Foreword

Writing documentation is an unavoidable high-frequency task for developers: technical solutions need to be finalized into specs, architecture trade-offs must be documented as decision docs, and PRDs or RFCs must be drafted before new features go live. The common difficulty of these documents is not “whether you can write them”, but “whether readers can understand them after you finish writing”. The author has full context in their mind, but the reader does not; the background you omitted is unreadable to others; the terms you assume the entire team knows leave newbies confused.

Asking an AI to generate the full text at once often results in a “template text” that is structurally neat but empty in content; drafting from scratch yourself can easily get bogged down in details and miss key constraints. The doc-coauthoring provided by Anthropic in their official Skills repository takes a different approach: instead of writing the entire document for you at once, it guides you through a three-stage workflow of context gathering → section-by-section refinement → reader testing to co-create a truly deliverable structured document. This article introduces the positioning, capabilities and usage of this Skill based on the official SKILL.md and repository documentation.

What is this

doc-coauthoring is an Agent Skill maintained by Anthropic. The repository address is:
https://github.com/anthropics/skills/tree/main/skills/doc-coauthoring

It follows the universal SKILL.md format and can be used in environments that support Agent Skills such as Cursor, Claude Code, and Claude.ai. The core positioning of the Skill is: when a user wants to write structured content such as documents, proposals, technical specifications, or decision documents, the Agent actively guides the user through a repeatable co-creation process, rather than freely playing the role of “write an article for me”.

The official description summarizes three goals: efficiently transfer context, refine content through iteration, and verify whether the document is readable before handing it over to real readers.

Core Features and Highlights

1. Three-stage Workflow

The entire Skill splits document writing into three stages, and the Agent will guide them in order. Users can also choose to skip stages and write freely at any time:
1. Context Gathering: First ask meta questions such as document type, audience, expected impact, and template constraints, then encourage users to “dump all information” — background, team discussions, reasons for rejected options, organizational constraints, timelines, technical dependencies, etc. — without having to organize the format first. The Agent will generate 5–10 clarifying questions to fill in understanding gaps.
2. Refinement & Structure: Proceed section by section according to the chapter structure. Each section goes through a cycle of “clarifying questions → brainstorm 5–20 candidate points → user filters to keep/delete/merge → gap check → drafting → iterative modification”. Prioritize starting with the sections with the highest uncertainty (such as the core solution for decision documents, technical solutions for specs), while summary chapters are usually placed last.
3. Reader Testing: Use a brand new Claude instance that has not participated in the co-creation context to simulate real readers asking questions, and check whether the document has blind spots from the author’s perspective. This can be executed automatically in environments that support sub-agents such as Claude Code; otherwise, manual testing steps will be provided.

2. Automatic Trigger and Optional Processes

The Skill will actively offer the structured workflow when the user mentions the following scenarios:
- Writing intentions such as “write a doc”, “draft a proposal”, “create a spec”, “write up”, etc.
- Specific document types such as PRD, design doc, decision doc, RFC, etc.
- Users clearly starting a large writing task

The Agent will first explain the three-stage workflow and ask the user whether to adopt it; if the user refuses, it will switch back to free writing mode.

3. Section-by-section Co-creation, Not One-time Generation

The design of Stage 2 is the key difference between doc-coauthoring and ordinary “help me write a document” prompts:
- First build the document skeleton (artifact or local Markdown file, with [To be written] placeholders for each section)
- Brainstorm each section individually, and the user can filter with short instructions (such as “keep 1,4,7; delete 3, it duplicates with 1”)
- Use str_replace for local modifications after drafting, avoiding full rewrites of the entire document
- If there are no substantial changes after three consecutive rounds, the Agent will actively ask “Can we delete more without losing information?”

This method forces the author to make trade-offs in each section, reducing the “filler talk” that AI generates on its own.

4. Reader Testing: Find Blind Spots Before Publishing

The idea of Stage 3 is very practical: the document will eventually be read by others (or other AIs). During testing, it will:
- Predict 5–10 questions that readers may ask
- Use a Claude without context to answer only based on the document content
- Additional checks for ambiguity, implicit premises, and internal contradictions

If the Reader Claude answers incorrectly or gets stuck, the workflow will return to Stage 2 to repair the corresponding section until the test passes.

5. External Context Access (Optional)

If the environment supports MCP connectors such as Slack, Teams, Google Drive, etc., the Skill will try to pull background information from team channels and shared documents; without integration, it will suggest that the user paste content or enable Claude Connectors. This part of the capability depends on the specific tool environment and is not available on all platforms.

Installation and Activation

Method 1: Project-level Manual Installation in Cursor

Create the Skill directory in the project root directory and download the official files:

mkdir -p .cursor/skills/doc-coauthoring
curl -o .cursor/skills/doc-coauthoring/SKILL.md \
  https://raw.githubusercontent.com/anthropics/skills/main/skills/doc-coauthoring/SKILL.md

