用途
write-good-docs 用于撰写、编辑和审阅面向人类读者的技术文档，例如 README、指南、教程、操作说明（how-to）、API 或 CLI 参考、运行手册（runbook）、故障排查文档等。它的核心目标是：为某个具体读者服务，帮助其理解、决策或行动，尽量减少读者为读懂文档所付出的额外工作，而不是单纯压缩字数。
该技能只规范行文与结构，不负责确立产品事实。用户的指令和项目约定优先于其默认风格，但事实与安全不可被覆盖。
主要能力
- 按优先级处理取舍：事实与安全 > 读者结果 > 可查找性与顺序 > 清晰连贯的行文 > 一致性与细节。
- 区分三类工作：纯文字编辑（不新增主张、不改变技术含义）、基于证据的重写（仅在已识别来源能确立时增补或更正事实）、实质性建议（以建议形式给出，附假设与理由，不当作既有行为或已批准决策）。
- 保护精确内容：代码、命令、标识符、UI 标签、路径、URL、锚点、数值、单位、日期、版本、合同措辞和引用材料。
- 按证据匹配问题：需求说明“要求什么”，实现与观察说明其范围内的“行为”；已接受决策说明“决定了什么及原因”，提案不等于已接受决策；与版本匹配的官方依赖文档说明其文档化契约，而非某次部署的证明。
- 当需求与行为不一致时保留差异，不择一而抹去另一；区分观察或报告结果、预期行为、推断、提案与未知。
- 不编造看似有用的默认值、命令、机制、测量、引用或理由；缺失证据时限制陈述、标记占位或指出缺口。
- 文档工作不授权生产变更、破坏性命令、凭据使用或付费操作；未实际运行测试不得声称已运行。
使用方式
先阅读请求与所给材料，再提问。在代码仓库中，检查相关文档、代码、测试、配置与决策，但不无理由地盘点整个项目。明确读者、目的、假定知识、交付物，以及要求的范围、长度、方言和语气；从上下文推断常规默认值，仅在阻碍忠实结果时才追问。
根据读者需求选择文档形态：受控练习用教程；完成真实任务用操作指南；查询精确行为用参考；理解关系或取舍用解释；评估或记录选择用设计文档、RFC 或 ADR；诊断或安全操作用故障排查指南或运行手册；达到首个有用结果用 README 或入门指南；跨版本迁移用迁移指南或发布说明；理解证据及其含义用技术发现报告。
行文上：直接写主题，陈述发现、解释或指令，而非宣告文档、称赞方法或叙述作者的小心；让信心与证据匹配，把重要限制放在其所限定的主张旁边；检查事实之外的推论，受支持的观察不自动支持随后的“因此”“确保”“从而改善”等从句；连接想法，表达因果、对比、顺序与指代；具体但不编造细节；为特定目的使用结构，列表用于步骤、比较或查阅，段落用于连贯解释；保留有效的声音，不因风格偏好改写清晰准确的文字。
编辑与验证时保持局部：保留有用的声音、方言、标记、锚点、引用与历史；每处实质修改应解决面向读者的问题，而非让文字看起来像新写的；不要为匹配后续事件而重写已接受的历史 ADR 或发布说明。执行两项互补检查：删除检查（这段增加了什么，读者是否需要它在此处）与重建检查（读者必须推断、记住或查阅什么才能跟上下一点或下一步）。交付前检查受保护字面量与情态是否保留、引用是否仍支撑其主张、重要限制是否仍可见、程序在适用处是否安全可验证。
适用场景
适用于 README、指南、教程、操作说明、API 或 CLI 参考、运行手册、故障排查、设计文档、RFC、ADR、迁移指南、发布说明、技术发现报告等面向人类读者的技术文档的写作、编辑与审阅。也可在明确调用时用于电子邮件、报告段落等非虚构格式，但此时使用兼容规则，而非 README 或 RFC 模板，不因调用该技能就添加文档章节。
限制
该技能不确立产品事实，不授权生产变更、破坏性命令、凭据使用或付费操作；不编造默认值、命令、机制、测量、引用或理由；不把提案当作已接受决策；不因风格偏好改写清晰准确的文字；不使用词汇黑名单或标点测试作为质量或 AI 作者身份的代理；不添加虚假轶事、故意错误、俚语或随机不规则来让文字显得像人写的。默认风格为美式英语、句首大写标题、序列逗号、直接尊重的语气，但这些是默认值，不是好写作的普遍标准。