doc-coauthoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Doc Co-Authoring Workflow

文档协作编写工作流

This skill provides a structured workflow for guiding users through collaborative document creation. Act as an active guide, walking users through three stages: Context Gathering, Refinement & Structure, and Reader Testing.

本Skill提供结构化工作流，引导用户完成协作式文档创建。全程作为主动引导者，带领用户完成三个阶段：上下文收集、优化与结构化、读者测试。

When to Offer This Workflow

何时提供此工作流

Trigger conditions:

User mentions writing documentation: "write a doc", "draft a proposal", "create a spec", "write up"
User mentions specific doc types: "PRD", "design doc", "decision doc", "RFC"
User seems to be starting a substantial writing task

Initial offer: Offer the user a structured workflow for co-authoring the document. Explain the three stages:

Context Gathering: User provides all relevant context while Claude asks clarifying questions
Refinement & Structure: Iteratively build each section through brainstorming and editing
Reader Testing: Test the doc with a fresh Claude (no context) to catch blind spots before others read it

Explain that this approach helps ensure the doc works well when others read it (including when they paste it into Claude). Ask if they want to try this workflow or prefer to work freeform.

If user declines, work freeform. If user accepts, proceed to Stage 1.

触发条件：

用户提及撰写文档："写一份文档"、"起草提案"、"创建规范"、"整理文档"
用户提及特定文档类型："PRD"、"设计文档"、"决策文档"、"RFC"
用户似乎正在启动一项重要的写作任务

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

上下文收集：用户提供所有相关上下文，Claude 会提出澄清问题
优化与结构化：通过头脑风暴和编辑迭代构建每个章节
读者测试：使用全新的 Claude（无上下文）测试文档，在他人阅读前发现盲区

说明这种方法有助于确保文档在他人阅读时（包括粘贴到 Claude 中时）效果良好。询问用户是否想尝试此工作流，还是偏好自由创作。

如果用户拒绝，则采用自由创作模式。如果用户接受，则进入第一阶段。

Stage 1: Context Gathering

第一阶段：上下文收集

Goal: Close the gap between what the user knows and what Claude knows, enabling smart guidance later.

目标： 缩小用户已知信息与Claude已知信息之间的差距，为后续的智能引导奠定基础。

Initial Questions

初始问题

Start by asking the user for meta-context about the document:

What type of document is this? (e.g., technical spec, decision doc, proposal)
Who's the primary audience?
What's the desired impact when someone reads this?
Is there a template or specific format to follow?
Any other constraints or context to know?

Inform them they can answer in shorthand or dump information however works best for them.

If user provides a template or mentions a doc type:

Ask if they have a template document to share
If they provide a link to a shared document, use the appropriate integration to fetch it
If they provide a file, read it

If user mentions editing an existing shared document:

Use the appropriate integration to read the current state
Check for images without alt-text
If images exist without alt-text, explain that when others use Claude to understand the doc, Claude won't be able to see them. Ask if they want alt-text generated. If so, request they paste each image into chat for descriptive alt-text generation.

首先向用户询问文档的元上下文信息：

这是什么类型的文档？（例如：技术规范、决策文档、提案）
主要受众是谁？
读者阅读后预期达到什么效果？
是否有需要遵循的模板或特定格式？
还有其他需要了解的约束条件或上下文吗？

告知用户可以用简写或任意方式提供信息。

如果用户提供模板或提及特定文档类型：

询问用户是否可以分享模板文档
如果用户提供共享文档链接，使用相应集成工具获取文档内容
如果用户提供文件，读取文件内容

如果用户提及要编辑现有共享文档：

使用相应集成工具读取文档当前状态
检查是否有无替代文本（alt-text）的图片
如果存在无替代文本的图片，说明当其他人使用Claude理解文档时，Claude无法识别这些图片。询问用户是否需要生成替代文本。如果需要，请求用户将每张图片粘贴到对话中以生成描述性替代文本。

Info Dumping

信息输出

Once initial questions are answered, encourage the user to dump all the context they have. Request information such as:

