Better Readme

---
name: better-readme
description: Audit and rewrite a project README against reader-funnel principles (noffle's "Art of README"). Use when the user asks to review, improve, rewrite, or translate a README, or asks whether their README is good — covers funnel ordering, moving maintainer content out, doc-shape tests pinned in CI, neutral multi-tool framing, idiomatic translations, and link/claim verification.
---

# Better README

A README is the consumer's first — and maybe only — look at the project. It is
also the project's contract: the documentation, not the code, defines what the
project does and what it promises to keep stable. No README means no
abstraction — readers must read the source to learn the interface, and the
interface/implementation boundary disappears. The job is not to sell; it is to
let each reader evaluate fit as fast as possible, including bailing out early. Structure every README as a **cognitive funnel**:
broadest, most decision-relevant facts first, deeper detail only for readers
who already decided to stay.

The reference framework is noffle's *Art of README*. An archived copy lives in
this skill at [references/art-of-readme.md](references/art-of-readme.md) — the
upstream repository link has gone offline, so consult the local copy when you
need the original checklist or the reasoning behind a rule. Do not reproduce it
in the READMEs you write — apply it.

## The funnel

Name → one-liner → (background if the domain is unfamiliar) → **usage, runnable**
→ install → API (or a link to it) → caveats → contributing → license.

- Each layer should let a reader short-circuit: "not for me" in 30 seconds is
  a success, not a failure.
- Install/API order depends on what the thing is. For libraries whose value
  *is* the API, readers vet the API before they bother installing: usage →
  API → install (the article's original order). For apps, CLIs, and
  out-of-the-box tools that expose no external API, install/setup comes right
  after usage, and the API section may not exist at all.
- Non-permissive license (AGPL/SSPL/…): badge or note at the **top**, full text
  at the bottom. License incompatibility is the fastest disqualifier; do not
  bury it.
- Images that carry critical information must live in the repo, not on an
  external host — the README outlives the host.

## Audit before rewriting

Read the current README top to bottom and score it against the funnel. Failure
modes seen in real audits:

- **Audience mixing.** Maintainer content (release runbooks, CI secrets tables,
  repo-structure trees, debug guides) interleaved with consumer content. This
  is the most common and most damaging pattern.
- **Funnel collapse.** Adapter/internals detail in the first 50 lines, before
  the reader knows whether the tool is for them.
- **Duplication.** The same fact (Node version, incremental rebuilds, runtime
  details) stated two or three times. Keep one statement, at the shallowest
  layer where a consumer needs it.
- **One-tool-centric framing.** A table or section written when the project
  supported one tool, still leading with that tool's specifics after it
  supports ten. Verify the truth against the code — the old text may be not
  just biased but *wrong* (missing entries, superseded semantics).
- **Staleness.** Dead relative links, version ranges that drifted ("ADRs
  0001–0006" when 0015 exists), references to deleted files.
- **Unlinked API docs.** Detailed reference exists in the repo but the README
  never links it.

## Pre-flight checks (do these before editing anything)

1. **`git status` first.** Never overwrite files in a dirty worktree — the
   README may carry the owner's uncommitted work. If the tree is dirty, work
   in a fresh worktree off `origin/main`; that also keeps the PR free of
   unrelated changes.
2. **Diff the branch against `origin/main`.** READMEs drift between branches.
   Base the rewrite on what main actually says today, not on the checkout.
3. **Grep tests and CI for `README`/`CONTRIBUTING` strings.** Projects pin doc
   content in tests: exact headings, file lists, required phrases. Know what
   is pinned *before* restructuring — otherwise CI fails after the rewrite.
4. **Check for derived documents.** Packaging READMEs, website copies, or
   generated docs that duplicate the README may need the same treatment or a
   deliberate out-of-scope note.

## Rewriting rules

- Consumer content only, in funnel order. Maintainer procedures **move** to
  `CONTRIBUTING.md` or `docs/` — moved, not deleted — with a pointer link left
  behind.
- One home per fact. If a detail now lives in a reference doc, link it; do not
  also summarize it at full length.
- Usage section = the actual interaction shape (real commands/prompts/code),
  copy-pasteable. Show CLI invocations with output when the project is a CLI.
- Compress deep detail into tables (consumers pattern-match tables faster
  than prose); push the prose version to the reference doc and link it.
- Every factual claim you carry forward, re-verify against the code. Never
  copy the old README's claims on faith.
- **When tests pin wording:** reshape the test to assert the *requirement*
  (ordering of two install paths, presence of a link) instead of the
  document's shape (exact heading strings, a file list). Most contributing
  guides require justifying changed assertions in the PR description — write
  that section. Do not silently weaken a test to make the docs pass.
- **Author preferences beat checklist purity.** Decorative elements the author
  likes (star-history charts, badges, wordmarks) stay unless the author
  explicitly agrees to cut them. Ask before deleting anything purely
  decorative; the checklist serves the author, not the reverse.

## Translated READMEs

- **意译, not 直译.** Rewrite in the target language's tech-writing rhythm;
  restructure sentences freely. Sentence-by-sentence mapping always produces
  translationese ("索引进", "服务两类读者", "综合缓存").
- Keep terms in English where the community actually uses English (provider,
  agent, session, tool call). Translate what has a real native term.
- Mirror structure exactly: same sections, same tables, same links, same
  heading count — parity must be mechanically checkable.
- Cross-link at the top of both files (`English · 中文`).
- Match the product's voice. If the product's own examples are colloquial,
  the README may be too ("用人话回答").
- Chinese section anchors change when headings do — update in-file anchor
  links to match the new headings.

## Verification before delivery

- Check every relative link and asset resolves (a quick script over
  `](…)`, `src=`, `srcset=` targets is enough).
- Run every test that reads the README or CONTRIBUTING — not just the suite
  you expect to matter.
- Re-read the final README as a stranger, top to bottom, and note where you
  would bail. If the bail points come in the wrong order, the funnel is wrong.
- Report the change as decisions: what moved where, what was dropped and why,
  which assertions changed. A README rewrite reviewed as prose diff is hard
  to approve; reviewed as a decision list it is easy.