---

name: docs-writer description: 撰写或修改 README、技术教程、API 说明与变更日志。局部修改保留现有结构；新建 README 或明确要求时处理头部与徽章。不因仅提到文档名称而触发。

技术文档写作（docs-writer）

按五原则与四类文档最小结构，产出可扫描、带可运行示例的 Markdown 文档。规则与模板见 references/style-guide.md 与 references/templates.md。

何时使用

• 撰写或修订 README、项目说明、安装与快速上手
• 文档化 API、函数、CLI 参数、配置项
• 编写教程、上手指南、分步教学
• 撰写变更日志、发布说明、迁移指引
• 解释架构、设计决策、复杂技术概念

何时不使用

• 写业务代码注释、commit message、PR 描述 → 直接写，不用此 skill
• 接口契约的强约束规范 → 用 api-docs
• PRD / 需求文档 → 用 prd-creator

写作五原则

原则	要点	反例
目标先行	先答"为什么用"，再讲"怎么用"	开头堆功能列表
示例胜过描述	操作性概念按需配可运行代码与预期输出	关键操作缺少示例
渐进披露	Quick Start 在前，深潜在后；复杂主题用链接隔离	一上来铺全部配置
可扫描	描述性标题、3 项以上用列表、代码加语言标签	大段无层级散文
主动 + 现在时	"运行 X 返回 Y"，不是"X 被运行后 Y 被返回"	被动语态连串

文档类型选择

按读者意图选型，而非按内容罗列：

读者想…	文档类型	最小结构见
评估/上手项目	README	README 模板
调用接口/函数	API 文档	API 文档模板
跟着做完成一个任务	教程	教程模板
了解版本变化	变更日志	变更日志模板
理解概念/设计	解释性文档	用 README 或独立文章，遵循同样五原则

README 专用规则

仅在新建 README，或用户明确要求调整头部与徽章时，读取 README 模板 和 README 头部与徽章，执行与请求相关的步骤。其他 README 修改保留现有版式，不自动添加或统一徽章：

1. 检查头部：识别第一个 H1、简介、Logo、导航、已有居中容器和全部 img.shields.io 图片 URL。
2. 补充徽章：没有 Shields.io 徽章时，从仓库文件提取可靠事实，默认添加 2–4 枚技术栈、许可证、CI 或版本徽章；信息不足时减少数量，不虚构状态。
3. 统一样式：将所有 Shields.io URL 的 style 参数新增或替换为 for-the-badge，保留其他参数、图片文本和链接目标。
4. 居中头部：居中显示 Logo、项目主标题、简介和徽章区；复用已有 <div align="center">，避免嵌套或重复元素。
5. 保护正文：在第一个 H2 前结束居中区域，不重排后续章节，不修改非 Shields 图片。
6. 核对事实：许可证、CI、版本、覆盖率和下载量等徽章必须能从仓库或可信发布源验证；无法确认时不添加并说明缺失依据。

README 以外的文档不自动应用上述徽章规则，除非用户明确要求。

工作流程

1. 定类型与读者：确认上述哪类文档，读者是新手/中级/专家。
2. 套最小结构：新建文档从 templates.md 取必要章节；局部修改保留结构，只更新相关内容。README 专用规则仅按其适用条件执行。
3. 填示例：相关操作需要演示时，提供可运行代码与预期输出；不为纯文字修改补造示例。
4. 风格校对：按 style-guide.md 逐项过（语态、格式、术语、反模式）。
5. 链接检查：检查新增或修改的链接与受影响锚点；不因局部修改重新检查无关外链。

验收（Gate）

按明确标准自检；复杂或高风险文档按需独立审查，不强制另找 Agent。

角色	说明
执行	主 Agent 按工作流程产出
验收	对照 style-guide.md 的反模式清单 检查相关项；新增或修改可执行示例时抽检代表性示例，无代码时跳过

验收不通过时：带着具体错误信息修正，进入下一轮（见下方停止条件）。

停止条件

类型	上限
自修订迭代	单文档最多 3 轮
Token / 成本 / 时间	仅采用用户或工具已明确配置的上限，不自行编造

检查通过即结束，不为凑轮数重复修订。触达适用上限或同一外部阻塞重复出现时，停止该部分重试，说明未完成项，继续不受影响的工作。

参考文件

• references/templates.md — README、API 文档、教程、变更日志的最小结构与示例
• references/style-guide.md — 语态人称、格式约定、代码示例规范与常见反模式