Background on the project/problem
Related team discussions or shared documents
Why alternative solutions aren't being used
Organizational context (team dynamics, past incidents, politics)
Timeline pressures or constraints
Technical architecture or dependencies
Stakeholder concerns

Advise them not to worry about organizing it - just get it all out. Offer multiple ways to provide context:

Info dump stream-of-consciousness
Point to team channels or threads to read
Link to shared documents

If integrations are available (e.g., Slack, Teams, Google Drive, SharePoint, or other MCP servers), mention that these can be used to pull in context directly.

If no integrations are detected and in Claude.ai or Claude app: Suggest they can enable connectors in their Claude settings to allow pulling context from messaging apps and document storage directly.

Inform them clarifying questions will be asked once they've done their initial dump.

During context gathering:

If user mentions team channels or shared documents:
- If integrations available: Inform them the content will be read now, then use the appropriate integration
- If integrations not available: Explain lack of access. Suggest they enable connectors in Claude settings, or paste the relevant content directly.
If user mentions entities/projects that are unknown:
- Ask if connected tools should be searched to learn more
- Wait for user confirmation before searching
As user provides context, track what's being learned and what's still unclear

Asking clarifying questions:

When user signals they've done their initial dump (or after substantial context provided), ask clarifying questions to ensure understanding:

Generate 5-10 numbered questions based on gaps in the context.

Inform them they can use shorthand to answer (e.g., "1: yes, 2: see #channel, 3: no because backwards compat"), link to more docs, point to channels to read, or just keep info-dumping. Whatever's most efficient for them.

Exit condition: Sufficient context has been gathered when questions show understanding - when edge cases and trade-offs can be asked about without needing basics explained.

Transition: Ask if there's any more context they want to provide at this stage, or if it's time to move on to drafting the document.

If user wants to add more, let them. When ready, proceed to Stage 2.

初始问题解答完成后，鼓励用户输出所有已有的上下文信息。请求提供以下类型的信息：

项目/问题的背景信息
相关的团队讨论或共享文档
不选择其他解决方案的原因
组织上下文（团队动态、过往事件、相关情况）
时间线压力或约束条件
技术架构或依赖关系
相关利益相关者的关注点

告知用户无需担心内容的组织，只需将所有信息输出即可。提供多种上下文提供方式：

以意识流的方式输出信息
指向需要读取的团队频道或讨论线程
链接到共享文档

如果有可用集成工具（例如：Slack、Teams、Google Drive、SharePoint或其他MCP服务器），说明可以直接通过这些工具获取上下文信息。

如果未检测到集成工具，且在Claude.ai或Claude应用中： 建议用户在Claude设置中启用连接器，以便直接从消息应用和文档存储中获取上下文。

告知用户在初始信息输出完成后，会提出澄清问题。

上下文收集过程中：

如果用户提及团队频道或共享文档：
- 如果有可用集成工具：告知用户将立即读取内容，然后使用相应集成工具
- 如果无可用集成工具：说明无法访问。建议用户在Claude设置中启用连接器，或直接粘贴相关内容。
如果用户提及未知的实体/项目：
- 询问是否应该通过关联工具搜索相关信息
- 获得用户确认后再进行搜索
在用户提供上下文的过程中，记录已了解的信息和仍不明确的内容

Stage 2: Refinement & Structure

提出澄清问题

Goal: Build the document section by section through brainstorming, curation, and iterative refinement.

Instructions to user: Explain that the document will be built section by section. For each section:

Clarifying questions will be asked about what to include
5-20 options will be brainstormed
User will indicate what to keep/remove/combine
The section will be drafted
It will be refined through surgical edits

Start with whichever section has the most unknowns (usually the core decision/proposal), then work through the rest.

Section ordering:

If the document structure is clear: Ask which section they'd like to start with.

Suggest starting with whichever section has the most unknowns. For decision docs, that's usually the core proposal. For specs, it's typically the technical approach. Summary sections are best left for last.

If user doesn't know what sections they need: Based on the type of document and template, suggest 3-5 sections appropriate for the doc type.

Ask if this structure works, or if they want to adjust it.

Once structure is agreed:

Create the initial document structure with placeholder text for all sections.

