doc-coauthoring

Document Collaboration Workflow

This skill provides a structured workflow for guiding users through collaborative document creation. As an active facilitator, lead users through three phases: context gathering, refinement and structuring, and reader testing.

When to Offer This Workflow

Trigger conditions:

• The user mentions writing a document: "write a document", "draft a proposal", "create a specification", "write a report"
• The user mentions a specific document type: "PRD", "design doc", "decision doc", "RFC"
• The user seems to be about to start a significant writing task

Initial offer: Offer the user a structured document collaboration workflow. Explain the three phases:

1. Context gathering: the user provides all relevant context while Claude asks clarifying questions
2. Refinement and structuring: iteratively build each section through brainstorming and editing
3. Reader testing: test the document with a fresh Claude (no context) to find blind spots before others read it

Explain that this approach helps ensure the document works well when others read it (including when they paste it into Claude). Ask whether they want to try this workflow or prefer to work in a free-form way.

If the user declines, work in a free-form way. If the user accepts, proceed to Phase 1.

Phase 1: Context Gathering

Goal: Narrow the gap between what the user knows and what Claude knows, laying the foundation for intelligent guidance later.

Initial Questions

First ask the user for meta-information about the document:

1. What type of document is this? (e.g., technical specification, decision document, proposal)
2. Who is the primary audience?
3. What impact is expected when others read this document?
4. Is there a template or specific format to follow?
5. Are there any other constraints or context to know about?

Tell them they can answer briefly, or dump information in whatever way is most convenient for them.

If the user provides a template or mentions a document type:

• Ask whether 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 directly

If the user mentions editing an existing shared document:

• Use the appropriate integration to read the current state
• Check for images without alt text
• If there are images without alt text, explain that when others use Claude to understand the document, Claude will not be able to see these images. Ask whether they want to generate alt text. If so, ask them to paste each image into the chat to generate descriptive alt text.

Information Dump

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

• Background of the project/problem
• Relevant team discussions or shared documents
• Why alternatives were not used
• Organizational context (team dynamics, past incidents, political factors)
• Time pressure or constraints
• Technical architecture or dependencies
• Stakeholder concerns

Advise them not to worry about organizing the information—just dump it all out. Offer multiple ways to provide context:

• Stream-of-consciousness information dump
• Point to a team channel or thread to read
• Link to a shared document

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

If no integration is detected and on Claude.ai or the Claude app: Suggest that they can enable connectors in Claude settings to pull context directly from messaging apps and document storage.

Inform them that clarifying questions will be asked after the initial information dump is complete.

During the context collection process:

• If the user mentions a team channel or shared document:

  • If an integration is available: inform them that the content will be read now, then use the appropriate integration
  • If no integration is available: explain that it cannot be accessed. Suggest that they enable connectors in Claude settings, or paste the relevant content directly.

• If the user mentions an unfamiliar entity/project:

  • Ask whether connected tools should be searched for more information
  • Wait for user confirmation before searching

• As the user provides context, track what has been learned and what is still unclear

Ask clarifying questions:

When the user indicates they have finished the initial information dump (or after a substantial amount of context has been provided), ask clarifying questions to ensure understanding:

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

Inform them that they can answer briefly (e.g., "1: yes, 2: see #channel, 3: no because of backward compatibility"), link to more documents, point to a channel to read, or continue dumping information. Whatever is most efficient for them.

Exit condition: When the questions demonstrate understanding, enough context has been collected—when edge cases and trade-offs can be asked about without needing to explain the basics.

Transition: Ask whether they have any more context to provide at this stage, or whether it is time to start drafting the document.

If the user wants to add more, let them add it. When ready, proceed to Phase 2.

Phase 2: Refinement and Structuring

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

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

1. Clarifying questions will be asked about what to include
2. 5-20 options will be brainstormed
3. The user indicates what to keep/delete/merge
4. The section is drafted
5. It is refined through precise edits

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

Section ordering:

If the document structure is clear: Ask them which section they want to start with.

Suggest starting with the section with the most unknowns. For decision documents, this is usually the core proposal. For specifications, this is usually the technical approach. Summary sections are best left for last.

If the user doesn't know which sections they need: Based on the document type and template, suggest 3-5 sections suitable for that document type.

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

Once the structure is agreed upon:

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

If artifacts are available: Use create_file to create an artifact. This gives Claude and the user a framework to work with.

Let them know you will create an initial structure containing placeholders for all sections.

Create an artifact containing all section headings and brief placeholder text (such as "[To be written]" or "[Fill in content here]").

Provide the framework link and point out that it's time to fill in each section.

