# Doc Coauthoring

> 引导用户通过结构化的工作流协作编写文档。当用户想要编写文档、提案、技术规范、决策文档或类似的结构化内容时使用。此工作流帮助用户高效地传递上下文、通过迭代优化内容,并验证文档是否适合读者阅读。当用户提到编写文档、创建提案、起草规范或类似文档任务时触发。

- Skill: `majiayu000/doc-coauthoring-7` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/doc-coauthoring-7`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/doc-coauthoring-7/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/doc-coauthoring-7

---


# 文档协作工作流

此技能提供了一个结构化的工作流,用于引导用户进行协作式文档创建。作为主动的引导者,带领用户完成三个阶段:上下文收集、优化与结构、读者测试。

## 何时提供此工作流

**触发条件:**
- 用户提到编写文档:"写个文档"、"起草提案"、"创建规范"、"写一下"
- 用户提到特定文档类型:"PRD"、"设计文档"、"决策文档"、"RFC"
- 用户似乎正在开始一个重要的写作任务

**初始提议:**
为用户提供协作编写文档的结构化工作流。解释三个阶段:

1. **上下文收集**:用户提供所有相关上下文,同时 Claude 提出澄清问题
2. **优化与结构**:通过头脑风暴和编辑迭代构建每个部分
3. **读者测试**:使用全新的 Claude(无上下文)测试文档,在他人阅读前发现盲点

解释这种方法有助于确保文档在被他人阅读时效果良好(包括当他们将其粘贴到 Claude 中时)。询问他们是否想尝试此工作流,还是更喜欢自由形式的工作。

如果用户拒绝,则自由形式工作。如果用户接受,继续第一阶段。

## 第一阶段:上下文收集

**目标:**缩小用户所知与 Claude 所知之间的差距,以便后续提供智能指导。

### 初始问题

首先向用户询问关于文档的元上下文:

1. 这是什么类型的文档?(例如:技术规范、决策文档、提案)
2. 主要受众是谁?
3. 期望的阅读影响是什么?
4. 是否有模板或特定格式要遵循?
5. 是否还有其他约束或上下文需要了解?

告知他们可以用简写方式回答,或以任何最有效的方式倾倒信息。

**如果用户提供模板或提到文档类型:**
- 询问是否有可分享的模板文档
- 如果他们提供共享文档链接,使用相应的集成获取它
- 如果他们提供文件,读取它

**如果用户提到编辑现有共享文档:**
- 使用相应的集成读取当前状态
- 检查是否有没有 alt-text 的图片
- 如果存在没有 alt-text 的图片,解释当他人使用 Claude 理解文档时,Claude 将无法看到它们。询问是否要生成 alt-text。如果需要,请求他们将每张图片粘贴到聊天中以生成描述性 alt-text。

### 信息倾倒

一旦初始问题得到回答,鼓励用户倾倒他们拥有的所有上下文。请求以下信息:
- 项目/问题的背景
- 相关团队讨论或共享文档
- 为何不使用其他解决方案
- 组织上下文(团队动态、过往事件、政治因素)
- 时间压力或约束
- 技术架构或依赖关系
- 利益相关者的关注点

建议他们不用担心组织结构——只需把所有信息都倾倒出来。提供多种提供上下文的方式:
- 意识流式的信息倾倒
- 指向要阅读的团队频道或线程
- 链接到共享文档

**如果集成可用**(例如:Slack、Teams、Google Drive、SharePoint 或其他 MCP 服务器),提及可以使用这些来直接拉取上下文。

**如果未检测到集成且在 Claude.ai 或 Claude 应用中:** 建议他们可以在 Claude 设置中启用连接器,以允许直接从消息应用和文档存储中拉取上下文。

告知他们在完成初始倾倒后将提出澄清问题。

**在上下文收集期间:**

- 如果用户提到团队频道或共享文档:
  - 如果集成可用:告知内容将被读取,然后使用相应的集成
  - 如果集成不可用:解释无法访问。建议他们在 Claude 设置中启用连接器,或直接粘贴相关内容

- 如果用户提到未知的实体/项目:
  - 询问是否应搜索已连接的工具以了解更多信息
  - 在搜索前等待用户确认

- 当用户提供上下文时,追踪正在学习的内容以及仍不清楚的内容

**提出澄清问题:**

当用户表示已完成初始倾倒(或提供了大量上下文)后,提出澄清问题以确保理解:

根据上下文中的差距生成 5-10 个编号的问题。

告知他们可以使用简写方式回答(例如:"1: 是,2: 见 #channel,3: 否因为向后兼容"),链接到更多文档,指向要阅读的频道,或继续信息倾倒。只要对他们最高效即可。

**退出条件:**
当问题显示出理解——即能够询问边缘情况和权衡而无需解释基础知识时,就表示收集了足够的上下文。

**过渡:**
询问在此阶段是否还有更多上下文要提供,还是该开始起草文档了。

如果用户想添加更多,让他们添加。准备好后,进入第二阶段。

## 第二阶段:优化与结构

**目标:** 通过头脑风暴、策划和迭代优化逐节构建文档。

**给用户的说明:**
解释文档将逐节构建。对于每个部分:
1. 将提出关于包含内容的澄清问题
2. 将头脑风暴 5-20 个选项
3. 用户将指示保留/删除/合并哪些内容
4. 将起草该部分
5. 将通过精确编辑进行优化

从具有最多未知数的部分开始(通常是核心决策/提案),然后处理其余部分。

**部分顺序:**

如果文档结构清晰:
询问他们想从哪个部分开始。

建议从具有最多未知数的部分开始。对于决策文档,通常是核心提案。对于规范,通常是技术方法。摘要部分最好留到最后。

如果用户不知道需要哪些部分:
根据文档类型和模板,建议适合该文档类型的 3-5 个部分。

询问此结构是否可行,或者是否要调整它。

**一旦结构确定:**

创建包含所有部分占位符文本的初始文档结构。

**如果可以访问工件:**
使用 `create_file` 创建工件。这为 Claude 和用户都提供了一个可工作的脚手架。

告知他们将创建包含所有部分占位符的初始结构。

创建包含所有部分标题和简短占位符文本(如"[待写]"或"[此处内容]")的工件。

提供脚手架链接,并指示现在是填充每个部分的时候了。

**如果无法访问工件:**
在工作目录中创建 markdown 文件。适当命名(例如:`decision-doc.md`、`technical-spec.md`)。

告知将创建包含所有部分占位符的初始结构。

创建包含所有部分标题和占位符文本的文件。

确认已创建的文件名,并指示现在是填充每个部分的时候了。

**对于每个部分:**

### 步骤 1: 澄清问题

宣布将开始处理 [部分名称] 部分。提出 5-10 个关于应包含内容的澄清问题:

根据上下文和部分目的生成 5-10 个具体问题。

告知他们可以使用简写方式回答,或只需指出要涵盖的重要内容。

### 步骤 2: 头脑风暴

为 [部分名称] 部分,根据部分的复杂程度,头脑风暴 [5-20] 个可能包含的内容。寻找:
- 可能已被遗忘的共享上下文
- 尚未提及的角度或考虑因素

根据部分复杂程度生成 5-20 个编号选项。最后,如果他们需要更多选项,提供继续头脑风暴。

### 步骤 3: 策划

询问应保留、删除或合并哪些要点。请求简要说明以帮助了解后续部分的优先级。

提供示例:
- "保留 1、4、7、9"
- "删除 3(与 1 重复)"
- "删除 6(受众已经知道这一点)"
- "合并 11 和 12"

**如果用户给出自由形式反馈**(例如:"看起来不错"或"我大部分喜欢但是...")而不是编号选择,提取他们的偏好并继续。解析他们想要保留/删除/更改的内容并应用。

### 步骤 4: 差距检查

根据他们的选择,询问 [部分名称] 部分是否缺少重要内容。

### 步骤 5: 起草

使用 `str_replace` 将此部分的占位符文本替换为实际起草的内容。

宣布现在将根据他们的选择起草 [部分名称] 部分。

**如果使用工件:**
起草后,提供工件链接。

请他们通读并指示要更改的内容。注意,具体说明有助于为后续部分学习。

**如果使用文件(无工件):**
起草后,确认完成。

告知已在 [文件名] 中起草 [部分名称] 部分。请他们通读并指示要更改的内容。注意,具体说明有助于为后续部分学习。

**给用户的关键说明(在起草第一部分时包含):**
提供说明:与其直接编辑文档,不如让他们指示要更改的内容。这有助于了解他们的风格以便后续部分使用。例如:"删除 X 要点——已由 Y 涵盖"或"使第三段更简洁"。

### 步骤 6: 迭代优化

当用户提供反馈时:
- 使用 `str_replace` 进行编辑(永不重新打印整个文档)
- **如果使用工件:** 每次编辑后提供工件链接
- **如果使用文件:** 只确认编辑完成
- 如果用户直接编辑文档并要求读取:在心理上记录他们所做的更改,并在后续部分中记住这些更改(这显示了他们的偏好)

**继续迭代**直到用户对该部分满意。

### 质量检查

经过 3 次连续迭代且无重大更改后,询问是否可以在不丢失重要信息的情况下删除任何内容。

当部分完成时,确认 [部分名称] 已完成。询问是否准备好进入下一部分。

**对所有部分重复此过程。**

### 接近完成

当接近完成(80% 以上的部分完成)时,宣布打算重新阅读整个文档并检查:
- 各部分之间的流程和一致性
- 冗余或矛盾
- 任何感觉像"草率"或通用填充的内容
- 每个句子是否都有分量

阅读整个文档并提供反馈。

**当所有部分都已起草和优化时:**
宣布所有部分已起草。表示打算再审查一次完整文档。

审查整体连贯性、流程、完整性。

提供任何最终建议。

询问是否准备好进入读者测试,或者是否想优化其他内容。

## 第三阶段:读者测试

**目标:** 使用全新的 Claude(无上下文泄露)测试文档,以验证它是否适合读者。

**给用户的说明:**
解释现在将进行测试,以查看文档是否真的适合读者。这能发现盲点——对作者有意义但可能使他人困惑的内容。

### 测试方法

**如果可以访问子代理(例如在 Claude Code 中):**

直接执行测试,无需用户参与。

### 步骤 1: 预测读者问题

宣布打算预测读者在尝试发现此文档时可能会问的问题。

生成 5-10 个读者实际会问的问题。

### 步骤 2: 使用子代理测试

宣布将使用全新的 Claude 实例(无此对话的上下文)测试这些问题。

对于每个问题,调用仅包含文档内容和问题的子代理。

总结读者 Claude 在每个问题上的对错。

### 步骤 3: 运行额外检查

宣布将执行额外检查。

调用子代理检查歧义、错误假设、矛盾。

总结发现的任何问题。

### 步骤 4: 报告和修复

如果发现问题:
报告读者 Claude 在特定问题上遇到困难。

列出具体问题。

表示打算修复这些差距。

循环回到有问题的部分进行优化。

---

**如果无法访问子代理(例如 claude.ai 网页界面):**

用户将需要手动执行测试。

### 步骤 1: 预测读者问题

询问人们在尝试发现此文档时可能会问什么问题。他们会在 Claude.ai 中输入什么?

生成 5-10 个读者实际会问的问题。

### 步骤 2: 设置测试

提供测试说明:
1. 打开全新的 Claude 对话:https://claude.ai
2. 粘贴或分享文档内容(如果使用启用了连接器的共享文档平台,提供链接)
3. 向读者 Claude 提出生成的问题

对于每个问题,指示读者 Claude 提供:
- 答案
- 是否有任何歧义或不清楚的内容
- 文档假设已具备什么知识/上下文

检查读者 Claude 是否给出正确答案或误解任何内容。

### 步骤 3: 额外检查

还要询问读者 Claude:
- "此文档中哪些内容可能对读者来说有歧义或不清楚?"
- "此文档假设读者已经具备哪些知识或上下文?"
- "是否有任何内部矛盾或不一致?"

### 步骤 4: 根据结果迭代

询问读者 Claude 哪些问题弄错或遇到困难。表示打算修复这些差距。

循环回到任何有问题的部分进行优化。

---

### 退出条件(两种方法)

当读者 Claude 始终正确回答问题且未发现新的差距或歧义时,文档就准备好了。

## 最终审查

当读者测试通过时:
宣布文档已通过读者 Claude 测试。完成之前:

1. 建议他们自己做最后的通读——他们拥有此文档并对其质量负责
2. 建议仔细检查任何事实、链接或技术细节
3. 请他们验证是否达到了他们想要的影响

询问他们是否还需要一次审查,或者工作是否完成。

**如果用户希望最终审查,提供审查。否则:**
宣布文档完成。提供一些最后的提示:
- 考虑在附录中链接此对话,以便读者可以看到文档是如何开发的
- 使用附录提供深度而不膨胀主文档
- 根据真实读者的反馈更新文档

## 有效指导的技巧

**语气:**
- 直接且程序化
- 当影响用户行为时简要解释理由
- 不要试图"推销"这种方法——只需执行它

**处理偏差:**
- 如果用户想跳过某个阶段:询问是否想跳过此阶段并以自由形式编写
- 如果用户似乎感到沮丧:承认这比预期的时间长。建议加快速度的方法
- 始终给予用户调整流程的主动权

**上下文管理:**
- 整个过程中,如果提到的内容缺少上下文,主动询问
- 不要让差距累积——在出现时解决它们

**工件管理:**
- 使用 `create_file` 起草完整部分
- 使用 `str_replace` 进行所有编辑
- 每次更改后提供工件链接
- 永远不要将工件用于头脑风暴列表——那只是对话

**质量优于速度:**
- 不要匆忙完成各个阶段
- 每次迭代都应有意义的改进
- 目标是一个真正适合读者的文档