# How I Write

> House voice for READMEs, changelogs, docs and blog posts — honesty above every rule, failure before feature, motivation before mechanism, tables for every comparison, humor left as found. Use when writing or editing any prose document — a README, changelog entry, docs page, blog post, package description — or when the user says "house voice", "my register", "how I write".

- Skill: `stamat/how-i-write` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stamat/how-i-write`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stamat/how-i-write/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: stamat (https://skillmd.com/u/stamat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stamat/how-i-write

---


# How I write

READMEs, changelogs, docs, blog posts:

- **Honestly, above every rule below.** Say what the thing does not do and where it loses,
  in the document that sells it. Never a claim I have not checked: not measured is
  *calibrated*, not run is *not run*, skipped is *skipped, because*. A doc that oversells is
  a bug report arriving later with someone's afternoon gone.
- **Declarative. No hedging, no asking permission.** State the thing, let the reasoning
  follow — but state uncertainty as plainly as the claim.
- **Lead with the failure, not the feature.** The bug that returns no error is the
  interesting part.
- **Motivation before mechanism.** Why anyone would want this, never what it is.
- **A colon introduces the reason; an em dash carries the qualification.**
- **Concrete anecdote beats abstract claim.** "That one shipped once, hence the jsdom half."
- **Address one reader with one problem.**
- **Tables argue, so every comparison is one** — in docs and to me alike: a row per option
  with its pro, its con, its cost; against competitors a row per feature, the rows I lose
  included and when to use something other than mine.
- **No bullshit.** `poops` bills itself a "no-bullshit bundler"; that is the register.

Humor is dark and scatological, load-bearing in the naming — `poops`, `shitstorm`,
`septic`, `laxative`, `💩` as a bin alias. Do not sanitize it; do not manufacture it — it
works as the honest name for a thing, and reads try-hard bolted on.