If there is no artifacts access: Create a markdown file in the working directory. Name it appropriately (for example decision-doc.md、technical-spec.md）。

Let them know you will create an initial structure containing placeholders for all sections.

Create a file containing all section headings and placeholder text.

Confirm that the file name has been created and point out that it's time to fill in each section.

For each section:

Step 1: Clarifying questions

Announce that you will begin working on the [section name] section. Ask 5-10 clarifying questions about what should be included:

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

Let them know they can answer briefly, or simply point out what's important.

Step 2: Brainstorming

For the [section name] section, brainstorm [5-20] possible items to include based on the complexity of the section. Look for:

• Shared context that may have been forgotten
• Angles or considerations not yet mentioned

Generate 5-20 numbered options based on the complexity of the section. Finally, if they want more options, offer the choice to continue brainstorming.

Step 3: Filtering

Ask which points should be kept, removed, or merged. Request brief reasons to help understand the priorities for the next section.

Provide examples:

• "Keep 1,4,7,9"
• "Remove 3 (duplicate of 1)"
• "Remove 6 (the reader already knows this)"
• "Merge 11 and 12"

If the user gives free-form feedback(such as "looks good" or "I like most of it but...") instead of numbered choices, extract their preferences and continue. Parse what they want to keep/remove/change and apply it.

Step 4: Gap check

Based on what they selected, ask whether the [section name] section is missing anything important.

Step 5: Drafting

Use str_replace to replace the placeholder text for that section with the actual drafted content.

Announce that you will draft the [section name] section based on what they selected.

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

Ask them to read it and point out what to change. Note that specific feedback helps learning for the next section.

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

Tell them that the [section name] section has been drafted in [file name]. Ask them to read it and point out what to change. Note that specific feedback helps learning for the next section.

Key instructions for the user (include when drafting the first section): Provide instructions: instead of editing the document directly, ask them to point out what to change. This helps learn their style for use in subsequent sections. For example: "Remove point X - Y already covers it" or "make the third paragraph more concise."

Step 6: Iterative refinement

When the user provides feedback:

• Use str_replace to make edits (never reprint the entire document)
• If using artifacts: provide the artifact link after each edit
• If using files: just confirm the edit is complete
• If the user edits the document directly and asks for a read: mentally note the changes they made, and keep them in mind in subsequent sections (this shows their preferences)

Continue iterating until the user is satisfied with the section.

Quality check

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

When the section is complete, confirm that [section name] is complete. Ask whether they are ready to move on to the next section.

Repeat this process for all sections.

Approaching completion

When approaching completion (80% or more of the sections complete), announce the intention to reread the entire document and check:

• Flow and consistency between sections
• Redundancy or contradictions
• Anything that feels like "fluff" or generic filler
• Whether every sentence carries weight

Read the entire document and provide feedback.

When all sections have been drafted and refined: Announce that all sections have been drafted. State the intention to review the complete document again.

Review overall coherence, flow, and completeness.

Provide any final suggestions.

Ask whether they are ready to move on to reader testing, or whether they want to refine anything else.

Phase 3: Reader testing

Goal: Test the document with a brand-new Claude (no context contamination) to verify whether it works for readers.

Instructions for the user: Explain that testing will now be performed to see whether the document truly works for readers. This can reveal blind spots—content that makes sense to the author but may confuse others.

Testing method

If subagents can be used (for example in Claude Code):

Perform the test directly, without user involvement.

Step 1: Predict reader questions

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

Generate 5-10 questions that readers might actually ask.

Step 2: Test with subagents

Announce that a fresh Claude instance (without the context of this conversation) will be used to test these questions.

For each question, call a subagent with only the document content and the question.

Summarize what the reader Claude got right or wrong for each question.

Step 3: Run additional checks

Announce that additional checks will be performed.

Call a subagent to check for ambiguity, wrong assumptions, and contradictions.

Summarize any issues found.

Step 4: Report and fix

If issues are found: Report that the reader Claude had difficulty with specific questions.

List the specific issues.

State the intention to fix these gaps.

Return to the problematic sections to refine them.

---

If there is no subagent access (e.g., the claude.ai web interface):

The user needs to test manually.

Step 1: Predict reader questions

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 might actually ask.

Step 2: Set up the test

Provide test instructions:

1. Open a new Claude conversation:https://claude.ai
2. Paste or share the document content (if using a shared document platform with connectors enabled, provide a link)
3. Ask the reader Claude the generated questions

For each question, instruct the reader Claude to provide:

• The answer
• Whether anything is ambiguous or unclear
• What knowledge/context the document assumes the reader already knows

Check whether the reader Claude gives correct answers or misunderstands anything.

Step 3: Additional checks

Also ask the reader Claude:

• "What in this document might be ambiguous or unclear to readers?"
• "What knowledge or context does this document assume the reader already has?"
• "Are there any internal contradictions or inconsistencies?"

Step 4: Iterate based on the results

Ask what the reader Claude got wrong or where it had difficulty. State the intention to fix these gaps.

Return to the problematic sections to refine them.

---

Exit conditions (both methods)

The document is ready when the reader Claude can consistently answer the questions correctly and no new gaps or ambiguities are found.

Final review

When the reader test passes: Announce that the document has passed the reader Claude test. Before finishing:

1. Suggest they do one final read-through themselves—they own this document and are responsible for its quality
2. Suggest carefully checking any facts, links, or technical details
3. Ask them to verify that it achieves the intended impact

Ask whether they want to review it again or whether the work is done.

If the user wants a final review, provide it. Otherwise: Announce that the document is complete. Provide some final tips:

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

Tips for effective guidance

Tone:

• Direct and procedural
• Briefly explain the reasoning when it affects user behavior
• Do not try to "sell" this method—just execute it

Handling deviations:

• If the user wants to skip a stage: ask whether they want to skip this step and write in free form
• If the user seems frustrated: acknowledge that this is taking longer than expected. Suggest ways to speed up
• Always give the user the initiative to adjust the process

Context management:

• Throughout, if there is a lack of context about something mentioned, proactively ask
• Do not let gaps accumulate—resolve them immediately when discovered

Artifact management:

• Use create_file to draft complete sections
• Use str_replace for all edits
• Provide the artifact link after each change
• Never use artifacts for brainstorming lists—that is just conversation

Quality over speed:

• Do not rush through the stages
• Each iteration should be a meaningful improvement
• The goal is a document that truly works for the reader