anthropics/skills · skills/doc-coauthoring/SKILL.md
doc-coauthoring
“A patient doc-writing coach that tests your draft on a fresh Claude before your team ever sees it”
What it does
Walks the user through writing a spec, proposal or decision doc in three stages: gather context, build each section by brainstorming and curating, then test the draft on a context-free Claude to find blind spots.
- When the agent uses it
- When a user wants to write or draft documentation, a proposal, a technical spec, a decision doc or similar structured content.
- Who it is for
- Install it if you write design docs, RFCs or PRDs with an agent. Skip it if you want quick one-shot drafts; this is a long, question-heavy process.
- What it costs
- 236 lines, about 4.3k tokens once the agent loads it.
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
What it tells the agent to do
- Offer the three-stage workflow, or work freeform if the user declines
- Ask about doc type, audience, impact and template, take an info dump, then ask 5-10 numbered clarifying questions
- Agree on 3-5 sections and create a scaffold artifact or markdown file with placeholders
- For each section: ask questions, brainstorm 5-20 options, have the user curate them, draft, and refine with str_replace
- Re-read the whole doc for flow, contradictions and filler
- Reader-test with a fresh sub-agent, or have the user test manually in claude.ai, and loop back on any gaps
- Recommend a final human read-through and fact check, then close out
Lines worth reading
Straight from the file, with why each one matters.
line 22Test the doc with a fresh Claude (no context) to catch blind spots before others read it
The best idea here: a reader with no context shows what the doc assumes. That is a real check, not 'review it carefully'.
line 941: yes, 2: see #channel, 3: no because backwards compat
A concrete example of shorthand answers. It makes long Q&A rounds cheap for the user.
line 203Instead of editing the doc directly, ask them to indicate what to change.
Telling: the agent learns your style from your feedback, but you give up the habit of just fixing it yourself.
line 228Anything that feels like "slop" or generic filler
A skill that tells the model to hunt its own slop. Refreshingly honest.
line 60Organizational context (team dynamics, past incidents, politics)
It asks for the gossip. That helps the doc land, but think about where that context ends up.
Watch out for
- Low
It invites sensitive org context (politics, incidents), then suggests linking the whole conversation in the doc's appendix, which could expose it to readers.
line 346Consider linking this conversation in an appendix so readers can see how the doc was developed
- Low
When the user mentions channels or docs, it reads them via Slack, Drive and similar connectors right away, after only an announcement.
line 79Inform them the content will be read now, then use the appropriate integration
- Low
Reader testing runs several sub-agents without asking, which costs tokens and time.
line 253Perform the testing directly without user involvement.
The scorecard
- TriggerSays when to use it8/10
Clear 'use when' with doc types, but PRD, RFC and design doc are only in the body
- FocusOne clear job9/10
One job: co-writing a structured doc, start to finish
- LeanLight to load6/10
Under 500 lines but padded with 'Announce…' lines; Reader Testing could live in a file
- ConcreteSteps you can follow7/10
Good counts, examples and exit conditions; a few steps contradict each other
- SafeSafe to run9/10
No commands or downloads; only connector reads and an appendix-sharing tip
What it does well
- Reader Testing with a context-free sub-agent is a real way to check the result, with a clear exit condition
- Numbered brainstorm lists and curation examples ('Keep 1,4,7,9') make feedback fast and unambiguous
- It handles both setups: artifacts or files, sub-agents or manual testing in claude.ai
How it could be better
Put the body's trigger words in the description
PRD, RFC and design doc appear only on line 14, which the agent never sees before it loads the skill.
Adddescription: Co-write structured documents with the user: technical specs, design docs, PRDs, RFCs, proposals and decision docs. Use when the user asks to write a doc, draft a proposal, create a spec or write up a decision. Gathers context, builds the doc section by section, then tests it on a fresh reader.
Fix the conflicting tool instructions
Line 188 drafts with str_replace, but line 367 says to use create_file for drafting full sections.
Add**Artifact Management:** - Use `create_file` once, for the initial scaffold - Use `str_replace` for drafting and all later edits
Move Reader Testing to a reference file
The two testing paths, plus many 'Announce…' lines, load on every use; a linked file keeps SKILL.md lean.
Add## Stage 3: Reader Testing Test the doc with a context-free reader. Follow [reader-testing.md](reader-testing.md): use sub-agents if available, otherwise give the user the manual steps.
Warn before sharing the conversation
The conversation may hold the politics and incident details gathered in Stage 1.
Add- If you link this conversation in an appendix, first check it for sensitive context (politics, incidents, names) that readers should not see
Kin reviews against Anthropic’s Extend Claude with skills and agentskills.io’s the Agent Skills standard. It reads SKILL.md only, so a script beside it can still do things the file does not say.