doc-coauthoring
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDoc 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.
首先向用户询问文档的元上下文信息:
- 这是什么类型的文档?(例如:技术规范、决策文档、提案)
- 主要受众是谁?
- 读者阅读后期望达到什么效果?
- 是否有需要遵循的模板或特定格式?
- 还有其他约束条件或需要了解的上下文吗?
告知用户可以用简写或任意方式提供信息。
如果用户提供模板或提及特定文档类型:
- 询问用户是否可以分享模板文档
- 如果用户提供共享文档链接,使用相应集成获取内容
- 如果用户提供文件,则读取该文件
如果用户提及要编辑现有共享文档:
- 使用相应集成读取文档当前状态
- 检查是否存在无替代文本的图片
- 如果存在无替代文本的图片,说明当他人使用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会提出澄清问题。
上下文收集期间:
-
如果用户提及团队频道或共享文档:
- 如果有可用集成:告知用户将立即读取内容,然后使用相应集成
- 如果无可用集成:说明无法访问,建议用户在Claude设置中启用连接器,或直接粘贴相关内容。
-
如果用户提及未知的实体/项目:
- 询问是否应通过连接的工具搜索相关信息
- 等待用户确认后再进行搜索
-
在用户提供上下文时,记录已了解的信息和仍不明确的内容
提出澄清问题:
当用户表示完成初始信息汇总(或提供了大量上下文后),提出澄清问题以确保理解到位:
根据上下文缺口生成5-10个编号问题。
告知用户可以用简写回答(例如:“1: 是,2: 查看#频道,3: 不行,因为要向后兼容”),也可以链接到更多文档、指向要读取的频道,或继续汇总信息。选择最高效的方式即可。
退出条件:
当问题能体现对内容的理解——能够询问边缘情况和权衡问题,无需再解释基础知识时,说明已收集到足够的上下文。
过渡:
询问用户是否还有其他上下文要补充,还是可以进入文档起草阶段。
如果用户想要补充更多信息,允许其继续。准备就绪后,进入第二阶段。
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 to create an artifact. This gives both Claude and the user a scaffold to work from.
create_fileInform 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.mdtechnical-spec.mdInform 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-20个内容选项
- 用户指示保留/删除/合并哪些内容
- 起草该章节
- 通过精准编辑进行优化
从信息最不明确的章节开始(通常是核心决策/提案),然后处理其余章节。
章节顺序:
如果文档结构明确:
询问用户想从哪个章节开始。
建议从信息最不明确的章节开始。对于决策文档,通常是核心提案;对于规范文档,通常是技术方案。摘要章节最好放在最后。
如果用户不知道需要哪些章节:
根据文档类型和模板,建议3-5个适合该文档类型的章节。
询问用户该结构是否可行,或是否需要调整。
一旦确定结构:
创建包含所有章节占位符文本的初始文档结构。
如果可以访问工件:
使用创建工件,为Claude和用户提供一个工作框架。
create_file告知用户将创建包含所有章节占位符的初始结构。
创建包含所有章节标题和简短占位符文本(如“[待编写]”或“[此处添加内容]”)的工件。
提供框架链接,并表示可以开始填充每个章节。
如果无法访问工件:
在工作目录中创建Markdown文件,命名要恰当(例如:、)。
decision-doc.mdtechnical-spec.md告知用户将创建包含所有章节占位符的初始结构。
创建包含所有章节标题和占位符文本的文件。
确认文件已创建,并表示可以开始填充每个章节。
对于每个章节:
Step 1: Clarifying Questions
步骤1:澄清问题
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-10个关于内容的澄清问题:
根据上下文和章节目的生成5-10个具体问题。
告知用户可以用简写回答,或只需指出需要涵盖的重点。
Step 2: Brainstorming
步骤2:头脑风暴
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-20个可能包含的内容。重点关注:
- 用户分享但可能被遗忘的上下文
- 尚未提及的角度或考虑因素
根据章节复杂度生成5-20个编号选项。最后询问用户是否需要更多选项。
Step 3: Curation
步骤3:筛选
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.
询问用户哪些要点需要保留、删除或合并。请求提供简短理由,以便了解后续章节的优先级。
提供示例:
- “保留1、4、7、9”
- “删除3(与1重复)”
- “删除6(受众已了解此内容)”
- “合并11和12”
如果用户给出自由形式的反馈(例如:“看起来不错”或“我大部分都喜欢,但...”)而非编号选择,则提取用户偏好并继续。解析用户想要保留/删除/修改的内容并应用。
Step 4: Gap Check
步骤4:缺口检查
Based on what they've selected, ask if there's anything important missing for the [SECTION NAME] section.
根据用户选择的内容,询问【章节名称】章节是否遗漏了重要信息。
Step 5: Drafting
步骤5:起草
Use to replace the placeholder text for this section with the actual drafted content.
str_replaceAnnounce 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".
使用将该章节的占位符文本替换为实际起草内容。
str_replace宣布将根据用户选择起草【章节名称】章节。
如果使用工件:
起草完成后,提供工件链接。
请用户阅读并指出需要修改的内容。注意,具体的修改建议有助于Claude学习用户偏好,以便优化后续章节。
如果使用文件(无工件):
起草完成后,确认完成。
告知用户【章节名称】章节已在[文件名]中起草完成,请用户阅读并指出需要修改的内容。注意,具体的修改建议有助于Claude学习用户偏好,以便优化后续章节。
给用户的关键说明(起草第一个章节时包含):
提示用户:请不要直接编辑文档,而是指出需要修改的内容。这有助于Claude学习用户的写作风格,以便优化后续章节。例如:“删除X项目符号——已被Y涵盖”或“将第三段写得更简洁”。
Step 6: Iterative Refinement
步骤6:迭代优化
As user provides feedback:
- Use to make edits (never reprint the whole doc)
str_replace - 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 - 如果使用工件: 每次编辑后提供工件链接
- 如果使用文件: 只需确认编辑完成
- 如果用户直接编辑文档并要求Claude读取:记录用户所做的修改,在后续章节中参考这些偏好
持续迭代直到用户对该章节满意。
Quality Checking
质量检查
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.
在连续3次迭代无实质性修改后,询问用户是否可以删除某些内容而不丢失重要信息。
章节完成后,确认【章节名称】已完成。询问用户是否准备好进入下一章节。
对所有章节重复上述步骤。
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.
当文档完成80%以上章节时,宣布将重新阅读整个文档,检查以下内容:
- 章节间的连贯性和一致性
- 冗余或矛盾内容
- 任何“冗余”或通用填充内容
- 每个句子是否有实际意义
阅读整个文档并提供反馈。
当所有章节起草并优化完成后:
宣布所有章节已起草完成,将再次通读完整文档进行最终检查。
检查整体连贯性、流畅性和完整性。
提供最终建议。
询问用户是否准备好进入读者测试阶段,还是需要进一步优化内容。
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.
目标: 使用无上下文的全新Claude实例测试文档,验证文档对读者的可用性。
给用户的说明:
解释将进行测试,查看文档对读者是否真正有效。这能发现盲区——对作者来说合理,但可能让他人困惑的内容。
Testing Approach
测试方法
If access to sub-agents is available (e.g., in Claude Code):
Perform the testing directly without user involvement.
如果可以访问子代理(例如在Claude Code中):
无需用户参与,直接进行测试。
Step 1: Predict Reader Questions
步骤1:预测读者问题
Announce intention to predict what questions readers might ask when trying to discover this document.
Generate 5-10 questions that readers would realistically ask.
宣布将预测读者在阅读此文档时可能提出的问题。
生成5-10个读者可能会提出的真实问题。
Step 2: Test with Sub-Agent
步骤2:子代理测试
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.
宣布将使用无本次对话上下文的全新Claude实例测试这些问题。
针对每个问题,仅使用文档内容和问题调用子代理。
总结每个问题的测试结果,即读者Claude回答的对错情况。
Step 3: Run Additional Checks
步骤3:额外检查
Announce additional checks will be performed.
Invoke sub-agent to check for ambiguity, false assumptions, contradictions.
Summarize any issues found.
宣布将进行额外检查。
调用子代理检查文档中的歧义、错误假设和矛盾内容。
总结发现的问题。
Step 4: Report and Fix
步骤4:报告与修复
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.
如果发现问题:
报告读者Claude在某些问题上存在困难。
列出具体问题。
表示将修复这些缺口。
返回优化阶段处理有问题的章节。
如果无法访问子代理(例如claude.ai网页端):
需要用户手动进行测试。
Step 1: Predict Reader Questions
步骤1:预测读者问题
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.ai中输入什么内容?
生成5-10个读者可能会提出的真实问题。
Step 2: Setup Testing
步骤2:测试设置
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对话:https://claude.ai
- 粘贴或分享文档内容(如果使用带连接器的共享文档平台,提供链接)
- 向读者Claude提出生成的问题
针对每个问题,指示读者Claude提供:
- 答案
- 是否存在歧义或不明确内容
- 文档假设读者已具备哪些知识/上下文
检查读者Claude是否能给出正确答案,或是否存在误解。
Step 3: Additional Checks
步骤3:额外检查
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询问:
- “此文档中哪些内容可能对读者来说存在歧义或不明确?”
- “此文档假设读者已具备哪些知识或上下文?”
- “文档中是否存在内部矛盾或不一致内容?”
Step 4: Iterate Based on Results
步骤4:根据结果迭代
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)
退出条件(两种方法通用)
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 for drafting full sections
create_file - Use for all edits
str_replace - 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
语气:
- 直接且有条理
- 当影响用户行为时,简要解释理由
- 不要试图“推销”此方法,只需执行即可
处理偏差:
- 如果用户想要跳过某个阶段:询问用户是否要跳过此阶段并采用自由创作模式
- 如果用户似乎感到沮丧:承认过程比预期耗时,建议加快进度的方法
- 始终给予用户调整流程的自主权
上下文管理:
- 全程如果发现提及的内容存在上下文缺口,主动询问
- 不要让缺口累积——出现时立即解决
工件管理:
- 使用起草完整章节
create_file - 使用进行所有编辑
str_replace - 每次修改后提供工件链接
- 绝不使用工件存储头脑风暴列表——这些内容仅在对话中进行
质量优先于速度:
- 不要急于完成各个阶段
- 每次迭代都应带来有意义的改进
- 目标是创建一份真正对读者有效的文档