Doc Coauthoring Skill 详解
结构化的文档协作写作工作流
基本信息
| 属性 | 值 |
|---|---|
| 名称 | doc-coauthoring |
| 类别 | 工作流程 |
| 输出格式 | 结构化文档 |
| 许可证 | Apache 2.0 |
yaml
name: doc-coauthoring
description: Guide users through a structured workflow for co-authoring
documentation. Use when user wants to write documentation, proposals,
technical specs, decision docs, or similar structured content. This
workflow helps users efficiently transfer context, refine content through
iteration, and verify the doc works for readers.1
2
3
4
5
6
2
3
4
5
6
1. 核心概念
1.1 适用场景
触发条件：
- 用户提到写文档："write a doc", "draft a proposal", "create a spec"
- 用户提到特定文档类型：PRD、设计文档、决策文档、RFC
- 用户开始进行大量写作任务
1.2 三阶段工作流
mermaid
graph LR
A[阶段1: 上下文收集] --> B[阶段2: 精炼与结构化]
B --> C[阶段3: 读者测试]1
2
3
2
3
| 阶段 | 目标 |
|---|---|
| 上下文收集 | 用户提供所有相关上下文，Claude 提问澄清 |
| 精炼与结构化 | 通过头脑风暴和编辑迭代构建每个章节 |
| 读者测试 | 用新鲜的 Claude 测试文档是否对读者有效 |
2. 阶段1：上下文收集
2.1 初始问题
markdown
1. 这是什么类型的文档？（如技术规格、决策文档、提案）
2. 主要受众是谁？
3. 读者阅读后期望产生什么影响？
4. 是否有模板或特定格式要求？
5. 还有其他约束或上下文需要了解吗？1
2
3
4
5
2
3
4
5
2.2 信息倾倒
markdown
鼓励用户提供所有上下文：
- 项目/问题背景
- 相关团队讨论或共享文档
- 为什么不使用替代方案
- 组织上下文（团队动态、过往事件、政治因素）
- 时间压力或约束
- 技术架构或依赖
- 利益相关者关注点1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
2.3 澄清问题
用户完成初始信息倾倒后，生成 5-10 个编号问题，基于上下文中的空白：
markdown
用户可以用简短方式回答：
- "1: 是, 2: 见 #channel, 3: 不行因为向后兼容"
- 链接更多文档
- 指向要读取的频道
- 继续信息倾倒1
2
3
4
5
2
3
4
5
2.4 退出条件
markdown
当问题显示理解深度时，上下文收集完成：
- 能够询问边界情况和权衡
- 不需要解释基础知识1
2
3
2
3
3. 阶段2：精炼与结构化
3.1 章节构建流程
对于每个章节：
mermaid
graph LR
A[澄清问题] --> B[头脑风暴]
B --> C[筛选]
C --> D[缺口检查]
D --> E[起草]
E --> F[迭代精炼]1
2
3
4
5
6
2
3
4
5
6
3.2 步骤详解
markdown
**步骤1：澄清问题**
询问关于该章节应包含什么的 5-10 个问题
**步骤2：头脑风暴**
根据章节复杂度，头脑风暴 5-20 个可能包含的要点：
- 寻找可能被遗忘的上下文
- 尚未提及的角度或考虑
**步骤3：筛选**
用户指示保留/删除/合并哪些要点，并给出简要理由：
- "Keep 1,4,7,9"
- "Remove 3 (duplicates 1)"
- "Combine 11 and 12"
**步骤4：缺口检查**
询问该章节是否还缺少重要内容
**步骤5：起草**
使用 str_replace 替换占位符文本为实际内容
**步骤6：迭代精炼**
根据用户反馈进行编辑，直到满意1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
3.3 章节排序
markdown
**优先处理最有未知数的章节**：
- 决策文档：通常是核心提案
- 规格文档：通常是技术方法
- 摘要章节：留到最后1
2
3
4
2
3
4
3.4 质量检查
markdown
连续 3 次迭代没有实质性改变后，询问：
"是否有任何内容可以删除而不失去重要信息？"1
2
2
4. 阶段3：读者测试
4.1 目标
用新鲜的 Claude（无上下文泄露）测试文档，验证它对读者有效。
4.2 有子代理时（如 Claude Code）
markdown
**步骤1：预测读者问题**
生成读者可能会问的 5-10 个问题
**步骤2：用子代理测试**
对每个问题，调用只有文档内容和问题的子代理
总结读者 Claude 对每个问题的正确/错误
**步骤3：运行额外检查**
调用子代理检查歧义、错误假设、矛盾
**步骤4：报告并修复**
列出具体问题，回到精炼阶段修复问题章节1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
4.3 无子代理时（如 claude.ai）
markdown
用户需要手动测试：
**步骤1：预测读者问题**
生成 5-10 个读者会问的问题
**步骤2：设置测试**
1. 打开新的 Claude 对话：https://claude.ai
2. 粘贴或分享文档内容
3. 向读者 Claude 提问
**步骤3：额外检查**
请读者 Claude 回答：
- "这份文档中有什么可能对读者不明确或模糊？"
- "这份文档假设读者已经知道什么知识或上下文？"
- "是否有任何内部矛盾或不一致？"
**步骤4：根据结果迭代**
报告读者 Claude 遇到的困难，修复这些缺口1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
4.4 退出条件
markdown
当读者 Claude 始终正确回答问题且不再发现新的缺口或歧义时，
文档准备就绪。1
2
2
5. 最终审查
5.1 通过读者测试后
markdown
1. 建议用户自己做最终通读——他们对文档负责
2. 建议仔细检查事实、链接或技术细节
3. 请用户验证文档是否达到预期效果1
2
3
2
3
5.2 完成建议
markdown
- 考虑在附录中链接此对话，让读者看到文档如何开发
- 使用附录提供深度而不膨胀主文档
- 收到真实读者反馈后更新文档1
2
3
2
3
6. 有效引导技巧
6.1 语调
markdown
- 直接和程序化
- 简短解释原因（当影响用户行为时）
- 不要"推销"方法——直接执行1
2
3
2
3
6.2 处理偏离
markdown
- 如果用户想跳过某个阶段：
询问是否要跳过并自由写作
- 如果用户看起来沮丧：
承认这比预期花费更长时间
建议更快推进的方法
- 始终给用户调整流程的权力1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
6.3 上下文管理
markdown
- 如果提到的内容缺少上下文，主动询问
- 不要让缺口积累——遇到时立即解决1
2
2
6.4 Artifact 管理
markdown
- 使用 create_file 起草完整章节
- 使用 str_replace 进行所有编辑
- 每次更改后提供 artifact 链接
- 不要用 artifact 做头脑风暴列表——那只是对话1
2
3
4
2
3
4
7. 使用示例
7.1 触发方式
"帮我写一份技术规格文档"
"我需要起草一个项目提案"
"write a design doc for our new feature"
"create an RFC for the API redesign"1
2
3
4
2
3
4
7.2 典型对话流程
markdown
**用户**：帮我写一份关于用户认证系统的设计文档
**Claude**：我可以引导你通过一个结构化的工作流来协作写这份文档。这个流程有三个阶段：
1. 上下文收集
2. 精炼与结构化
3. 读者测试
你想试试这个工作流，还是更喜欢自由形式地写？
**用户**：用这个工作流吧
**Claude**：好的，让我们开始上下文收集...1
2
3
4
5
6
7
8
9
10
11
12
2
3
4
5
6
7
8
9
10
11
12
8. 本节小结
| 要点 | 说明 |
|---|---|
| 三阶段流程 | 上下文收集 → 精炼结构 → 读者测试 |
| 章节构建 | 澄清 → 头脑风暴 → 筛选 → 起草 → 迭代 |
| 读者测试 | 用新鲜 Claude 验证文档有效性 |
| 质量优先 | 每次迭代应有实质性改进 |
| 用户控制 | 始终给用户调整流程的权力 |
返回：Skills 目录