doc-coauthoring Agent Skill 实操:陪 AI 三阶段写完一篇别人能看懂的文档
技术文档写完没人看得懂,多数不是文笔问题,是作者脑内的上下文没卸载出来——你觉得显然的东西,读者一无所知。anthropics/skills 仓库里的 doc-coauthoring 技能就是冲这个来的:它不替你写文档,而是把协作写作拆成三段流水线(收集上下文、逐节打磨、读者测试),让 Claude 以「主动引导者」的身份陪你走完。这个技能目录下只有一个 15.8KB 的 SKILL.md,没有任何脚本和 API——整条流水线是纯提示工程实现的,这篇把它的每一步拆开讲清楚(Claude Code 产品页)。
什么时候它会自己跳出来
技能靠 SKILL.md 的 description 字段触发,原文列了三类信号:
User mentions writing documentation: "write a doc", "draft a proposal", "create a spec", "write up
User mentions specific doc types: "PRD", "design doc", "decision doc", "RFC"
User seems to be starting a substantial writing task—— skills/doc-coauthoring/SKILL.md "Trigger conditions"
命中之后不是直接开写,而是先做一个「Initial offer」:Claude 会解释这套三阶段流程是什么、为什么值得走(原文的逻辑是 ensure the doc works well when others read it,包括别人把文档粘给 Claude 读的场景),然后问你要走结构化流程还是自由发挥。你说自由发挥,它就退出技能按普通方式写——整个技能是可选的,不绑架你的工作习惯。这个设计值得留意:流程类技能最容易犯的错是「不分场合硬上流程」,官方用一句 Ask if they want to try this workflow or prefer to work freeform 把选择权留给了用户。
装上它
和 docx 技能同仓同装法(详细步骤见 docx 技能那篇):Claude Code 里 /plugin marketplace add anthropics/skills 注册官方市场,这个技能在 example-skills 包里;Claude.ai 付费用户开箱即用;API 用户走 Skills API。装完不用记任何命令,说出 "draft a proposal" 这类话它自己会接。
第一阶段:把你脑子里的东西倒出来
SKILL.md 给这阶段定的目标只有一句话,原文是 Close the gap between what the user knows and what Claude knows——把你知道而它不知道的东西搬过去。动作分三拍。
先是五个元问题,原文照录:文档类型(技术规格/决策文档/提案)、主要读者是谁、读完要达成什么效果、有没有模板或格式要求、还有什么约束。官方特意说明回答可以用速记,怎么省事怎么来。
然后是 Info Dumping:官方鼓励你把所有背景一口气倒出来,并点名欢迎这些内容——项目背景、团队讨论记录、为什么没采用备选方案、组织环境(团队动态、历史事故、政治因素)、时间线压力、技术架构依赖、干系人的顾虑。原话是 Advise them not to worry about organizing it - just get it all out:不用整理,倒在桌上就行,整理是 AI 的活。
你倒完之后,Claude 生成 5-10 个编号追问,专挑信息缺口。什么时候算收集够了?技能给了个很实在的退出条件:当追问已经能问到边界情况和权衡取舍、而不再需要解释基础知识时,说明它跟上你了。
信息源方面技能分了三档。你提到团队频道或共享文档时,如果宿主装了集成(原文点名 Slack、Teams、Google Drive、SharePoint 及其他 MCP 服务器),Claude 会告知后直接去读;没装集成时它会明说拿不到,建议你去 Claude 设置里开 connectors,或者直接把内容贴进来。遇到它不认识的实体或项目,官方要求先问一句「要不要让已连接的工具去查一查」、等你确认再动——上下文收集阶段不许 AI 自作主张到处翻。在 Claude.ai 里一个集成都没有的极端情况,技能也写了降级话术:提示你可以启用连接器,从消息应用和文档存储直接拉上下文。

三阶段流水线:每阶段的目标引文均出自 SKILL.md 原文
第二阶段:一节一节过,每节六步
结构先立起来:所有章节带占位文本([To be written]),从「未知最多」的那节开始填——决策文档先写核心提案,规格文档先写技术方案,摘要类永远留最后。如果你连需要哪些章节都不确定,它会按文档类型建议 3-5 个章节再和你确认。

