technical-writer
A Claude Code agent persona that writes developer documentation — README files, API references, tutorials — using the Divio system (tutorial / how-to / reference / explanation) and a rule that every code example must run.
Write developer docs that actually get read, not docs that get skimmed and abandoned
Trigger phrases
Phrases that activate this skill when typed to Claude Code:
write a READMEdraft API docswrite a tutorial
What it does
technical-writer is the docs persona in the agency-agents collection. It writes README files, API references, tutorials, and conceptual guides — and applies the Divio Documentation System as a hard rule: tutorials, how-to guides, reference, and explanation are four distinct doc types that should never be combined into one wall of text. The persona will refuse to write a “guide” that mixes installation, configuration, and usage in one section.
Five quality gates govern the output: code examples must run (no untested snippets), every doc stands alone or links to its prerequisites, voice is consistent (second person, present tense, active voice), every version of the docs matches a software version, and one concept gets one section. The README template the persona uses passes a “5-second test” — what is this, why care, how to start, all visible above the fold.
When to use it
- Writing or rewriting a project README that needs to convert visitors in 30 seconds
- Producing API reference docs from an OpenAPI spec or hand-written endpoint set
- Writing a step-by-step tutorial where the goal is “developer goes from zero to working in <15 minutes”
- Auditing existing docs for stale content, missing migration guides, or untested code samples
When not to reach for it:
- Marketing copy or blog posts — the persona is structural-doc-shaped, not narrative-shaped
- Pure inline code comments — the rules apply, but most comments are too small for the framework to add value
- Internal team wikis where information density matters more than reader empathy
Install
From msitarzewski/agency-agents at engineering/engineering-technical-writer.md. Copy to ~/.claude/agents/ or use the repo’s installer. Standalone.
What a session looks like
- Audience and entry point. Who is the reader? Beginner, experienced dev, architect? What do they already know? Where does this doc sit in the journey — discovery, first use, reference, troubleshooting?
- Pick the doc type. Tutorial (learning-oriented), how-to (task-oriented), reference (information-oriented), or explanation (understanding-oriented). The persona refuses to mix these.
- Outline first. Headings and flow before prose. Every section has one job.
- Draft in plain language. Optimize for clarity, not eloquence. Lead with outcomes (“After this guide, you’ll have a working webhook”), use second person, be specific about failure modes (“If you see
Error: ENOENT…”). - Test every code example. Spin up a clean environment, copy-paste the snippet, run it. If it fails, the doc is broken — fix the doc before shipping.
- Review cycle. Engineering review for technical accuracy, peer review for clarity, and ideally a developer unfamiliar with the project reading it while you watch.
The discipline that makes it work: step 5. Untested code samples are the most common docs failure mode, and the persona treats them as bugs, not minor issues.
Receipts
TODO — to be filled in from a real docs session. Once the persona has been used to write or rewrite at least one README or tutorial, this section will capture: how strict the Divio rule felt in practice (does it actually improve the doc, or does it make some pages awkward?), how many code samples failed the “must run” gate, and whether the 5-second-README test caught the things it claims to catch.
Source and attribution
From Michael Sitarzewski’s agency-agents repository.
License: MIT.
Quote from the persona body, verbatim: “Bad documentation is a product bug — you treat it as such.” The “code examples must run” rule and the Divio separation are how the persona makes that stance operational.