前言¶
写文档是开发者绕不开的高频任务：技术方案要落成 spec，架构取舍要写成 decision doc，新功能上线前还要补 PRD 或 RFC。这类文档的共同难点不在「能不能写」，而在「写完之后读者能不能看懂」——作者脑子里有上下文，读者没有；你省略的背景，别人读不懂；你默认团队都懂的术语，新人一头雾水。
直接让 AI 一次性生成全文，往往得到结构整齐、内容却空洞的「模板文」；自己从零起草，又容易陷进细节、漏掉关键约束。Anthropic 在官方 Skills 仓库里提供的 doc-coauthoring，走的就是另一条路：不替你把文档一次写完，而是用「上下文收集 → 分节打磨 → 读者测试」三阶段流程，带着你共创一份真正可交付的结构化文档。本文基于官方 SKILL.md 与仓库说明，介绍这个 Skill 的定位、能力与用法。
这是什么¶
doc-coauthoring 是 Anthropic 维护的 Agent Skill，仓库地址：
https://github.com/anthropics/skills/tree/main/skills/doc-coauthoring
它遵循通用的 SKILL.md 格式，可在 Cursor、Claude Code、Claude.ai 等支持 Agent Skills 的环境中使用。Skill 的核心定位是：当用户要写文档、提案、技术规格、决策文档等结构化内容时，Agent 主动引导用户走完一套可重复的共创流程，而不是自由发挥式地「帮我写一篇」。
官方 description 概括了三个目标：高效传递上下文、通过迭代 refine 内容、在交给真实读者之前验证文档是否可读。
核心功能与亮点¶
1. 三阶段工作流¶
整个 Skill 把文档写作拆成三个阶段，Agent 会按顺序引导，用户也可随时选择跳过、自由写作：
- Context Gathering（上下文收集）：先问文档类型、受众、预期影响、模板约束等元问题，再鼓励用户「信息倾倒」——背景、团队讨论、未选方案的原因、组织约束、时间线、技术依赖等，不必先整理格式。Agent 据此生成 5–10 条澄清问题，补齐理解缺口。
- Refinement & Structure（打磨与结构化）：按章节逐节推进。每节经历「澄清问题 → 头脑风暴 5–20 个候选点 → 用户筛选保留/删除/合并 → 缺口检查 → 起草 → 迭代修改」的循环，优先从不确定性最高的章节（如决策文档的核心方案、spec 的技术方案）开始，摘要类章节通常放最后。
- Reader Testing（读者测试）：用「没有参与共创上下文」的全新 Claude 实例，模拟真实读者提问，检查文档是否存在作者视角的盲区。在 Claude Code 等支持 sub-agent 的环境中可自动执行；否则提供手动测试步骤。
2. 自动触发与可选流程¶
Skill 会在用户提到以下场景时主动提供结构化流程：
- 「write a doc」「draft a proposal」「create a spec」「write up」等写作意图
- PRD、design doc、decision doc、RFC 等具体文档类型
- 用户明显在启动一项较大的写作任务
Agent 会先解释三阶段流程，询问用户是否采用；若用户拒绝，则退回自由写作模式。
3. 分节共创，而非一次性生成¶
Stage 2 的设计是 doc-coauthoring 区别于普通「帮我写文档」提示词的关键：
- 先搭文档骨架（artifact 或本地 Markdown 文件，各节占位
[To be written]） - 每节单独头脑风暴，用户用简短指令筛选（如「保留 1,4,7；删除 3，与 1 重复」）
- 起草后用
str_replace做局部修改，避免整篇重刷 - 连续三轮无实质改动时，Agent 会主动问「能否再删减而不丢信息」
这种方式强迫作者在每个章节做取舍，减少 AI 自说自话的「废话填充」。
4. 读者测试：在发出去之前找盲区¶
Stage 3 的思路很务实：文档最终会被别人（或别的 AI）阅读。测试时会：
- 预测读者可能提出的 5–10 个问题
- 用无上下文的 Claude 仅依据文档内容作答
- 额外检查歧义、隐含前提、内部矛盾
若 Reader Claude 答错或卡住，流程会回到 Stage 2 修补对应章节，直到测试通过。
5. 外部上下文接入（可选）¶
若环境支持 Slack、Teams、Google Drive 等 MCP 连接器，Skill 会尝试从团队频道、共享文档拉取背景；无集成时则建议用户粘贴内容或启用 Claude Connectors。这部分能力依赖具体工具环境，并非所有平台都具备。
安装与启用¶
方式一：Cursor 项目级安装（手动）¶
在项目根目录创建 Skill 目录并下载官方文件：
mkdir -p .cursor/skills/doc-coauthoring
curl -o .cursor/skills/doc-coauthoring/SKILL.md \
https://raw.githubusercontent.com/anthropics/skills/main/skills/doc-coauthoring/SKILL.md
Cursor 启动时会扫描 .cursor/skills/ 下的 SKILL.md；也可在 Agent 对话中输入 /doc-coauthoring 手动调用。
方式二：skills CLI 安装¶
skills.sh 收录了该 Skill，可用命令行拉取：
npx skills add https://github.com/anthropics/skills --skill doc-coauthoring
安装目标路径因 CLI 配置而异，常见为项目的 .cursor/skills/ 或 .agents/skills/。
方式三：Claude Code 插件¶
Anthropic 官方 README 提供了 Claude Code 安装方式：
/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills
安装 example-skills 插件后，doc-coauthoring 随示例技能集一并可用；在对话中提及文档写作需求即可触发，或明确说明「使用 doc-coauthoring 流程」。
方式四：Claude.ai¶
Anthropic 示例 Skill 对已付费 Claude.ai 用户部分开放；自定义 Skill 的上传与启用方式见官方文档 Using skills in Claude。
典型用法示例¶
Skill 无需额外配置文件，启用后通过自然语言触发。下面是一次技术决策文档（decision doc）的常见交互路径：
第一步：发起任务
我要写一份 decision doc，说明为什么把缓存从 Redis 迁到 Valkey，受众是后端团队和 SRE。
用 doc-coauthoring 流程，我们按阶段来。
Agent 会先介绍三阶段流程，确认是否开始 Stage 1。
第二步：上下文收集（Stage 1）
用户可用 shorthand 回答元问题，再倾倒背景：
1. decision doc
2. 后端 + SRE，也要给新同学看
3. 希望读完能同意迁移方案并知道回滚条件
4. 公司有 ADR 模板，我稍后贴
5. Q4 前必须完成，旧 Redis 集群 license 到期
背景：当前 Redis 6.x 单集群 3 主 3 从，峰值 QPS 8 万……（省略）
未选方案：继续续费 Redis Enterprise，成本是 Valkey 的 3 倍……
Agent 会追问 5–10 条澄清问题，例如迁移窗口、数据一致性要求、谁有否决权等。
第三步：分节打磨（Stage 2）
以「核心决策」章节为例，Agent 会：
- 问该节要覆盖哪些要点
- 列出 5–20 条候选论点（成本、兼容性、运维负担、社区支持等）
- 等待用户筛选：
保留 2,5,8,11；删除 6（SRE 已知）；合并 3 和 4 - 起草该节，请用户指出修改点：
第三段太抽象，补一个 QPS 对比数字 - 局部修改后进入下一节
全部章节完成后，Agent 会通读全文，检查冗余、矛盾与「空话」。
第四步：读者测试（Stage 3）
在 Claude Code 中，Agent 可能自动启动 sub-agent，用如下问题测试：
- 「这份文档推荐的最终方案是什么？」
- 「回滚条件是什么？」
- 「为什么不继续用 Redis Enterprise？」
若 Reader Claude 对「回滚条件」答得含糊，流程会回到 Stage 2 补写「风险与回滚」章节。
在 Cursor 等无 sub-agent 的环境，官方 Skill 会给出手动步骤：新开对话、粘贴文档、逐条提问并核对答案。
适用场景与注意事项¶
适合谁、什么场景：
- 需要写 技术规格（spec）、架构决策（ADR/decision doc）、RFC、PRD、设计文档 等结构化长文
- 文档要交给多人评审，或会被粘贴进 AI 工具二次解读
- 作者上下文复杂、一次性说不清，希望 Agent 通过提问帮自己理清结构
- 团队有固定模板，但希望内容质量可控、而非套模板填空
限制与注意：
- 这是 流程型 Skill，不是文档模板库；产出质量仍取决于你提供的上下文与每轮筛选反馈
- 三阶段完整走一遍耗时较长；Skill 允许跳过阶段或自由写作，赶 deadline 时可只用 Stage 1 收集上下文
- Reader Testing 在 Claude Code 体验最好；Cursor 等环境需手动开新对话测试
- 外部文档/频道拉取依赖 MCP 或 Connectors，本地纯文本环境需自行粘贴材料
- Anthropic README 注明：仓库 Skill 仅供演示与教育，生产环境使用前请自行充分验证
小结¶
文档写作难，往往难在「作者视角」与「读者视角」之间的鸿沟。doc-coauthoring 的价值，是把这份鸿沟拆成可执行的三个阶段：先把上下文倒干净，再分节共创、逐段打磨，最后用无记忆的 Reader Claude 做验收。对经常要写 spec、决策文档、提案的开发者来说，它提供的是一套可复用的 Agent 引导流程，而不是又一篇生成即弃的 AI 草稿。
官方 Skill 与完整工作流说明：
https://github.com/anthropics/skills/tree/main/skills/doc-coauthoring