每节完整走一遍六步,官方给的取舍回复格式示例一并附在图中
六步里的第 3 步是这套流程的灵魂:你对头脑风暴清单做取舍时要带理由,官方连回复格式都给好了示例,原文照录:
Keep 1,4,7,9
Remove 3 (duplicates 1)
Remove 6 (audience already knows this)
Combine 11 and 12—— skills/doc-coauthoring/SKILL.md "Step 3: Curation"
带理由是为了让 AI 学到你的判断标准,后面的章节提问和脑暴会越来越准。成稿和修改全部用 str_replace 做点状替换,官方明确要求 never reprint the whole doc——每次改动只动该动的地方,你 review 时不用重读全文。
载体有两种:宿主支持 artifacts(如 Claude.ai)就建 artifact 文件双方共编;没有就在工作目录建 markdown 文件(decision-doc.md、technical-spec.md 这类命名)。写到 80% 时有一个全文回读检查,原文列了四项:跨章节的流畅与一致、冗余与自相矛盾、有没有 "slop"(原文用词,指套话凑数段)、每句话是否都承载信息。
第三阶段:让一个「没参与写作的 Claude」来挑刺
这是整个技能最有想法的一段。测试对象不是你(你已经被写作过程污染了,看不出问题),而是一个全新的、完全没读过这段对话的 Claude 实例。怎么跑取决于宿主:

Claude Code 里全自动,Claude.ai 网页版需要手动开新对话当「读者」
Claude Code 有 sub-agents,测试直接跑不用你参与:每个预测的读者问题唤起一个只拿到文档内容和问题的子代理,汇总答对答错,再查一轮歧义、错误假设和内部矛盾。网页版没有这个能力,官方给的替代流程是手动开新对话、粘贴文档、逐个提问,并且要求「读者 Claude」除了答案还要交代三件事:哪里有歧义、文档默认读者已经知道什么、有无内部矛盾。
退出条件同样写得清楚:当读者 Claude 能连续答对问题、且不再暴露新的缺口或歧义,文档才算就绪。
收尾与一段容易被忽略的 Tips
测试通过后技能还坚持一件事:最终读一遍的责任在你。原文让 AI 明确说出 they own this document and are responsible for its quality,并建议读者自查事实、链接、技术细节,确认文档达成了最初想要的 impact。收尾建议里有两条挺实用——把协作对话链接放进附录(读者能看到文档是怎么长出来的)、用附录承载深度内容避免正文膨胀,以及收到真实读者反馈后回来更新。
SKILL.md 末尾的 Tips 段落值得单独读一遍,几条都反直觉:遇到想跳阶段的用户,先确认再放行,不强留;用户表现出不耐烦时,承认流程确实花时间并主动提议提速,而不是假装没看见;上下文缺口出现一个问一个,不许攒着。Artifact 管理那条最具体:脑暴清单永远只在对话里流转,不写进 artifact——列表是过程产物,进文档就是垃圾。
它的边界在哪
这个技能管「写什么、怎么组织」,不管两件事:文档格式(生成 .docx 交给同仓的 docx 技能,见那篇教程);写作中引用的 API 细节是否准确(claude-api 技能把官方手册挂进上下文,教程在这)。三个技能是互补关系,一次真实写作里可以同时在场。
局限也说透:流程深度依赖宿主能力——sub-agents 决定读者测试是自动还是手动,artifacts 支持决定协作载体,集成连接器(Slack/Teams/Drive)决定第一阶段的上下文能不能直接拉取,没有集成时官方的降级方案是让你自己开 connectors 或直接粘贴内容。另外整份 SKILL.md 是纯指令文本,没有可独立调用的脚本,离开 Claude 这套流程不成立——想在自己的 Agent 里复用,得把三阶段重新实现一遍。
仓库 README 的免责声明同样适用:技能仅供演示与教学,实际产品里的行为可能与仓库版有差异,关键文档流程先在自己环境里验证。
本文流程与引文依据 anthropics/skills 仓库 skills/doc-coauthoring/SKILL.md 整理,blockquote 内均为原文摘录,版权归原作者所有。教程目录:总纲