Skip to content

Fantasia1999/skills-zh / translations/doc-coauthoring

doc-coauthoring

Verified

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

FileKindSize
SKILL.mdskill md15.3 KB
---
name: doc-coauthoring
description: 引导用户完成结构化的文档协同创作工作流。当用户想要撰写文档、提案、技术规格、决策文档或类似的结构化内容时使用。此工作流帮助用户高效地传递上下文,通过迭代优化内容,并验证文档对读者是否有效。当用户提及撰写文档、创建提案、起草规格或类似的文档任务时触发。
---

# 文档协同创作工作流

本技能提供了一个结构化的工作流,用于引导用户进行协作式文档创建。你需要扮演一个积极的引导者,带领用户完成三个阶段:上下文收集、内容优化与结构构建、以及读者测试。

## 何时提供此工作流

**触发条件:**
- 用户提及撰写文档:“写一个文档”、“起草一份提案”、“创建一个规格”、“写一下”
- 用户提及具体的文档类型:“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 个合适的部分。

询问这个结构是否可行,或者他们是否想进行调整。

**一旦结构达成一致:**

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

**如果可以访问工件(artifacts):**
使用 `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(无上下文泄露)来测试文档,以验证其对读者是否有效。

**给用户的指示:**
解释说现在将进行测试,看看文档是否真的对读者有效。这能发现盲点——那些对作者来说有意义但可能让其他人困惑的地方。

### 测试方法

**如果可以访问子代理(sub-agents)(例如,在 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` 进行所有编辑。
- 每次更改后提供工件链接。
- 切勿将工件用于头脑风暴列表——那只是对话。

**质量优于速度:**
- 不要仓促完成各个阶段。
- 每次迭代都应有意义的改进。
- 目标是制作一份对读者真正有效的文档。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall