Menu
Use when user wants to write, refactor, or expand documentation (README, guides, API docs, runbooks, specification documents).
| name | doc-coauthoring |
| description | Use when user wants to write, refactor, or expand documentation (README, guides, API docs, runbooks, specification documents). |
| metadata | {"category":"authoring","audience":"general-coding-agent","maturity":"beta","kind":"task","reader_testing":"required"} |
Use this skill when the user wants to author, improve, or expand documentation through structured co-authoring. Documentation benefits from separated concerns—context discovery, structural design, content iteration, and validation through real readers—rather than a single linear draft-and-polish pass.
This skill splits the work into three stages: gather context and constraints, refine structure and content, and validate with reader feedback.
Documentation deserves structured co-authoring.
Good documentation emerges from clear audience intent, structured iteration, and validation with real readers—not from a single authorial pass. Separation of concerns—context gathering, design, content, validation—keeps documentation coherent, complete, and trusted by its readers.
A document written with reader feedback loops will always outpace one revised only by the author alone.
| Scenario | Use Doc-Coauthoring | Route Away |
|---|---|---|
| New README or user guide | Yes — gather context, design structure, write, test with readers | N/A |
| API or reference documentation | Yes — capture current state, organize logically, validate with examples | N/A |
| Architectural decision record | Yes — gather context, document decision + rationale, reader validation | N/A |
| Runbook or operational guide | Yes — gather workflows, organize by task, validate with operators | N/A |
| Inline code comments | No — edit directly or use code documentation skills | Use repository coding skills |
| Minor typos or style fixes | No — edit directly | Make the fix directly without skill invocation |
| Single-file tech spec update | No if scope is clear and unchanged; Yes if scope is ambiguous or will affect multiple readers | Ask user to clarify scope first |
| Copyediting or phrasing polish | No — edit directly in final review phase | Use a dedicated style pass, not this skill |
Before starting the workflow:
Documentation authoring proceeds through three stages. Each stage has a clear input, goal, and output. Follow the references below for detailed guidance on each stage.
Goal: Establish audience, purpose, scope, and constraints so the structure is grounded in real reader needs.
Input: Answers to the inputs listed above.
Output: A context document capturing:
Reference: See references/stage-1-context-gathering.md for detailed guidance and checklist.
Goal: Draft, organize, and refine content based on the context from Stage 1.
Input: Context document from Stage 1.
Output: A structured draft document with:
Reference: See references/stage-2-refinement-structure.md for detailed guidance on organizing content, handling multiple audiences, and drafting sections.
Goal: Validate the document with real readers before finalizing and publishing.
Input: Structured draft from Stage 2.
Output: Finalized document incorporating reader feedback:
Reference: See references/stage-3-reader-testing.md for guidance on planning reader sessions, capturing feedback, and prioritizing changes.
After completing all three stages, you will have:
The skill workflow is complete when:
Stage 1 context is documented and user confirms it captures their intent.
Stage 2 draft is structured, complete, and ready for reader feedback.
Stage 3 reader feedback has been collected from at least one real reader outside the original authoring team.
Feedback has been incorporated and the document is finalized.
The document is published or merged into the repository.
Related documentation is updated with cross-references to the new or updated document.
Smoke test:
agent-instructions)references/stage-1-context-gathering.md — context gathering checklist and detailed guidance for Stage 1references/stage-2-refinement-structure.md — guidance on organizing content and drafting sections in Stage 2references/stage-3-reader-testing.md — guidance on planning reader sessions and prioritizing changes in Stage 3assets/document-scaffold-template.md — reusable document scaffold templateassets/feedback-capture-template.md — reader testing feedback capture templateUse when auditing JS/TS code health with Fallow - dead code, duplication, boundaries, or cleanup; not for debugging failures.
Use when a JavaScript or TypeScript project needs Knip to find unused dependencies, exports, files, or unresolved imports; not for runtime failures or dormant-task recovery.
Use when creating or revising a reusable agent skill under skills/<name>/SKILL.md — deciding activation, layering, examples, or validation, or choosing between a skill vs. instructions vs. a specialized agent.
Run, debug, and extend tests for Go projects, including generation prerequisites. Use when domain logic, repositories, HTTP handlers, migrations, or unexpected test failures need coverage.
Draft structured documents, audit prose readability, and review short audience-facing metadata strings. Use when the primary work is writing, editing, or copy quality.
Use when creating or updating agent instruction files (AGENTS.md for Pi, copilot-instructions.md for Copilot, per-path guides, or AGENTS.md router) — especially when instruction files are too long, generic, or stale, or when agents repeatedly make the same avoidable mistakes.