xiongxianzhu 技术文档写作（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 修改保留现有版式，不自动添加或统一徽章：
- 检查头部：识别第一个 H1、简介、Logo、导航、已有居中容器和全部
img.shields.io图片 URL。 - 补充徽章：没有 Shields.io 徽章时，从仓库文件提取可靠事实，默认添加 2–4 枚技术栈、许可证、CI 或版本徽章；信息不足时减少数量，不虚构状态。
- 统一样式：将所有 Shields.io URL 的
style参数新增或替换为for-the-badge，保留其他参数、图片文本和链接目标。 - 居中头部：居中显示 Logo、项目主标题、简介和徽章区；复用已有
<div align="center">，避免嵌套或重复元素。 - 保护正文：在第一个 H2 前结束居中区域，不重排后续章节，不修改非 Shields 图片。
- 核对事实：许可证、CI、版本、覆盖率和下载量等徽章必须能从仓库或可信发布源验证；无法确认时不添加并说明缺失依据。
README 以外的文档不自动应用上述徽章规则，除非用户明确要求。
工作流程
- 定类型与读者：确认上述哪类文档，读者是新手/中级/专家。
- 套最小结构：新建文档从 templates.md 取必要章节；局部修改保留结构，只更新相关内容。README 专用规则仅按其适用条件执行。
- 填示例：相关操作需要演示时，提供可运行代码与预期输出；不为纯文字修改补造示例。
- 风格校对：按 style-guide.md 逐项过（语态、格式、术语、反模式）。
- 链接检查：检查新增或修改的链接与受影响锚点；不因局部修改重新检查无关外链。
验收（Gate）
按明确标准自检；复杂或高风险文档按需独立审查，不强制另找 Agent。
| 角色 | 说明 |
|---|---|
| 执行 | 主 Agent 按工作流程产出 |
| 验收 | 对照 style-guide.md 的反模式清单 检查相关项；新增或修改可执行示例时抽检代表性示例，无代码时跳过 |
验收不通过时：带着具体错误信息修正，进入下一轮（见下方停止条件）。
停止条件
| 类型 | 上限 |
|---|---|
| 自修订迭代 | 单文档最多 3 轮 |
| Token / 成本 / 时间 | 仅采用用户或工具已明确配置的上限，不自行编造 |
检查通过即结束，不为凑轮数重复修订。触达适用上限或同一外部阻塞重复出现时，停止该部分重试，说明未完成项，继续不受影响的工作。
参考文件
- references/templates.md — README、API 文档、教程、变更日志的最小结构与示例
- references/style-guide.md — 语态人称、格式约定、代码示例规范与常见反模式