Cursor will scan the SKILL.md under .cursor/skills/ when starting; you can also manually call it by entering /doc-coauthoring in the Agent conversation.

Method 2: Install via skills CLI

This Skill is included in skills.sh, and you can pull it via the command line:

npx skills add https://github.com/anthropics/skills --skill doc-coauthoring

The installation target path varies depending on the CLI configuration, commonly .cursor/skills/ or .agents/skills/ in the project.

Method 3: Claude Code Plugin

Anthropic’s official README provides the installation method for Claude Code:

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

After installing the example-skills plugin, doc-coauthoring will be available along with the sample skill set; you can trigger it by mentioning document writing needs in the conversation, or explicitly state “use the doc-coauthoring workflow”.

Method 4: Claude.ai

Anthropic’s sample Skills are partially available to paid Claude.ai users; see the official documentation Using skills in Claude for how to upload and enable custom Skills.

Typical Usage Example

The Skill does not require additional configuration files and is triggered via natural language after activation. Below is a common interaction path for a technical decision document (decision doc):

Step 1: Launch the Task

I want to write a decision doc explaining why we're migrating caching from Redis to Valkey, targeting backend teams and SREs. Use the doc-coauthoring workflow, let's go through the stages.

The Agent will first introduce the three-stage workflow and confirm whether to start Stage 1.

Step 2: Context Gathering (Stage 1)
Users can answer meta questions in shorthand, then dump background information:

1. decision doc
2. Backend + SRE, also for new hires
3. Hope readers can agree on the migration plan and know the rollback conditions after reading
4. The company has an ADR template, I'll paste it later
5. Must be completed before Q4, the old Redis cluster license expires

Background: The current Redis 6.x single cluster has 3 masters and 3 slaves, peak QPS is 80,000... (omitted)
Rejected option: Continue renewing Redis Enterprise, which costs 3 times as much as Valkey...

The Agent will follow up with 5–10 clarifying questions, such as migration window, data consistency requirements, who has veto power, etc.

Step 3: Section-by-section Refinement (Stage 2)
Taking the “Core Decision” section as an example, the Agent will:
1. Ask what key points this section should cover
2. List 5–20 candidate arguments (cost, compatibility, operational burden, community support, etc.)
3. Wait for the user’s filter: Keep 2,5,8,11; delete 6 (SRE already knows this); merge 3 and 4
4. Draft this section and ask the user to point out modifications: The third paragraph is too abstract, add a QPS comparison figure
5. Make local modifications and move to the next section

After all sections are completed, the Agent will read the full text to check for redundancy, contradictions, and “empty talk”.

Step 4: Reader Testing (Stage 3)
In Claude Code, the Agent may automatically start a sub-agent to test with the following questions:
- “What is the final solution recommended in this document?”
- “What are the rollback conditions?”
- “Why not continue using Redis Enterprise?”

If the Reader Claude gives a vague answer to “rollback conditions”, the workflow will return to Stage 2 to supplement the “Risks and Rollback” section.

In environments without sub-agents such as Cursor, the official Skill will provide manual steps: open a new conversation, paste the document, ask questions one by one, and verify the answers.

Applicable Scenarios and Notes

Who and what scenarios it suits:
- Need to write structured long texts such as technical specifications (specs), architecture decisions (ADR/decision docs), RFCs, PRDs, design documents, etc.
- The document needs to be reviewed by multiple people, or will be pasted into AI tools for secondary interpretation
- The author has complex context and cannot explain it all at once, hoping the Agent will help clarify the structure through questions
- The team has a fixed template, but hopes to control content quality instead of just filling in the template

Limitations and Notes:
- This is a workflow-based Skill, not a document template library; the output quality still depends on the context you provide and the filtering feedback in each round
- The complete three-stage process takes a long time; the Skill allows skipping stages or free writing, and you can just use Stage 1 to collect context when meeting deadlines
- Reader Testing works best in Claude Code; environments such as Cursor require manually opening a new conversation for testing
- Pulling external documents/channels depends on MCP or Connectors, and local plain text environments need to paste materials yourself
- The Anthropic README notes: the repository Skills are for demonstration and educational purposes only, please fully verify them yourself before using in a production environment

Summary

Writing documentation is difficult, often because of the gap between the “author’s perspective” and the “reader’s perspective”. The value of doc-coauthoring is to split this gap into three executable stages: first dump all context, then co-create section by section and polish each paragraph, and finally use a memory-free Reader Claude for acceptance testing. For developers who often need to write specs, decision documents, or proposals, it provides a reusable Agent-guided workflow, rather than another AI draft that will be discarded after generation.

Official Skill and complete workflow documentation:
https://github.com/anthropics/skills/tree/main/skills/doc-coauthoring