mcpField
G
generate-docs

generate-docs

github.com/gtrabanco开发2271 次安装今天更新
代码仓库

关于 generate-docs

generate-docs 是一项 Agent 技能，可将已完成的工作单元转化为项目文档站点中的增量开发指南。它要求先识别已配置的文档适配器，并在写入带来源信息的页面后执行验证，再报告结果。

主要功能

  1. 01根据已完成工作增量生成指南
  2. 02发现并解析文档适配器
  3. 03为生成页面添加来源信息
  4. 04执行文档构建或链接验证
  5. 05返回固定格式的完成报告

适用场景

  1. 01记录已交付工作单元的说明
  2. 02为指定项目区域生成文档
  3. 03将现有审查报告发布为文档页

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gtrabanco/agentic-workflow --skill generate-docs

安装后在 Claude Code 中输入/generate-docs确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
ADAPTER_DISCOVERY.md
ADAPTERS.md
GENERATION_PROCESS.md

详细介绍

生成文档

将某个工作单元产出的知识转化为开发者文档，让贡献者可以在项目文档网站上阅读——随着功能交付逐步生成，作为交付的副产品，使公开仓库的文档保持最新，而不是逐渐过时。提交说明了改了什么；指南则说明如何使用（“如何创建领域事件，以及应该在哪里注册其处理程序”）。

回合契约——结束回合前核验

✓ The docs adapter was resolved through the Step 0 detection checklist and the
  outcome (adapter name, or NOT CONFIGURED) is stated in the report
✓ Every generated/updated page is WRITTEN to disk (paths listed in the report)
  and carries the provenance frontmatter — or zero pages were written and the
  report says exactly why
✓ The verify step was RUN (docs build command or link check) and its result
  pasted — never assumed
✓ Artifact language: explicit user instruction > the project's declared docs
  language > English. The CONVERSATION language never decides
✓ The fixed report block is printed, then the closing `→ Next:` block, as the
  ABSOLUTE last output

准备结束回合时，如果有任何复选框尚未勾选，回合就尚未完成——请先完成缺失的项目（弱模型容易漏掉文档末尾的职责；此清单特意放在前面）。

适用场景

  • 完成一个工作单元后——如果项目声明了文档网站，execute-phase 会在收尾时推荐此技能：趁上下文还新鲜，记录该工作单元带来的变更。
  • 按需针对特定区域使用：generate-docs src/domain/events/。
  • --review——将最新的 review-change 报告导出为文档页面，以便人们在网站上审查发现的问题。
  • 不用于编写 SPEC／规划文档（plan-feature）、会话日志（log-session）或审查代码（review-change 负责生成发现结果；此技能仅按需发布已有报告）。

渐进式加载——解析文档路由

参考资料白名单严格限定为以下三个路径。按顺序读取；每项选定的资源均为规范依据，且距此入口仅一跳。

  1. 每次调用都要读取 适配器发现，并根据证据解析适配器。NOT CONFIGURED 表示停止写作。
  2. 仅适用于已配置的适配器：选择任何输出路径或格式前，先读取 适配器槽位。
  3. 读取 生成流程，并执行范围、增量处理、映射／审查、验证和报告步骤。

遇到 NOT CONFIGURED 后，不要加载步骤 2–3。缺少必需资源 → 停止；绝不要猜测适配器、输出路径或固定契约。

允许与禁止（固定清单——不得自行解读）

允许：

  • 在适配器的指南目录下编写／更新页面
  • 仅在适配器表要求时，更新适配器声明的手动侧边栏配置
  • 运行声明的文档构建／验证命令
  • 阅读任何内容（差异、代码、文档）

禁止——任何情况下都不允许，即使这样“会有帮助”：

  • 重新生成整个项目的文档（增量检查清单是唯一的页面选择依据）
  • 编辑源代码、测试或适配器声明的手动侧边栏配置以外的任何配置
  • 搭建文档网站（安装 Astro/Starlight、创建配置）
  • 在适配器内容目录之外编写内容；适配器声明的手动侧边栏配置除外
  • 编写缺少来源证明前置元数据的页面
  • 提交或推送（工作单元的工作流负责提交）

严格按以下格式返回

GENERATE DOCS — adapter: <starlight|docusaurus|markdown|NOT CONFIGURED> — scope: <scope>

| Page | Action | Source-unit | Subject paths |
|---|---|---|---|
| <content-path> | created|updated | <NN-slug> | <paths> |

Map: regenerated (<command>) | n/a — no map command declared | invalid output — <reason>
Review export: <page path> | not requested | no report available
Verify: <command + exit code | links checked: <n>, broken: 0 | n/a — not configured>
Pages: <n> written, <n> skipped by incrementality checklist
Decision: PASS | FAIL | NOT-CONFIGURED

仅当验证步骤未通过或编写的页面不得不回退时使用 FAIL；根据步骤 0.5 使用 NOT-CONFIGURED；其他情况（包括 0 个页面）均使用 PASS。

可移植性（适用于 Claude Code 以外的 Agent）

工作流才是契约；Claude Code 功能只是便利工具。如果 Agent 缺少某项功能，请使用后备方案——绝不要跳过该功能所支持的步骤：

  • 没有斜杠命令菜单——本技能提到 /<skill> 时，打开该技能的 SKILL.md，并在新的对话中严格遵循其中内容。
  • 没有逐技能的 model:/effort: 设置——编写指南是基于差异进行的结构化总结：中档模型就足够；绝不要使用低于能够准确理解项目语言的档位。
  • 不支持传递参数——在调用消息中说明范围（“为 01-generate-docs 生成文档”）；流程步骤 1 的顺序仍然适用。

与其他技能的关系

  • execute-phase 建议在单元收尾时使用此技能，前提是文档映射声明了文档站点（通过 → Next: 移交，绝不在本轮中组合执行）。
  • audit-docs 通过来源信息的 frontmatter 检测孤立或过时的生成页面。
  • init-workspace 记录此技能在步骤 0 中读取的 Docs site 声明。
  • 这不是审查：发现的问题和质量评估属于 review-change。

完成条件

  • 已提供有证据支持的适配器结果；每个选定页面都已写入来源信息 frontmatter；验证步骤已运行且通过（或已打印 NOT-CONFIGURED 报告，且未写入任何内容）。

  • 已返回固定报告块，然后：

    → Next: commit these pages with the unit's close-out (they ride the unit's PR)
  · unit already closed → commit as docs(<unit>): generated guides on the unit's branch
  · adapter NOT CONFIGURED → add the Docs site block to the documentation map, then re-run /generate-docs

评论

支持 Markdown