doc-coauthoring

doc-coauthoring Skill 多维度简评

类别：沟通写作 / 协作 仓库：anthropics/skills 核心价值：让 Claude 成为你的主动引导型写作伙伴，而不是被动响应工具

一、核心定位与价值

普通的”让 AI 帮我写文档”流程是这样：

你："帮我写一份 RFC"
AI：（立刻写 1000 字文档）
你："不对，我想的不是这个..."（叹气）

doc-coauthoring Skill 把这个流程倒过来：

你："帮我写一份 RFC"
AI："好的。我们用 3 阶段工作流：
  1. 上下文收集（我问你答）
  2. 精炼结构（迭代每段）
  3. 读者测试（fresh Claude 检验）
  要不要试？"
你："试！"

它的核心创新是**“主动引导 + 3 阶段门禁”**——不是写完给你看，而是陪你一起写。

二、3 阶段工作流详解

阶段 1：上下文收集（Context Gathering）

目标：缩小”你知道 vs Claude 知道”的差距

1.1 触发条件

用户提到以下任一时启用：

• “write a doc”, “draft a proposal”, “create a spec”, “write up”
• “PRD”, “design doc”, “decision doc”, “RFC”

1.2 初始元问题

首先问 4 个元问题：

1. 文档类型？（技术规范 / 决策文档 / 提案 / RFC）
2. 主要受众？（工程师 / 高管 / 客户 / 跨团队）
3. 预期影响？（读了之后读者会做什么决策 / 行动）
4. 有模板吗？（公司模板 / 行业标准 / 自由发挥）

1.3 信息倾倒（Info Dumping）

鼓励用户一次性倾倒所有上下文：

• 项目/问题背景
• 团队讨论或共享文档
• 为什么不用替代方案
• 组织背景（团队动态、历史事件、政治因素）
• 已考虑的方案
• 成功指标/标准

关键：鼓励一次性分享，而不是挤牙膏。

1.4 追问（3-5 个一批）

围绕缺失信息追问：

• 不清晰的关键决策
• 缺失的约束
• 受众或目标不明确

1.5 模板处理

• 用户提供模板 → 用 Read 工具读取
• 用户给链接 → 用相应集成拉取
• 用户给文件 → 读取
• 已有共享文档 → 读取当前状态

1.6 图片处理

如果文档中插入图片但没有 alt-text：

• 警告：其他用 Claude 读这文档的人/AI 看不到
• 建议：让用户把图片贴到对话生成 alt-text

阶段 2：精炼与结构（Refinement & Structure）

目标：通过迭代逐段构建文档

2.1 提出大纲

基于文档类型提供常用结构模板：

技术规范（Technical Spec）：

1. 摘要 / TL;DR
2. 问题陈述
3. 目标 / 非目标
4. 提议方案
5. 备选方案
6. 风险与缓解
7. 落地计划
8. 开放问题

决策文档（Decision Doc / ADR）：

1. 背景
2. 决策
3. 理由
4. 备选方案
5. 后果

提案（Proposal）：

1. 背景
2. 提案
3. 收益
4. 成本
5. 风险
6. 下一步

2.2 增量起草

不要一次性写完整篇，而是：

• 写一段（或部分段）
• 询问反馈
• 整合修改
• 移至下一段

关键原则：

• ✅ 让用户参与，但不要每句都询问批准
• ✅ 提供具体草稿，让用户能反应
• ❌ 不要在没共识的情况下继续写

2.3 保持一致性

整个起草过程中：

• 术语统一
• 叙事与目标/受众保持一致
• 跟踪开放问题
• 发现不一致时主动指出并建议修复

阶段 3：读者测试（Reader Testing）

目标：确保文档对没有上下文的人也有效

3.1 测试方法

当文档草稿足够好时：

1. 让用户把文档粘贴到全新的 Claude 会话（或模拟这个效果）
2. 指示这个”新读者”：
   • 总结文档
   • 指出不清楚的部分
   • 列出仍有的问题
   • 点出作者似乎在做的假设

3.2 修复盲点

根据读者反馈：

• 补充缺失的上下文
• 澄清混乱的段落
• 让假设显式化
• 改进结构/流程

3.3 重复测试

高风险文档重复测试直到满意。

三、为什么这个 Skill 如此重要

3.1 上下文传递效率

普通模式：作者 → 文档 → 读者 → 多次询问作者 → 最终理解 本 Skill 模式：作者 + Claude 协作 → 文档 → 读者一次理解

节省时间：减少 50% 的来回沟通

3.2 文档质量提升

3 阶段强制覆盖了最常缺失的：

• 受众明确化
• 上下文充分
• 读者测试验证

3.3 审阅者信心

读者读到的不再是”作者自己懂但写不清”的文档，而是经过 fresh reader 测试的可读文档。

四、6 大实战场景

