​

Doc Co-Authoring Workflow

The Doc Co-Authoring skill provides a structured, three-stage workflow for creating high-quality documentation. It helps users efficiently transfer context, refine content through iteration, and verify the document works for readers before sharing.

​

When to Use

Trigger this skill when:

• 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 is starting a substantial writing task that needs structure

Supported document types: Technical specs, decision documents, proposals, RFCs, PRDs, design docs, status reports, project plans

​

Workflow Overview

The skill guides you through three distinct stages:

Stage 1: Context Gathering

Goal: Close the gap between what you know and what Claude knows

• Gather meta-context about the document (type, audience, purpose)
• Collect background information through info dumps
• Ask clarifying questions to fill knowledge gaps
• Pull context from connected tools (Slack, Google Drive, etc.)

Stage 2: Refinement & Structure

Goal: Build the document section by section through iteration

• Create document structure with sections
• For each section: ask questions, brainstorm options, curate, draft, refine
• Use surgical edits rather than full rewrites
• Learn your style and preferences as you go

Stage 3: Reader Testing

Goal: Verify the document works for readers without context

• Test with a fresh Claude instance (no context bleed)
• Predict and verify common reader questions
• Identify blind spots and ambiguities
• Fix gaps before others read it

​

Stage 1: Context Gathering

The first stage focuses on transferring knowledge efficiently.

​

Initial Questions

Claude will ask for meta-context:

1. What type of document is this?
2. Who’s the primary audience?
3. What’s the desired impact when someone reads this?
4. Is there a template or specific format to follow?
5. Any other constraints or context to know?

​

Information Dumping

Provide context through multiple methods:

• Stream-of-consciousness info dumps
• Links to team channels or threads
• Shared documents (Google Drive, SharePoint)
• Related discussions or decisions
• Organizational context (team dynamics, politics)
• Timeline pressures or constraints

​

Clarifying Questions

After initial context, Claude generates 5-10 numbered questions based on gaps. You can answer:

• In shorthand: “1: yes, 2: see #channel, 3: no because backwards compat”
• By linking to more docs
• By pointing to channels to read
• By continuing to info-dump

Exit condition: You’ve gathered sufficient context when questions show deep understanding - edge cases and trade-offs can be discussed without needing basics explained.

​

Stage 2: Refinement & Structure

This stage builds the document iteratively, section by section.

​

Document Structure

Claude will suggest 3-5 sections appropriate for your doc type, or use your provided template. The structure is created with placeholders:

• With artifacts (Claude.ai): Creates an artifact you can view and reference
• Without artifacts: Creates a markdown file in your working directory

​

Section-by-Section Process

For each section, follow this iterative process:

Step 1: Clarifying Questions

Claude asks 5-10 questions about what should be included in this specific section.Answer in shorthand or indicate what’s important to cover.

Step 2: Brainstorming

Claude generates 5-20 possible points to include, based on:

• Context you’ve shared
• Angles or considerations not yet mentioned
• Section-specific requirements

You’ll see things you may have forgotten plus new perspectives.

Step 3: Curation

Indicate which points to keep, remove, or combine:

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

Freeform feedback also works - Claude will extract your preferences.

Step 4: Gap Check

Claude asks if anything important is missing before drafting.

Step 5: Drafting

Claude drafts the section using str_replace to update the document.Instead of editing directly, tell Claude what to change. This helps it learn your style for future sections.

Step 6: Iterative Refinement

Provide feedback on the draft:

• “Remove the X bullet - already covered by Y”
• “Make the third paragraph more concise”
• “Add more technical detail about the implementation”

Claude makes surgical edits without reprinting the whole doc.

​

Quality Checking

After 3 iterations with no substantial changes, Claude asks if anything can be removed without losing important information. This keeps the document tight and focused.

​

Stage 3: Reader Testing

The final stage verifies your document works for readers without your context.

​

Testing Methods

With Sub-Agents (Claude Code)

Claude performs testing automatically:

1. Predict Reader Questions: Generates 5-10 realistic questions readers would ask
2. Test with Fresh Claude: Each question is tested with a new Claude instance that only sees the document (no conversation context)
3. Run Checks: Tests for ambiguity, false assumptions, and contradictions
4. Report Results: Identifies what Reader Claude got right/wrong

If issues are found, Claude loops back to refinement for problematic sections.

Without Sub-Agents (Claude.ai)

You perform testing manually:

1. Generate Questions: Claude suggests 5-10 questions readers would ask
2. Open Fresh Session: You open https://claude.ai in a new conversation
3. Test Questions: Paste/share the document and ask Reader Claude each question
4. Check Understanding: Note what Reader Claude answers correctly or misinterprets
5. Additional Checks: Ask Reader Claude about ambiguities, assumptions, and contradictions
6. Report Back: Tell Claude what Reader Claude struggled with, and it will fix those gaps

​

Exit Condition

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

​

Final Review

Before completion, Claude recommends:

1. Do a final read-through yourself - you own this document
2. Double-check facts, links, and technical details
3. Verify it achieves the impact you wanted
4. Consider linking the conversation in an appendix
5. Use appendices for depth without bloating the main doc

​

Workflow Tips

​

Tone and Approach

• Direct and procedural - no unnecessary sales pitch
• Brief rationale when it affects your behavior
• You always have agency to adjust the process

​

Handling Deviations

• Want to skip a stage? Claude can switch to freeform writing
• Feeling frustrated? Claude can suggest ways to move faster
• You control the pace and depth of each stage

​

Context Management

• Claude proactively asks when context is missing
• Gaps are addressed as they come up, not accumulated
• The more context provided early, the better the output

​

Best Practices

1. Front-load context: The more context in Stage 1, the smoother Stage 2 becomes
2. Start with complex sections: Build the hardest parts first while context is fresh
3. Be specific with feedback: “Make it shorter” is less helpful than “Remove the technical jargon for non-technical readers”
4. Let Claude learn your style: Indicate changes rather than editing directly, especially early on
5. Trust the reader testing: Fresh eyes (even AI eyes) catch what authors miss

​

Document Types Supported

The workflow adapts to various document types:

• Technical Specs: Focus on architecture, implementation, and technical decisions
• Decision Docs: Emphasize options considered, trade-offs, and the chosen path
• Proposals: Highlight problem, solution, impact, and resource requirements
• RFCs: Structure around problem statement, proposed solution, alternatives, and open questions
• PRDs: Cover user needs, features, success metrics, and timeline

​

Related Skills

• Internal Comms: For structured internal communication formats (3P updates, newsletters)
• Brand Guidelines: To apply brand styling to completed documents