technical-writer

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• write a README
• draft API docs
• write 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

1. 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?
2. Pick the doc type. Tutorial (learning-oriented), how-to (task-oriented), reference (information-oriented), or explanation (understanding-oriented). The persona refuses to mix these.
3. Outline first. Headings and flow before prose. Every section has one job.
4. 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…”).
5. 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.
6. 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

2026-05-05 — Critique of receipts-drafts/_TEMPLATE.md

Pointed the persona at the receipts template that drives every wiki receipt, with three actually-filled examples (seo-technical, seo-geo, copy-editing) for cross-comparison. Brief asked for the writer’s-experience lens, not the reader’s — where would an author stall?

Persona produced 5 specific edits and 1 cut. The most useful finding: the “Output gist” field is doing two jobs. The template prompts a 1–2 line summary, but every filled example uses it as a structured findings dump (3–8× longer than the prompt implies). Authors are improvising structure inside one field every time. Splitting it into Findings: (expand-allowed) + Output gist: (1–2 sentences) removes the contradiction. Three other slot additions came from cross-examination against actual practice: a Wiki beat: field (every entry already produces this informally), a Prior runs: reference field at the top of multi-run entries, and a Surfaces probed: / Counts/timings: split inside Numbers:. The cut: drop Trigger: — boilerplate in all 3 filled examples.

Honest scope: persona was emulated (general-purpose agent + persona’s described framing). The Divio-system rule didn’t apply — this isn’t a Divio doc type — but the “every code example must run” discipline carried over as “every template field must match real practice.” None of the 5 edits would invalidate the existing 3 filled examples; they’d just become slightly under-structured by the new template.

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.