场景 1：技术 RFC

用 doc-coauthoring 帮我写一份"我们从 MongoDB 迁移到 PostgreSQL"的 RFC。

Skill 自动流程：

1. 问你 4 个元问题（文档类型、受众、影响、模板）
2. 让你倾倒上下文（当前 MongoDB 痛点、团队经验、迁移成本）
3. 追问（迁移时间、兼容性、回滚方案）
4. 提出 RFC 大纲
5. 逐段起草
6. 读者测试
7. 输出最终版

场景 2：PRD

用 doc-coauthoring 帮我写"用户积分系统"的 PRD。

Skill 关键引导：

• 追问：积分怎么获取 / 消耗？过期规则？防刷机制？
• 决策记录：为什么这套规则？
• 受众：PM / 工程师 / 高管 / 客服

场景 3：决策记录（ADR）

用 doc-coauthoring 帮我做 ADR-001："为什么我们用 PostgreSQL 而不是 MongoDB"。

Skill 重点：

• 备选方案对比
• 决策理由的可信度
• 后果的清晰描述

场景 4：事故复盘（Postmortem）

用 doc-coauthoring 帮我写这次线上事故的 Postmortem。

Skill 强调：

• 时间线
• 根因（不只是症状）
• 影响范围（量化）
• 短期修复 + 长期改进
• 不甩锅文化

场景 5：入职文档

用 doc-coauthoring 帮我写"新成员入职指南"。

Skill 突出：

• 受众：新人（无背景知识）
• 关键决策：为什么这样做
• 工具 / 资源 / 联系人

场景 6：客户提案

用 doc-coauthoring 帮我给 XX 客户写一份技术方案提案。

Skill 关键：

• 客户痛点（而非你的能力）
• 投资回报（ROI）
• 风险与缓解
• 决策路径

五、安装

5.1 命令

# Claude Code
/plugin install example-skills@anthropic-agent-skills

# 通用
npx skills add anthropics/skills --skill doc-coauthoring

5.2 触发示例

用户：用 doc-coauthoring 帮我写份 API 设计文档
用户：我要起草一份关于缓存策略的提案
用户：帮我创建产品 PRD
用户：用 doc-coauthoring 工作流起草一份事故复盘

六、5 大常见错误

错误 1：跳过阶段 1

错误：直接给一堆上下文，让 Claude 开始写
正确：让 Skill 主动引导提问

错误 2：每句都要批准

错误：每写一句就问"这样行吗？"
正确：写完整段才询问反馈

错误 3：忽略受众

错误：不区分读者，让 Claude 写得很"AI 范"
正确：明确受众，调整语言深度

错误 4：不更新就停

错误：写完一段就停
正确：保持一致性，跨段追踪

错误 5：跳过读者测试

错误：写完直接发布
正确：fresh Claude 测试，找出盲点

七、5 条反合理化

八、与其他 Skill 配合

九、与其他 Skill 对比

十、Q&A

Q: 适合所有文档吗？ A: 高风险、需要审阅的文档（RFC/PRD/ADR）。简短通知用 internal-comms。

Q: 3 阶段可以跳过吗？ A: 紧急场景可压缩阶段 2，但仍要阶段 1 和 3。

Q: 文档要保密怎么办？ A: Claude 不会上传任何内容，但敏感场景请用企业版或本地部署。

Q: 多语言支持？ A: 文档语言由用户决定，Skill 支持任意语言。

Q: 多人协作时呢？ A: 一人主导，其他人审阅。可多人轮流当”读者测试”角色。

Q: 输出格式？ A: Markdown / 任何文本格式。也支持 Word / PDF（链式调用 docx / pdf Skill）。

Q: 需要付费 Claude 吗？ A: 建议 Sonnet 4.6+ 或 Opus 4.6+。

十一、6 条实战技巧

1. 明确退出机制：用户可以说”我自己写”，跳过整个流程
2. 保持耐心：阶段 1 问得越多，阶段 2 写得越好
3. 批量化追问：一次问 3-5 个问题，不要一个一个
4. 提供模板：模板能让阶段 2 更快
5. 关注”假设”：读者测试找出的最大问题是隐藏假设
6. 建立文档库：团队多次使用积累出”文档模式库”

十二、总结

核心价值：

• 把”AI 写文档”升级为”AI 协作写文档”
• 3 阶段门禁确保读者能懂
• 强制结构化降低沟通成本

适用人群：

• 技术负责人（写 RFC / ADR）
• 产品经理（写 PRD）
• 团队领导（写决策文档）

投入产出比：⭐⭐⭐⭐⭐（5/5）—— 高频文档协作场景必装。

配套文档：internal-comms 通知

参考资料

1. anthropics/skills - doc-coauthoring
2. Google Technical Writing Courses
3. Write the Docs 社区
4. Mozilla 技术写作指南