Plain Technical Writing Skill — AI skill for Claude Code

Plain Technical Writing

**Version 1.0.2** | [Changelog](CHANGELOG.md)

Write reports, docs, specs, runbooks, and error text that an expert reader can find, understand, and use. Applies ISO 24495-1 plain-language principles with an explicit reader model, Diataxis genre separation, answer-first structure, and ASD-STE100 Simplified Technical English for procedures and agent-facing text.

What it fixes

Dense technical writing usually fails for one of three reasons, and each needs a different repair: the wrong genre (explanation smuggled into a reference), the wrong reader model (terms the reader doesn't hold, or over-gloss on terms they own), or the wrong mechanics (long sentences, dead verbs, one thing under three names). Most rewrites reach straight for mechanics — the least common cause. This skill diagnoses before rewriting.

Use cases

• Technical reports, README files, design docs, architecture write-ups
• PR descriptions, release notes, decision memos, status updates
• Runbooks, SOPs, error messages, tool descriptions, agent-to-agent instructions
• TRDs and other requirement specs — the answer-first + reader-model steps make requirements testable, not just shorter
• Rewriting existing text a reader called confusing, jargon-heavy, or dense

Not a fit: essays, marketing copy, or creative work where voice is the point.

How it works

1. Name the reader — one line: who, what they hold, what they want, what they'll do after reading
2. Declare the information type — Reference / How-to / Tutorial / Explanation / Decision memo / Troubleshooting — and write only that type
3. Put the answer first — conclusion or recommendation opens the document and every section in it
4. Choose the mode — Strict STE (references/ste-strict.md) for procedures and agent-facing text; Plain-SME (references/mechanics.md) for reports, design docs, and explanations
5. Audit before shipping — a 10-item checklist (sentence length, passive voice, nominalizations,