前言¶
寫文檔是開發者繞不開的高頻任務：技術方案要落成 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
