mcpField
M
make-documentation

make-documentation

github.com/callicrate开发11.5k 次安装24 周前更新
代码仓库

关于 make-documentation

此技能用于编写和审查项目文档，涵盖 README、运行手册和 Agent 工作流指南等。它按文档类型选择相应指南，并在适用时检查现有文档，强调依据来源且简洁的内容。

主要功能

  1. 01审查文档结构与缺漏
  2. 02按文档类型选择专用指南
  3. 03支持 README、运行手册和 Agent 文档
  4. 04使用检查清单审阅草稿
  5. 05避免不必要的图表和重复的事实源

适用场景

  1. 01起草或修订项目 README
  2. 02调查文档缺失或结构混乱
  3. 03编写特定环境的安装或操作指南
  4. 04准备 Agent 工作流文档

安装

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

$npx skills add https://github.com/callicrate/skills --skill make-documentation

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

包含的文件

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

agents/
openai.yaml
references/
ascii-art-standards.md
guide-access-runbook.md
guide-agent-ops-docs.md
guide-ai-ingestion.md
guide-architecture.md
guide-changelog.md
guide-ctf-handoff.md
guide-diagrams.md
guide-install-runbook.md
guide-notebook-documentation.md
guide-readme.md
guide-security-article.md
review-checklist.md
source-discovery-and-heading-stability.md
scripts/
audit_documentation.py

详细介绍

编写文档

适用场景

  • 编写或更新 README.md、架构说明、变更日志或发行说明
  • 在补充缺失文档前审核现有项目文档
  • 根据源材料起草面向客户的安全指南或涉及合作伙伴敏感信息的文章内容
  • 编写实时访问、复现、实验室接口、工作站/服务器或操作人员运行手册
  • 编写笔记本、生成的笔记本或生成表格的笔记本工作流文档
  • 编写适用于 WSL、本地环境、Docker 或特定环境的安装文档
  • 编写 Agent 操作手册、角色文件、同伴状态约定或供 AI 阅读的工作流文档
  • 仅在用户明确要求或项目已在使用图表文档时，才编写图表文档

不适用场景

  • 编写 API 参考文档
  • 创建或更新 AGENTS.md。请使用 agents-md，即使更广泛的请求还涉及其他文档也一样。
  • 在文字或表格足以表达时，默认不生成图表文件

工作流

  1. 对于新文档、大幅重写、文档迁移、缺失文档调查或结构不明的情况，运行 scripts/audit_documentation.py。对于明确的小幅编辑，直接检查目标文件和附近文档。
  2. 只生成用户请求和审核结果所需的交付内容。默认不要生成固定的文档套件。
  3. 按文档类型选择指南：README.md 使用 references/guide-readme.md，docs/architecture.md 或仓库中已有的同类文件使用 references/guide-architecture.md，用户说明文档供 Agent/AI 读取时使用 references/guide-ai-ingestion.md，Agent 使用的角色/工作流文档使用 references/guide-agent-ops-docs.md，实时访问、复现、操作人员、实验室接口或能力清单使用 references/guide-access-runbook.md，笔记本说明使用 references/guide-notebook-documentation.md，WSL/本地/Docker 安装文档使用 references/guide-install-runbook.md，涉及合作伙伴敏感信息的安全文章使用 references/guide-security-article.md，CHANGELOG.md 或发行说明使用 references/guide-changelog.md。如果 AGENTS.md 纳入范围，请改用 agents-md 处理该文件，而不要扩展此技能的范围。
  4. 仅当用户明确要求图表文档或项目已在维护这类文档时，才使用 references/guide-diagrams.md。
  5. 对于大型文档、迭代报告、功能清单、概念框架或证据审核修订，在编写前加载 references/source-discovery-and-heading-stability.md。
  6. 对于概念或策略文档，应在深入介绍架构前明确展示一个可用的首个工作流，让读者先执行一小部分内容，再理解整体模型。
  7. 确保内容简洁且有源材料依据。保留用户提供的术语，避免会改变领域含义或语感的泛化改写。
  8. 如果后续实现工作涉及相同的笔记本、文档或文件夹，请保留先前要求的文档。若无关的实现变更可能移除了已有文档，完成前应重新打开受影响的文档进行检查。
  9. 完成前，使用 references/review-checklist.md 检查结果。

反模式

  • 错误：根据生成的 README、审阅材料包、AI 评论或过时注释总结笔记本。正确做法：追踪可执行单元格、导入项、小组件、SQL、配置和输出，然后撰写简短说明。
  • 错误：移动文件夹后凭记忆编写文件夹契约文档。正确做法：检查目录树，并同时更新父级和子级文档。
  • 错误：在围绕实现编写文档时，重复创建验证器、架构、CLI、表清单或事实来源模块。正确做法：先查找现有的事实来源资源，并链接到它们。
  • 错误：让工作流文档绑定 VS Code、某个编辑器或某个 UI，除非用户明确提出要求。正确做法：说明与编辑器无关的起始状态和执行平面。
  • 错误：在人类读者的文档中保留 review packet、AI-generated summary 或 analysis artifact 等元标签，除非它们是必需的架构字段。正确做法：使用符合受众需求的自然小节名称。
  • 错误：将仅用于演示的标记或筛选器标为未来的产品接口。正确做法：将测试脚手架与持久的用户或 Agent 接口区分开。

确定性工具

工具使用时机结果
scripts/audit_documentation.py编写文档前需要确定性的清单当前状态的文档审计

参考资料

评论

支持 Markdown