If access to artifacts is available: Use

create_file

to create an artifact. This gives both Claude and the user a scaffold to work from.

Inform them that the initial structure with placeholders for all sections will be created.

Create artifact with all section headers and brief placeholder text like "[To be written]" or "[Content here]".

Provide the scaffold link and indicate it's time to fill in each section.

If no access to artifacts: Create a markdown file in the working directory. Name it appropriately (e.g.,

decision-doc.md

technical-spec.md

Inform them that the initial structure with placeholders for all sections will be created.

Create file with all section headers and placeholder text.

Confirm the filename has been created and indicate it's time to fill in each section.

For each section:

当用户表示已完成初始信息输出（或提供了大量上下文信息后），提出澄清问题以确保理解到位：

根据上下文缺口生成5-10个编号的澄清问题。

告知用户可以用简写回答，或只需指出需要涵盖的重点内容。

退出条件： 当提出的问题能够体现对内容的理解——能够询问边缘情况和权衡因素而无需解释基础知识时，即表示已收集到足够的上下文信息。

过渡： 询问用户是否有更多上下文信息需要提供，还是可以进入文档起草阶段。

如果用户想补充更多信息，允许其补充。准备就绪后，进入第二阶段。

Step 1: Clarifying Questions

第二阶段：优化与结构化

Announce work will begin on the [SECTION NAME] section. Ask 5-10 clarifying questions about what should be included:

Generate 5-10 specific questions based on context and section purpose.

Inform them they can answer in shorthand or just indicate what's important to cover.

目标： 通过头脑风暴、筛选和迭代优化，逐章构建文档。

给用户的说明： 向用户说明将逐章构建文档。对于每个章节：

提出关于章节内容的澄清问题
进行头脑风暴，生成5-20个可能的内容选项
用户指示保留、删除或合并哪些内容
起草章节内容
通过精准编辑优化内容

从信息缺口最大的章节开始（通常是核心决策/提案），然后依次处理其他章节。

章节顺序：

如果文档结构明确：询问用户想从哪个章节开始。

建议从信息缺口最大的章节开始。对于决策文档，通常是核心提案部分；对于规范文档，通常是技术方案部分。摘要章节最好放在最后处理。

如果用户不清楚需要哪些章节：根据文档类型和模板，建议3-5个适合该文档类型的章节。

询问用户该结构是否可行，或者是否需要调整。

确定结构后：

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

如果可以访问工件（artifacts）： 使用

create_file

创建工件。这将为Claude和用户提供一个文档框架。

告知用户将创建包含所有章节占位符的初始结构。

创建包含所有章节标题和简短占位符文本（如“[待撰写]”或“[此处添加内容]”）的工件。

提供框架链接，并表示可以开始填充每个章节的内容。

如果无法访问工件： 在工作目录中创建一个markdown文件。为文件起合适的名称（例如：

decision-doc.md

、

technical-spec.md

）。

告知用户将创建包含所有章节占位符的初始结构。

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

确认文件已创建，并表示可以开始填充每个章节的内容。

每个章节的处理流程：

Step 2: Brainstorming

步骤1：澄清问题

For the [SECTION NAME] section, brainstorm [5-20] things that might be included, depending on the section's complexity. Look for:

Context shared that might have been forgotten
Angles or considerations not yet mentioned

Generate 5-20 numbered options based on section complexity. At the end, offer to brainstorm more if they want additional options.

宣布将开始处理【章节名称】章节。提出5-10个关于章节内容的澄清问题：

根据上下文和章节目标生成5-10个具体问题。

告知用户可以用简写回答，或只需指出需要涵盖的重点内容。

Step 3: Curation

步骤2：头脑风暴

Ask which points should be kept, removed, or combined. Request brief justifications to help learn priorities for the next sections.

Provide examples:

"Keep 1,4,7,9"
"Remove 3 (duplicates 1)"
"Remove 6 (audience already knows this)"
"Combine 11 and 12"

If user gives freeform feedback (e.g., "looks good" or "I like most of it but...") instead of numbered selections, extract their preferences and proceed. Parse what they want kept/removed/changed and apply it.

针对【章节名称】章节，根据章节复杂度生成5-20个可能包含的内容点。重点关注：

用户已分享但可能被遗忘的上下文信息
尚未提及的视角或考虑因素

根据章节复杂度生成5-20个编号的内容选项。最后询问用户是否需要生成更多选项。

Step 4: Gap Check

步骤3：内容筛选

Based on what they've selected, ask if there's anything important missing for the [SECTION NAME] section.

询问用户哪些内容点需要保留、删除或合并。请求提供简短的理由，以便了解后续章节的优先级。

提供示例：

“保留1、4、7、9”
“删除3（与1重复）”
“删除6（受众已了解此内容）”
“合并11和12”

如果用户提供自由形式的反馈（例如：“看起来不错”或“我大部分都喜欢，但……”）而非编号选择，则提取用户的偏好并继续处理。解析用户希望保留/删除/修改的内容并应用。

Step 5: Drafting

步骤4：缺口检查

Use

str_replace

to replace the placeholder text for this section with the actual drafted content.

Announce the [SECTION NAME] section will be drafted now based on what they've selected.

If using artifacts: After drafting, provide a link to the artifact.

Ask them to read through it and indicate what to change. Note that being specific helps learning for the next sections.

If using a file (no artifacts): After drafting, confirm completion.

Inform them the [SECTION NAME] section has been drafted in [filename]. Ask them to read through it and indicate what to change. Note that being specific helps learning for the next sections.

Key instruction for user (include when drafting the first section): Provide a note: Instead of editing the doc directly, ask them to indicate what to change. This helps learning of their style for future sections. For example: "Remove the X bullet - already covered by Y" or "Make the third paragraph more concise".

根据用户选择的内容，询问【章节名称】章节是否有重要内容遗漏。

Step 6: Iterative Refinement

步骤5：起草内容

As user provides feedback:

Use
```
str_replace
```
to make edits (never reprint the whole doc)
If using artifacts: Provide link to artifact after each edit
If using files: Just confirm edits are complete
If user edits doc directly and asks to read it: mentally note the changes they made and keep them in mind for future sections (this shows their preferences)

Continue iterating until user is satisfied with the section.

使用

str_replace

将该章节的占位符文本替换为实际起草的内容。

宣布将根据用户选择的内容起草【章节名称】章节。

如果使用工件： 起草完成后，提供工件链接。

请用户阅读内容并指出需要修改的地方。注意：越具体的反馈越有助于后续章节的处理。

如果使用文件（无工件）： 起草完成后，确认任务完成。

告知用户【章节名称】章节已在[文件名]中起草完成。请用户阅读内容并指出需要修改的地方。注意：越具体的反馈越有助于后续章节的处理。

给用户的关键说明（起草第一个章节时包含）： 提示用户：不要直接编辑文档，而是指出需要修改的内容。这有助于了解用户的写作风格，以便处理后续章节。例如：“删除X项目符号——已被Y涵盖”或“将第三段写得更简洁”。

Quality Checking

步骤6：迭代优化

After 3 consecutive iterations with no substantial changes, ask if anything can be removed without losing important information.

When section is done, confirm [SECTION NAME] is complete. Ask if ready to move to the next section.

Repeat for all sections.

当用户提供反馈时：

使用
```
str_replace
```
进行编辑（不要重新打印整个文档）
如果使用工件： 每次编辑后提供工件链接
如果使用文件： 只需确认编辑已完成
如果用户直接编辑文档并要求读取：记录用户所做的更改，并在后续章节中考虑这些偏好

持续迭代直到用户对该章节满意为止。

Near Completion

质量检查

As approaching completion (80%+ of sections done), announce intention to re-read the entire document and check for:

Flow and consistency across sections
Redundancy or contradictions
Anything that feels like "slop" or generic filler
Whether every sentence carries weight

Read entire document and provide feedback.

When all sections are drafted and refined: Announce all sections are drafted. Indicate intention to review the complete document one more time.

Review for overall coherence, flow, completeness.

Provide any final suggestions.

Ask if ready to move to Reader Testing, or if they want to refine anything else.

连续3次迭代无实质性更改后，询问用户是否可以删除某些内容而不丢失重要信息。

章节完成后，确认【章节名称】章节已完成。询问用户是否准备好进入下一个章节。

对所有章节重复上述流程。

Stage 3: Reader Testing

接近完成阶段

Goal: Test the document with a fresh Claude (no context bleed) to verify it works for readers.

Instructions to user: Explain that testing will now occur to see if the document actually works for readers. This catches blind spots - things that make sense to the authors but might confuse others.

当完成80%以上的章节时，宣布将重新阅读整个文档并检查以下内容：

章节间的流畅性和一致性
冗余或矛盾内容
任何看起来“粗糙”或通用的填充内容
每句话是否有实际意义

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

当所有章节起草并优化完成后： 宣布所有章节已起草完成。表示将再次通读完整文档进行最终检查。

检查文档的整体连贯性、流畅性和完整性。

提供最终建议。

询问用户是否准备好进入读者测试阶段，还是需要进一步优化内容。

Testing Approach

第三阶段：读者测试

If access to sub-agents is available (e.g., in Claude Code):

Perform the testing directly without user involvement.

目标： 使用全新的Claude（无上下文泄露）测试文档，验证文档对读者的适用性。

给用户的说明： 向用户说明现在将进行测试，查看文档对读者是否真正有效。这可以发现盲区——对作者来说合理，但可能让其他人困惑的内容。

Step 1: Predict Reader Questions

测试方法

Announce intention to predict what questions readers might ask when trying to discover this document.

Generate 5-10 questions that readers would realistically ask.

如果可以访问子代理（例如：在Claude Code中）：

无需用户参与，直接进行测试。

Step 2: Test with Sub-Agent

步骤1：预测读者问题

Announce that these questions will be tested with a fresh Claude instance (no context from this conversation).

For each question, invoke a sub-agent with just the document content and the question.

Summarize what Reader Claude got right/wrong for each question.

宣布将预测读者在阅读文档时可能提出的问题。

生成5-10个读者可能会提出的真实问题。

Step 3: Run Additional Checks

步骤2：子代理测试

Announce additional checks will be performed.

Invoke sub-agent to check for ambiguity, false assumptions, contradictions.

Summarize any issues found.

宣布将使用全新的Claude实例（无本次对话的上下文）测试这些问题。

针对每个问题，调用子代理，仅提供文档内容和问题。

总结每个问题的测试结果：读者Claude回答正确/错误的地方。

Step 4: Report and Fix

步骤3：额外检查

If issues found: Report that Reader Claude struggled with specific issues.

List the specific issues.

Indicate intention to fix these gaps.

Loop back to refinement for problematic sections.

If no access to sub-agents (e.g., claude.ai web interface):

The user will need to do the testing manually.

宣布将进行额外检查。

调用子代理检查文档中的歧义、错误假设和矛盾内容。

总结发现的问题。

Step 1: Predict Reader Questions

步骤4：报告与修复

Ask what questions people might ask when trying to discover this document. What would they type into Claude.ai?

Generate 5-10 questions that readers would realistically ask.

如果发现问题：报告读者Claude在哪些方面存在理解困难。

列出具体问题。

表示将修复这些缺口。

返回优化阶段处理有问题的章节。

如果无法访问子代理（例如：claude.ai网页端）：

需要用户手动进行测试。

Step 2: Setup Testing

步骤1：预测读者问题

Provide testing instructions:

Open a fresh Claude conversation: https://claude.ai
Paste or share the document content (if using a shared doc platform with connectors enabled, provide the link)
Ask Reader Claude the generated questions

For each question, instruct Reader Claude to provide:

The answer
Whether anything was ambiguous or unclear
What knowledge/context the doc assumes is already known

Check if Reader Claude gives correct answers or misinterprets anything.

询问用户人们阅读文档时可能会提出什么问题。他们会在Claude.ai中输入什么内容？

生成5-10个读者可能会提出的真实问题。

Step 3: Additional Checks

步骤2：测试设置

Also ask Reader Claude:

"What in this doc might be ambiguous or unclear to readers?"
"What knowledge or context does this doc assume readers already have?"
"Are there any internal contradictions or inconsistencies?"

提供测试说明：

打开一个全新的Claude对话：https://claude.ai
粘贴或分享文档内容（如果使用带连接器的共享文档平台，提供链接即可）
向读者Claude提出生成的问题

针对每个问题，指示读者Claude提供：

答案
是否存在歧义或不明确的内容
文档假设读者已具备哪些知识/上下文

检查读者Claude的回答是否正确，或是否存在误解。

Step 4: Iterate Based on Results

步骤3：额外检查

Ask what Reader Claude got wrong or struggled with. Indicate intention to fix those gaps.

Loop back to refinement for any problematic sections.

同时询问读者Claude：

“文档中哪些内容可能对读者来说有歧义或不明确？”
“文档假设读者已具备哪些知识或上下文？”
“文档中是否存在内部矛盾或不一致的内容？”

Exit Condition (Both Approaches)

步骤4：根据结果迭代

When Reader Claude consistently answers questions correctly and doesn't surface new gaps or ambiguities, the doc is ready.

询问用户读者Claude回答错误或存在理解困难的地方。表示将修复这些缺口。

返回优化阶段处理有问题的章节。

Final Review

退出条件（两种方法通用）

When Reader Testing passes: Announce the doc has passed Reader Claude testing. Before completion:

Recommend they do a final read-through themselves - they own this document and are responsible for its quality
Suggest double-checking any facts, links, or technical details
Ask them to verify it achieves the impact they wanted

Ask if they want one more review, or if the work is done.

If user wants final review, provide it. Otherwise: Announce document completion. Provide a few final tips:

Consider linking this conversation in an appendix so readers can see how the doc was developed
Use appendices to provide depth without bloating the main doc
Update the doc as feedback is received from real readers

当读者Claude能够持续正确回答问题，且未发现新的缺口或歧义时，文档即准备就绪。

Tips for Effective Guidance

最终审核

Tone:

Be direct and procedural
Explain rationale briefly when it affects user behavior
Don't try to "sell" the approach - just execute it

Handling Deviations:

If user wants to skip a stage: Ask if they want to skip this and write freeform
If user seems frustrated: Acknowledge this is taking longer than expected. Suggest ways to move faster
Always give user agency to adjust the process

Context Management:

Throughout, if context is missing on something mentioned, proactively ask
Don't let gaps accumulate - address them as they come up

Artifact Management:

Use
```
create_file
```
for drafting full sections
Use
```
str_replace
```
for all edits
Provide artifact link after every change
Never use artifacts for brainstorming lists - that's just conversation

Quality over Speed:

Don't rush through stages
Each iteration should make meaningful improvements
The goal is a document that actually works for readers

当读者测试通过后：宣布文档已通过读者Claude测试。在完成前：

建议用户自行进行最终通读——用户是文档的所有者，对文档质量负责
建议再次检查任何事实、链接或技术细节
询问用户是否确认文档达到了预期效果

如果用户需要最终审核，提供审核服务。否则：宣布文档已完成。提供一些最终建议：

考虑在附录中链接本次对话，以便读者了解文档的开发过程
使用附录提供详细内容，避免主文档过于冗长
根据真实读者的反馈更新文档

—

有效引导技巧

—

语气：

直接且有条理
当影响用户行为时，简要解释理由
无需“推销”该方法，只需执行即可

处理偏差：

如果用户想跳过某个阶段：询问用户是否想跳过该阶段并采用自由创作模式
如果用户看起来很沮丧：承认过程比预期耗时更长。建议加快进度的方法
始终给予用户调整流程的自主权

上下文管理：

全程如果发现用户提及的内容存在上下文缺口，主动提出询问
不要让缺口累积——及时解决

工件管理：

使用
```
create_file
```
起草完整章节
使用
```
str_replace
```
进行所有编辑
每次更改后提供工件链接
不要使用工件存储头脑风暴列表——这些内容仅在对话中处理

质量优先于速度：

不要仓促完成各个阶段
每次迭代都应带来有意义的改进
目标是创建一份真正对读者有效的文档",