ogt-docs-create

📝 Docs-First 文档规范化创建中枢

基于 docs-first 方法论的标准化文档创建工具,通过结构化模板与自动化工作流,帮助团队建立统一的任务、规则与特性定义规范。

收藏
14.3k
安装
3.2k
版本
v1.0.0
CLS 安全性认证2026-05-20
点击查看完整报告 >

使用说明

核心定位与用法

ogt-docs-create 是面向 docs-first 系统的文档创建入口技能,采用智能路由模式将不同类型的文档创建请求分发至专门的子技能处理。用户遵循"识别类型→创建文件夹→复制模板→填充内容→添加信号文件→验证结构"六步标准化工作流,可在 docs/todo/pending/、docs/define/features/、docs/rules/code/ 等指定目录生成结构化的文档实体。

系统强制使用 slug 命名规范(小写、连字符连接、无特殊字符),并为每种文档类型提供严格的模板体系:任务文档需包含 Summary、Objectives、Acceptance Criteria 等必填章节;规则文档需定义 Rationale 和 Enforcement 机制;特性文档需明确 Scope 和 Success Metrics。通过 .version、.priority、.enforced_by 等信号文件实现元数据标记,支持版本追踪和优先级管理。

显著优点

标准化与一致性:提供覆盖任务、特性、业务定义、代码规范、营销内容等十余种文档模板,确保团队产出格式统一,降低沟通成本。批量创建功能支持通过单条命令生成特性定义及其关联的设计、开发、测试、文档任务,显著提升效率。

工程化集成:与开发工作流深度结合,代码规则可直接关联 ESLint 等工具配置(通过 .enforced_by 信号文件),实现"文档即规范"。严格的验证机制包括文件存在性检查、必填章节校验,保障文档完整性。

结构化知识管理:采用文件夹即实体的设计理念,每个文档作为独立文件夹存在,配合信号文件系统,便于后续自动化处理和知识检索。

潜在局限

学习曲线较陡:用户需理解 docs-first 方法论、slug 命名规范、信号文件系统等专有概念,初期上手成本高于普通文档工具。模板结构相对僵化,预设的章节格式(如规则文档的 MUST/SHOULD/MAY 语法)可能不完全适配所有团队习惯,定制化修改需手动调整模板文件。

操作依赖人工:虽然提供丰富的 bash 示例脚本,但实际创建过程仍需开发者手动执行命令或复制内容,缺乏 IDE 插件或 GUI 界面的交互便捷性,在大型批量创建场景下仍有一定操作负担。

维护稳定性:作为 T3 来源的个人开发者项目,长期维护持续性、社区生态丰富度及企业级技术支持弱于商业方案或顶级开源基金会项目。

适合群体

该技能特别适合采用文档驱动开发(Documentation-Driven Development)的技术团队,尤其是需要严格规范定义的中大型研发团队。产品经理可利用特性定义模板管理需求范围和 MVP 阶段划分;技术负责人可通过代码规则模板建立团队编码规范并关联自动化检查;运营人员可使用社交内容模板标准化营销物料输出。对于重视知识沉淀、追求流程标准化、需要维护复杂 CHANGELOG 和精细化任务追踪系统的软件项目尤为适用。

使用风险与注意事项

尽管该 skill 本身为纯 Markdown 文档类型,无代码执行风险,但用户直接复制 bash 示例命令(如 mkdir、cp、cat)操作文件系统时存在误操作风险,建议在执行前确认目标路径避免文件覆盖。模板中的 TODO 占位符若未完全替换可能导致文档信息不完整,影响后续自动化流程。信号文件(如 .priority、.enforced_by)若配置错误可能导致文档状态识别异常。此外,由于来源为个人开发者(T3),建议企业用户在使用前审查模板内容是否符合内部安全合规要求,并考虑 fork 后自主维护以保障长期稳定性。

安全解读

核心用法

ogt-docs-create 是面向文档优先(docs-first)开发体系的根级创建技能,采用"路由-模板-信号"三层架构:

1. 智能路由层:根据目标文档类型自动分发至6大子技能——任务创建(ogt-docs-create-task)、定义管理(ogt-docs-define)、规则建立(ogt-docs-rules)、社交内容(ogt-docs-create-social)、变更日志(ogt-docs-changelog)

2. 模板驱动层:内置Task/Feature/Definition/Rule四大标准模板,强制包含Summary、Objectives、Acceptance Criteria等结构化字段,确保文档一致性

3. 信号元数据层:通过.version.priority.enforced_by等隐藏文件实现机器可读的状态追踪,支持优先级分级(critical/high/medium/low)和规则执行标记

显著优点

  • 零代码执行风险:100% Markdown文档结构,无可执行代码块,通过CLS-Certify六维扫描(静态/动态/依赖/网络/隐私/威胁)
  • 标准化工作流:强制slug命名规范(小写+连字符+30字符限制)、统一目录结构、批量创建脚本支持
  • 工程化文档管理:将传统Wiki升级为版本化、可追踪的代码级文档体系,支持MVP阶段拆分和任务依赖映射

潜在局限

  • 生态锁定:深度绑定openclaw/docs-first特定目录约定,迁移成本较高
  • 学习曲线:需理解信号文件体系和子技能路由逻辑,对非技术写作者不够友好
  • 无可视化界面:纯CLI/bash工作流,缺乏GUI支持

适合人群

  • 采用Docs-as-Code实践的技术团队
  • 需要严格文档版本控制的合规驱动型组织
  • 追求Feature/Rule/Task traceability的敏捷开发团队

常规风险

  • 误用风险:bash示例代码块(如批量创建脚本)若被直接复制执行可能产生意外目录结构,需人工审查后使用
  • 维护者依赖:当前License未明确声明,长期维护稳定性依赖eduardou24个人

ogt-docs-create 内容

手动下载zip · 3.8 kB
SKILL.mdtext/markdown
请选择文件