---
name: atomic-writing
description: >
Voice and tone rules for *enduring narrative documentation* — README.md, docs/guides/,
CHANGELOG narrative entries, and any other long-form human-facing markdown that ships
in the repo. Clear, direct, technical narrative. No marketing language, no AI-tell
phrases, no em dashes, no throat-clearing. Two voices: Claude's TUI replies use atomic
output style (terse, fragments); file contents split by surface — narrative docs use
this skill, everything else (specs, design docs, CLAUDE.md, signals files) uses terse
technical prose. Invoked by /documentation when editing README or guides. Invoked as callee
by `atomic-documentation` when surface is human-facing prose. Auto-fires on
"draft the README", "write the docs", "improve this prose", "edit the guide".
---
- "draft the README", "write the docs", "improve this prose", "edit the guide"
- "clean this up", "tighten this", "edit for tone" — when target is narrative prose
- `/documentation` updating README or a guide
- User asks to draft, edit, or improve `README.md`, `docs/guides/`, or other narrative human-facing markdown
Enduring narrative documentation has its own voice. This skill governs it. Claude's TUI replies use a different style (atomic output style, terse, fragments). All other files — specs, design docs, `CLAUDE.md`, signals files — use terse technical prose. This skill covers the middle ground: plain, specific, technical narrative. Paragraphs that move, sentences that name things, no rhetorical scaffolding.
Run these rules when writing or editing prose in `README.md`, guides under `docs/guides/`, CHANGELOG narrative entries, or any other long-form human-facing markdown that ships in the repo.
**Do NOT apply this skill to `docs/spec/` or `docs/design/`.** Those files use terse technical prose: table-first, diagrams allowed, prose kept terse and to the point. Specs and design docs are read often by both humans and agents, and brevity is the dominant cost there. Atomic-writing narrative would inflate them without adding value.
## What this skill is, and what it is not
| | Atomic (TUI style) | Atomic-writing (this skill) | Terse technical | Marketing slop (avoid) |
|---|---|---|---|---|
| **Where** | Claude's TUI replies to the user | README, docs/guides/, CHANGELOG narrative | `docs/spec/`, `docs/design/`, `CLAUDE.md`, signals files | Anywhere |
| **Form** | Fragments OK, drop articles, terse | Full sentences, paragraphs that flow | Tables, diagrams, terse bullets | Punchy taglines, hero copy |
| **Length** | Shortest viable | As long as needed; no shorter | Shortest that carries the contract | Whatever sounds dramatic |
| **Voice** | Imperative, telegraphic | Active, specific, technical | Imperative, declarative | Aspirational, promissory |
| **Em dashes** | Allowed in inline replies | Forbidden | Forbidden | Stuffed with them |
| **Adverbs** | Cut | Cut | Cut | Loaded |
| **Reader** | The user, mid-task, watching the terminal | A developer reading docs to understand or use the system | A human or agent who will implement, follow, or audit a contract | An imagined "audience" being sold to |
Two voices. The atomic output style (`output-styles/atomic.md`) covers Claude's TUI replies. This skill covers file contents when those files are enduring narrative docs. Everything else (specs, design docs, `CLAUDE.md`, signals files) uses terse technical prose. The two voices do not contradict; they apply to different surfaces.
## Core rules
1. **Active voice, named actor.** Every sentence has a subject doing something. Replace "the decision was made" with "the team decided" or, in docs, "we picked" or "use X". Never let inanimate things perform human verbs ("the complaint becomes a fix", "the architecture emerges").
2. **Be specific. Name the thing.** No vague declaratives ("the implications are significant", "the reasons are structural"). Name the implication. Name the reason. If you cannot, the sentence has no content.
3. **Start with the point.** Cut "Here's the thing:", "Here's what X", "It turns out", "The truth is", "Let me be clear", "I'll be honest". State the point directly.
4. **Show importance through content.** Delete "Full stop.", "Period.", "Let that sink in.", "Make no mistake.", "This matters because". Demonstrate why it matters, or let the reader judge.
5. **Use plain words over business clichés and stock AI phrasing.** The second group is harder to catch because every individual word earns its place; the phrase is what fails. Replace:
| Avoid | Use |
|---|---|
| ship / ships with (as filler verb) | includes, provides, comes with, has, delivers, bundles. Reserve "ship" for literal release/deploy contexts ("ship v2.0", "ship to production"). |
| navigate (challenges) | handle, address |
| unpack | explain, examine |
| lean into | accept, use |
| game-changer | significant |
| deep dive | analysis |
| landscape | situation, field |
| moving forward | next, from now |
| at its core | (delete) |
| in today's X | (delete) |
| load-bearing | name what breaks without it |
| it's worth noting | (delete, then state the note) |
| the real question is | state the question |
| that's the actual X | state X |
| read that honestly / to be honest | (delete) |
6. **Use commas, periods, or parentheses.** Em dashes are an AI tell, and the comma or period is almost always clearer.
7. **Cut filler adverbs.** Remove `really`, `just`, `literally`, `genuinely`, `honestly`, `simply`, `actually`, `truly`, `deeply`, `fundamentally`, `inherently`, `inevitably`, `interestingly`, `importantly`, `crucially`, `meaningfully`. Keep `-ly` words only when they carry technical meaning (`asynchronously`, `recursively`).
8. **State the answer directly.** Skip "Not because X. Because Y.", "X isn't the problem. Y is.", "The question isn't X. It's Y." State Y without the dramatic setup.
9. **Lead with what it is.** Skip "Not a foo. Not a bar. A baz." — define the thing, then contrast if needed.
10. **Make the point directly.** Drop "What if X?", "Think about it.", "Here's what I mean:", "Picture this." — state the conclusion.
11. **Quantify or name the specific case.** Replace `every`, `always`, `never`, `everyone`, `nobody`, `all` (when used as authority crutches) with the actual scope ("most production setups", "every command in this family").
12. **Let headings orient the reader.** Cut "The rest of this section explains…", "Let me walk you through…", "As we will see…" — section headings already signal what is ahead.
13. **Trust the reader.** A developer reading these docs already knows code. Skip the hand-holding, the disclaimers, the "this might sound complex but". State the technical fact.
14. **Keep technical density.** Unlike atomic TUI replies, doc prose can run long when the content requires it. Do not compress a five-sentence explanation into a fragment because compression is a virtue. Compression in docs is only a virtue when it removes filler, not when it removes content.
15. **Keep some narrative.** Paragraphs that connect ideas are good. A README built entirely from bullet lists reads like a spec, not like documentation. Mix lists (for enumerable things) with paragraphs (for reasoning and motivation).
## Quick checklist before saving a doc edit
- Em dash anywhere? Replace with comma or period.
- Adverb anywhere? Delete unless it carries technical meaning.
- Sentence starting with `What`, `Here's`, `So`, or `Look,`? Restructure.
- Passive voice? Find the actor.
- Vague declarative ("the implications matter")? Name the implication or cut.
- Three-item rhythm list (`speed, quality, cost`)? Drop to two, or break the rhythm.
- Marketing word (game-changer, lean into, deep dive)? Replace.
- Stock AI phrase (load-bearing, it's worth noting, the real question is)? Cut it and state the fact it was decorating.
- Inanimate noun doing a human verb? Name the human.
- Throat-clearing opener ("Here's the thing")? Cut.
- Binary-contrast structure ("not X. Y.")? State Y.
- Meta-joiner ("As we will see…")? Delete.
## Examples (before / after)
**Throat-clearing + binary contrast:**
> Before: *Here's the thing: configuring the bundle isn't hard. It's just tedious.*
> After: *Configuring the bundle is tedious, not hard.*
**Marketing language:**
> Before: *In today's fast-paced development landscape, atomic-claude lets teams lean into discipline without slowing down.*
> After: *Atomic-claude adds workflow discipline (TDD, signals, structured commits) without adding ceremony.*
**False agency + adverbs:**
> Before: *The signals workflow inherently keeps Claude genuinely informed about the codebase as it evolves.*
> After: *The signals workflow refreshes a snapshot of the codebase whenever the source tree changes, so each Claude session opens with a current map of the project.*
**Em dash + rhetorical setup:**
> Before: *What if you could ship a feature without ever leaving the terminal — and have it reviewed automatically?*
> After: *The `/subagent-implementation` command runs an implement-review loop without leaving the terminal. A reviewer agent gates each iteration.*
## Boundaries
- **Scope: narrative docs only.** TUI replies follow atomic output style. `docs/spec/`, `docs/design/`, `CLAUDE.md`, and signals files use terse technical prose, not this skill. Files in `.claude/`, `agents/`, `commands/`, `skills/`, `output-styles/` follow their own conventions. Pure structure (tables, frontmatter, code blocks) passes through unchanged.
- **Tables and code blocks pass through unchanged.** This skill governs prose. Frontmatter, fenced code, command examples, file paths, identifier names, error strings: never reformat or rephrase.
- **Spec checkpoint tables and design alternative tables pass through unchanged.** Their structure is the contract. Only the surrounding prose (Goal, Problem, Rationale) is in scope.
- **CHANGELOG entries follow the project's existing tone.** This skill nudges new entries toward plainness but does not rewrite older entries on sight.
- **Comments in source code follow the global comment rules in `CLAUDE.md`, not this skill.** This skill is for documentation files, not inline code comments.