writing-for-humans git:20260808.9c56a31A

Immutable. This exact content never changes and is served at /api/v1/blob/271e3db07dd2b156.

---
name: writing-for-humans
description: Write copy a human reads — a landing page, a README's front half, a launch post, a profile page. Use when drafting or revising public-facing prose, when a page reads like agent documentation, or when a finished draft needs its last-mile scrub for AI tells.
---

# Writing for Humans

A human reads for a different reason than an agent. The sibling skill [writing-for-agents](../writing-for-agents/SKILL.md) makes documents predictable enough that an agent runs the same process every time. This skill makes pages worth a stranger's next minute: the reader is free to leave at any sentence, and the page earns each one. The registers are opposites, and the compression that serves an agent reads cold to a human. When the document you are writing is a SKILL.md, an AGENTS.md, or a reference an agent consumes, use the sibling instead.

Work the sections in order for a full draft; jump straight to [the scrub](references/last-mile-scrub.md) when the content already stands and only the tells remain.

## Guide structure over catalog structure

A catalog lists what exists. A guide walks the reader somewhere. Human-facing pages take the guide shape (modeled on the [mattpocock/skills](https://github.com/mattpocock/skills) README), in this order:

1. **Identity and hook first.** Before any list, one or two sentences say what this is, for whom, and the opinion that animates it.
2. **The quickest possible start.** The smallest real action the reader can take right now, stated as steps they can finish in minutes.
3. **Problems framed from the reader's seat.** Each one runs problem → fix → link: name the pain as the reader feels it, then the fix, then where to go. The reader's frustration comes before your feature every time.
4. **Explicit ordering.** Say outright what to do first, second, and when each later piece becomes relevant. "Start here. Do this first." The reader never infers the sequence.
5. **Full reference last.** The complete listing exists — at the bottom, where the convinced reader looks it up, not at the top where it greets the undecided one.

The structural test at every scroll depth: can the reader say what to do next? A section that leaves them informed but directionless goes lower or gets a pointer forward.

## Warmth moves

Warmth is specific moves, each observable in the text:

- **First person with real opinions.** "I built this because X annoyed me" over "This tool addresses X." An opinion is a claim the writer could lose an argument about.
- **Admit limits plainly.** Confessing what a thing won't do is the warmest move available: "it is a survey, not a rescue; it won't untangle the mud for you" builds more trust than any capability claim. Every piece carries at least one honest limit.
- **Permission-giving imperatives.** "Hack around with them. Make them your own." The reader is invited to act, not licensed to observe.
- **Empathy before feature talk.** Open from the reader's chair: the situation they're in, the thing that isn't working. Only then introduce what you built. A feature named before its pain is a spec line, not a sentence.

## Failure modes

Check a draft against each by name:

- **Agent-register bleed** — human copy written in the compressed declarative style of agent docs: single-verb headers, definition-dense paragraphs, insider vocabulary presented as self-evident. The tell is a term of art standing where a reader's word should be. Translate the term or teach it in the sentence where it first appears.
- **Process bleed** — the piece narrates the hidden work behind it instead of speaking to the reader about what they get and what to do next. (The term is [forint573's](https://github.com/forint573/human-copywrite): chat history shipping as copy.) The fix is to write from the facts, ordered by the reader's questions. The build timeline never sets the order.
- **Clean nothing** — tidy, de-AI'd, and empty: every tell scrubbed, no voice left. A scrub is not a voice. The test: does the piece contain an opinion, an admitted limit, or a choice a competitor's page wouldn't make? Zero of the three means you polished a vacancy.

## Standing voice rules

These carry over from the agent-facing register, plus one rule the human register adds. Warmth never buys them back:

- **Checkable claims only.** Every claim hands the reader a way to verify it, whether a link, a sourced number, or a behavior they can try for themselves. A claim that offers none of those is absent.
- **No stale numbers.** A count or date that will rot ("twelve integrations", "as of March") either lives where the release process updates it, or is written so it cannot rot ("the catalog table below is the current list").
- **Facts sacred.** Never invent a user, an anecdote, or a metric to sound human. A fabricated warm detail is worse than a cold true one. Where a fact is missing, leave a visible placeholder and go get the fact.
- **Anonymize criticism; names only in praise.** A person or company is named in your copy only when the mention flatters them.
- **Dashes on a budget.** The em dash is one of the most recognized AI tells, and the clause-spliced rhythm it builds is the reason. In human-facing copy dashes are the exception: roughly a handful per page, each one earning its place as a genuine interruption or turn. When a draft runs over, the fix is restructuring: split the sentence, subordinate the aside with a comma, or cut the aside entirely. Never swap a dash for another mark in place, whether a comma, a semicolon, a colon, or a pair of parentheses; the mechanical swap keeps the AI rhythm and only changes its costume.
- **Positioning is a standing first-person fact, reused verbatim.** The canonical lines are the identity hook "I don't write code. I direct agents." and the wedge "I don't write code. I've shipped four products in five months." (verify the shipped count and the elapsed time are current before using, since the no-stale-numbers rule above holds for both halves of the line). The third-person descriptor (a non-coder CEO shipping software via agents, lending as background credibility kept in the background) is rationale prose, not the line copy reaches for. The positioning stands on two legs, and copy carries both. It is interesting because the writer is not a coder, and believable because the work is shown ("And I check what the frontier actually claims"). Leg one without leg two reads as a stunt. The skills catalog itself is always positioned as the method that let a non-coder ship four products, never as generic portable skills for agents. The canon lives in the marketing plan's positioning and voice sections (personal-marketing PLAN.md §1, §7); when this skill and that doc disagree, the doc wins and this rule gets amended.

## Last-mile scrub

After structure and voice are settled (never before, or you produce clean nothing), run the AI-tell pass in [references/last-mile-scrub.md](references/last-mile-scrub.md). Start with the guardrails, which hunt clusters rather than isolated tells and let a voice sample outrank every rule. Then work the tell clusters, rewriting whole sentences rather than swapping words.

## Done when (checkable: verify each line before reporting complete)

- A reader who has never seen the project can say what to install (or read, or click) first and what their first session looks like. Test by reading only the page.
- Hook first, quickest start second, reference last; every section leaves a visible next action.
- No insider term appears before the sentence that explains it: the page teaches its vocabulary or drops it.
- Every claim is checkable or absent, every number has a live source or cannot rot, and nothing was invented to sound human.
- The piece carries at least one first-person opinion and at least one plainly admitted limit.
- The page spends its dash budget deliberately: a handful at most, each one an earned interruption, and no over-budget dash was fixed by an in-place swap.
- The piece describes what the reader gets and does next. How it got made appears nowhere.
- The last-mile scrub ran last, whole clusters were rewritten, and the voice sample (when one exists) won every conflict with the rules.

## Attribution

The guide structure is modeled on the README of Matt Pocock's [skills](https://github.com/mattpocock/skills) (MIT): hook, thirty-second start, problem → fix framing, and reference last are the shape his README demonstrates, and the quoted phrases in Warmth moves ("it won't untangle the mud for you", "Hack around with them. Make them your own.") are his. *Process bleed* is [forint573/human-copywrite](https://github.com/forint573/human-copywrite)'s term (Apache-2.0). The scrub's guardrails (clusters over isolated tells, voice sample outranks the rules, no fabrication) follow [blader/humanizer](https://github.com/blader/humanizer) (MIT), whose 33-pattern catalog builds on Wikipedia's "Signs of AI writing"; the dash budget is this catalog's softer cousin of that skill's outright em-and-en-dash ban. What this catalog adds: the register split against its sibling writing-for-agents, the *agent-register bleed* and *clean nothing* failure modes, the standing voice rules, and the checkable done-when list.