| name | Doc Co-Authoring Workflow |
| slug | doc-coauthoring |
| description | A three-stage structured document co-authoring workflow - Context Gathering / Refinement & Structure / Reader Testing. Triggered when user mentions writing docs, drafting proposals, or creating specs. Avoid the write-and-forget trap. |
| category | documentation |
| tags | ["ai","documentation","frontend","llm","security"] |
| source | {"url":"https://github.com/anthropics/skills/tree/9d2f1ae187231d8199c64b5b762e1bdf2244733d/skills/doc-coauthoring","fetched_at":"2026-06-12","commit":"9d2f1ae187231d8199c64b5b762e1bdf2244733d","license":"MIT","original_path":"skills/doc-coauthoring/SKILL.md"} |
| license | MIT |
| author | Anthropic (downstream pack: badhope) |
| version | 1.0.0 |
| created | 2026-06-12 |
| updated | 2026-06-19 |
| needs_review | false |
| quality | stable |
| inputs | [{"name":"doc_type","type":"string","required":true,"description":"Document type - RFC/design-doc/PRD/decision-record/runbook/tutorial/FAQ"},{"name":"audience","type":"string","required":true,"description":"Target audience for the document"},{"name":"current_stage","type":"string","required":false,"description":"Current workflow stage - gather/refine/test (default gather)"}] |
| output | {"format":"markdown","description":"Generated content based on the user request"} |
When to use
You're about to co-author a substantial document —
an RFC, a design doc, a PRD, a decision record, a
runbook, a tutorial. The user said "write a doc",
"draft a proposal", or "create a spec". The doc is
meant to be read by other humans (and often re-read
by an LLM later).
The three-stage workflow catches the most common
doc failures:
- Stage 1 — Context Gathering. The user dumps
what they know; the LLM asks clarifying questions.
Skipping this stage is the most common cause of
"the doc doesn't address the actual question" —
the author never said what they actually wanted.
- Stage 2 — Refinement & Structure. Iteratively
build each section. Brainstorm, then tighten. The
structure emerges from the content, not the other
way around.
- Stage 3 — Reader Testing. Test the doc with a
fresh LLM (no context from the co-authoring
session) and see if it works. This catches blind
spots the author has because they know too much.
The "Reader Testing" stage is the most novel and
the most easily skipped. A doc that doesn't survive
a fresh-LLM test will not survive a fresh-human
test.
Don't use this skill for one-line changelog
entries, commit messages, or comments in code.
Use a writing skill or just write it.
Inputs
| Field | Required | Notes |
|---|
doc_type | yes | Drives the section template. |
audience | yes | Drives depth and assumed context. |
current_stage | no | If omitted, start at stage 1. |
Output
Plain-text next step. Typical return (stage 1):
Current stage: Context Gathering
Audience: engineering team
Questions to ask the user:
- What is the decision or change this doc is
proposing / recording?
- Why now? What changes if we don't act?
- Who is the audience beyond "engineering team"
(e.g. on-call, security, leadership)?
- Are there constraints or non-goals the
proposal must respect?
- What is the desired reader action after
reading: align? review? approve? implement?
Section template (for stage 2):
1. Context: why this doc exists
2. Decision / Proposal: what we're doing
3. Alternatives considered
4. Open questions
5. Rollout plan
6. Risks
Next action: wait for the user's answers to the
questions; do NOT start drafting yet.
Prompt
You are co-authoring a substantial document with the
user. Follow the three stages in order. Do not skip
stage 3 (Reader Testing) — it's the most novel and
the most easily skipped.
1. Identify the doc type and audience.
Ask:
- What kind of doc? (RFC, design doc, PRD,
decision record, runbook, tutorial)
- Who reads this? (Engineering? Leadership?
External partners? On-call?)
- What's the desired reader action? (Align?
Review? Approve? Implement?)
The answer to "desired reader action" drives
the structure. A doc whose reader is supposed
to "approve" needs Risks and Open Questions
up front. A doc whose reader is supposed to
"implement" needs a Rollout plan and
concrete examples.
2. Stage 1 — Context Gathering.
Goal: the user dumps everything they know; you
ask clarifying questions.
- Ask 3-7 open-ended questions. Do NOT start
drafting until the user has answered.
- The questions should expose:
- the actual problem (not the surface
request)
- constraints and non-goals
- the audience and their prior context
- the desired reader action
- what would make the user say "this
doc is done"
- Capture the user's answers verbatim or
near-verbatim. The wording carries nuance
the LLM may not infer.
Do NOT skip this stage. A doc written without
context is a doc that doesn't address the
actual question.
3. Stage 2 — Refinement & Structure.
Goal: iteratively build each section.
For each section:
a) Brainstorm: the user (and you) dump
everything relevant. Don't worry about
order.
b) Cluster: group related ideas into
paragraphs.
c) Tighten: rewrite for clarity. Replace
phrases with shorter ones. Replace
adjectives with facts.
d) Move on to the next section.
The structure emerges from the content. Do NOT
pick a template first and force the content
into it. The template is a checklist at the
end, not a starting point.
Section templates (suggested, not required):
- RFC: Context, Proposal, Alternatives,
Open Questions, Rollout
- Design doc: Problem, Goals, Non-Goals,
Design, Alternatives, Open
Questions
- PRD: Background, Goals, User Stories,
Requirements, Out of Scope,
Open Questions
- Decision record: Context, Decision,
Consequences, Alternatives
- Runbook: Symptoms, Root Cause, Fix,
Verification, Escalation
- Tutorial: Goal, Prerequisites, Steps,
Verification, Next Steps
- FAQ: Audience context, Question,
Answer, Related
4. Stage 3 — Reader Testing.
Goal: confirm the doc works for a reader who
has none of the context the author has.
- Open a fresh LLM session (no chat history
from stages 1-2).
- Give it ONLY the doc text. No "we discussed
this earlier" references.
- Ask the reader-LLM to answer:
- What is this doc proposing / recording?
- What is the desired reader action?
- What are the open questions?
- What did the author forget to mention?
- If the reader-LLM's answer is materially
different from what the user intended, the
doc is broken. Fix and re-test.
Do NOT skip this stage. A doc that doesn't
survive a fresh-LLM test will not survive a
fresh-human test. The reader-LLM is a
cheap proxy for a busy colleague.
5. End-of-stage checklist.
Before declaring done:
- Reader-LLM can answer "what is this
proposing?" correctly.
- All "Open Questions" have a status
(open, deferred, answered, parked).
- The audience's prior context is
explicit, not assumed.
- The desired reader action is named.
- The non-goals are listed.
- The risks are named.
- The user has approved the final version.
When NOT to use
- The doc is a one-line changelog entry or
commit message. Use a writing skill or just
write it.
- You skip stage 1 (Context Gathering) and
start drafting from a template. The most
common doc failure is "doesn't address the
actual question". Stage 1 catches it.
- You treat the section template as a
starting point. The template is a checklist
at the end. Starting from the template
produces a doc that fits the template but
doesn't fit the content.
- You skip stage 3 (Reader Testing). A doc
that doesn't survive a fresh-LLM test will
not survive a fresh-human test. The reader
test is the cheapest way to catch blind spots
the author has.
- The reader-LLM's answer is materially
different from the user's intent and you
declare the doc done anyway. A doc the
reader can't understand is not a doc.
- You re-use the chat history from stages
1-2 in the reader test. The reader-LLM
has none of the context the author has. A
fresh session is the point.
- You write the doc for yourself, not the
audience. The audience drives depth and
assumed context. An exec doc that dives
into implementation details is wrong. An
engineering doc that hand-waves
implementation is also wrong.
- You forget the non-goals. A doc without
non-goals is a doc where everything is
in-scope. That's not a doc, that's a
brain dump.
- You ship before the user has approved.
Stage 3 is a check, not a sign-off. The
user has to say "yes" before the doc
goes to the audience.
- You treat the doc as a one-shot. Most
substantial docs are revised at least
once. Plan for iteration; the
three-stage workflow is the iteration
tool.
Example
Input:
doc_type: design-doc
audience: engineering team
current_stage: gather
Output:
Current stage: Context Gathering
Audience: engineering team
Questions to ask the user:
1. What is the change this doc is proposing?
(one sentence)
2. Why now? What changes if we don't act?
3. Are there constraints or non-goals the
proposal must respect (e.g. backward
compatibility, deadline, dependencies)?
4. Who is the audience beyond "engineering
team" (e.g. on-call, security, leadership)?
5. What is the desired reader action after
reading: align? review? approve?
implement?
6. What would make you say "this doc is done"?
Section template (for stage 2):
1. Problem
2. Goals
3. Non-Goals
4. Design
5. Alternatives Considered
6. Open Questions
7. Rollout
Next action: wait for the user's answers; do NOT
start drafting the doc.
Footguns
These are the bugs that bite every new user.
Check them before shipping:
-
Skipping Context Gathering: Starting to draft before understanding the actual question.
- how to detect: doc doesn't address what the user actually needed
- how to fix: always complete stage 1 before drafting
-
Writing for yourself, not the audience: Depth and context that doesn't match the reader.
- how to detect: exec finds it too technical; engineer finds it too shallow
- how to fix: match vocabulary and assumptions to the stated audience
-
Skipping Reader Testing: Assuming the doc is clear without verifying.
- how to detect: readers have questions that the doc should have answered
- how to fix: run reader test with fresh session, not the chat history
-
Not capturing non-goals: Doc that tries to cover everything.
- how to detect: doc is too broad, lacks focus
- how to fix: explicitly state what's NOT in scope
-
Shipping without user approval: Sending doc to audience before user signs off.
- how to detect: user says "that's not what I meant"
- how to fix: get explicit approval before distribution
