/readme-improver — make a README earn its first 30 seconds

A README's only job is to let a stranger decide — fast — whether the project fits, and then get them to their first success. This skill audits an existing README (or scaffolds a new one) against a rubric distilled from the canonical guides and exemplar READMEs (cited below), and emits prioritized, actionable findings. It improves the README in place only when asked, and never flattens the author's voice.

Sources distilled: hackergrrl/art-of-readme (cognitive funneling), banesullivan/README (the four reader questions + template), gruns/furl (problem → example → API narrative), marcomusy/vedo (large-surface library: link-out + cite + collapse).

The north star: a scanner's four questions

A first-time reader is triaging dozens of projects. In ~30 seconds they must answer:

1. Does this solve my problem? → the what + why, in the first 2–3 lines.
2. Can I use it? → install + a runnable example + license + platform/version support.
3. Who made it / can I trust it? → maintenance signals, provenance, social proof.
4. How do I learn more? → links out to docs, examples, issues.

If any of the four is unanswerable from the top half of the README, that is a finding.

Core principles (the lens)

• Cognitive funneling: order sections broad → specific. Name → one-liner → why → usage → install → deeper reference → meta. A reader bails the moment it doesn't fit; don't bury the hook under badges or a table of contents.
• The docs define the project, not the code. A user should never have to read source to evaluate or use it. But the README is not the docs — it is the elevator pitch with a runnable first step.
• Care about the reader's time. Every line either helps them decide or get started. Cut or relocate the rest.
• Show, don't tell. A real, runnable example with its actual output beats paragraphs describing the behaviour. In the strongest READMEs, examples-with-output are roughly a third to a half of the whole document.
• The README reflects the software. A stale, sprawling, or broken README signals a stale, sprawling, or broken project — so verify before you trust it, and fix the README and note the drift.
• Present tense, not autobiography. A README states what the project is and does today — not the path it took. Cut "previously we thought X / now superseded / turns out Y was a bug" narration: that's accurate history in the wrong document (a reader wants the current truth, not your changelog). Distinct from staleness — the content isn't wrong, it's misplaced; if the history matters, it belongs in CHANGELOG.md or a docs/ note.

Usage

• /readme-improver — audit the repo-root README (README*). Findings only.
• /readme-improver <path> — audit a specific README / directory.
• /readme-improver --fix — audit, show the plan, then apply the safe, high-value edits. Preserves voice; never invents facts.
• /readme-improver --new — scaffold a README from the skeleton below, filled from the actual repo (manifest, license, entry points, Justfile/CI).
• /readme-improver --drift — cross-document drift check: fan out one read-only sub-agent per doc (README*, sub-READMEs, CLAUDE.md/AGENTS.md, docs/, re/) and reconcile their claims against the code. Auto-runs inside a normal audit when ≥3 overlapping docs are present.

Default is audit-only. Editing a user-facing doc is opt-in.

The discipline (find without lying)

Every finding cites where, why it matters, and ONE concrete fix. No "consider improving." If you can't propose a concrete fix, it's noise — drop it.

Verify, don't assume — three checks that kill false findings:

1. Run the commands. Before claiming "the install/build is wrong," actually try it (scratch dir) or at least confirm the tool/recipe exists (just --list, cat Cargo.toml). A README saying npm install for a Rust crate is a real finding; one you assumed was wrong is a false positive.
2. Grep the code for drift. A documented flag/function/path/env-var: grep for it before asserting it's stale, and after asserting it's missing.
3. Resolve the links. Dead links and 404 images/badges are findings — check them (curl -sI), don't eyeball.

Never rewrite the author's voice into corporate boilerplate, add emoji they didn't use, or fabricate benchmarks/badges/citations/"used by".

The rubric (categories, in priority order)

1. Useful — does it answer What / Why / How? (highest priority)

The substance test:

• What — a one-liner in the first 1–2 lines naming the domain concretely. "parses and modifies URLs" beats "a URL utility"; the concrete verb-plus-object form beats the category noun. Vague naming is a finding.
• Why — the pain it removes, or why it exists over the obvious alternative (the language's own stdlib module, the incumbent tool). The strongest form names that alternative and the specific way it falls short. Missing why is the most common real defect.
• How to use — a minimal runnable example near the top, not buried under the API.
• How to install — the one-liner for the average user (package manager); dev/build kept separate.
• How to build / test — for a contributor: the real commands (or a pointer to just/make/CI). Drift here is common.
• How to configure — required env/config/secrets to run it for real, and where they live.
• How to contribute — even one line + a link; signals the project is alive.

Missing What or Why ⇒ HIGH. Missing how-to-use / how-to-install / license ⇒ MEDIUM.

2. Information overload — delegate, don't dump

The README is the pitch, not the manual. When a section outgrows it:

• Exhaustive API / long option tables / deep reference → move to docs/ (or a docs site / wiki) and link out; keep a one-screen "Quick start." Two workable treatments: link out entirely, or keep it inline but chunked under headings a reader can skip. Chunk if it must stay; link out if it's pure reference.
• Design rationale, history, deep dives → docs/notes/ or an ADR, linked.
• Stale / superseded / "coming soon (2 years ago)" content → this is not "move to docs," it's move to cruft/ (or delete). Stale content in a README is worse than none — it's a lie. Respect the project's convention (many repos use a cruft/ folder for exactly this).
• Journey / changelog narration — accurate history ("previously we thought X / now superseded", migration stories, "we first tried Y"). Unlike the stale bullet above (which is wrong), this is true but misplaced: the README is the current-state pitch, not a changelog. Cut it, or move real history to CHANGELOG.md / docs/. Symptom words: "previously / earlier / superseded / used to / turns out / no longer".
• Collapsible blocks (<details><summary>…</summary>) for big feature lists the reader rarely needs first.
• Symptom: more than ~2 screens of prose before the first runnable example, or a TOC needed to navigate — that's overload. Funnel and link out.

3. Staleness / doc-vs-code drift (the trust-killers)

Flag and verify each:

• Commands that don't run / wrong package manager / wrong binary name.
• Documented flags/functions/paths/env-vars absent from the code (grep to confirm).
• Version/compat claims contradicting the manifest (Cargo.toml / package.json / pyproject.toml).
• Dead links, 404 images/badges, broken anchors.
• "Coming soon" / "TODO" / "WIP" / roadmap items long since done or abandoned.
• Badges pointing at a renamed repo, dead CI, or the wrong branch.
• Screenshots/GIFs of an old UI.

4. First impression & scannability

• One-liner present and specific (the funnel's mouth).
• Badges: a few meaningful ones, not a wall — a badge wall is noise that pushes the hook below the fold. Keep CI · version · license; cut vanity counters with no decision value.
• Don't rely on images for critical info — inline the essential text; images may not load.
• Title → tagline → the what/why, not a giant logo pushing the hook below the fold.
• Link unfamiliar terms/acronyms on first use.
• Internal tracker IDs are reader-noise — bare TASK-1234 / JIRA-… / #123 an outside reader can't resolve signal an internal doc. Strip them; if one is genuinely load-bearing, turn it into a real link rather than deleting it.

5. Trust & "how to learn more"

• Maintenance signals: license, last-release/CI badge, supported versions.
• Provenance / who: author/org; for research code a "How to cite" + DOI if applicable.
• Social proof only if honest: "used by", publications, downloads.
• Interop: name the neighbouring tools and formats it works with — answers "fits my stack?".
• A clear next step: docs link, examples/ dir, discussions/issues.

6. License (always check)

• A LICENSE file exists at the repo root (not just a word in prose) and the license is stated in the README.
• It matches any license = field in the manifest (mismatch is a finding).
• Public repo with no license ⇒ all-rights-reserved by default (no one may legally use it) ⇒ HIGH.

Cross-document drift (multi-doc mode — fans out to sub-agents)

A project is rarely one document. README.md, sub-READMEs (*/README.md), CLAUDE.md / AGENTS.md, docs/**, RE/spec notes (re/**), CONTRIBUTING, TESTING.md, and a PRD all make overlapping claims — and they drift apart: the same load-bearing fact ends up stated three different (sometimes flatly contradictory) ways. A single-README audit cannot see this; you must read the whole doc set and cross-check. Because that is a fan-out, delegate it to sub-agents (one per document) and reconcile their structured output in the main loop. Runs automatically when ≥3 overlapping docs exist, or on demand via --drift.

The canonical axes (the facts that rot unevenly)

Cross-check the docs against each other on:

• Status — what works vs what's pending / blocked / "coming soon".
• Methodology / constraints — e.g. "static-only", "offline-first", "no network".
• Canonical commands — the build / test / run / install verbs (make vs just vs cargo vs npm).
• Version / compatibility / supported platforms.
• Scope / authorized-use / security posture.
• The headline feature and how to invoke it.
• License.

Procedure

1. Discover the doc set (cap + report if huge):

   { ls README* CLAUDE.md AGENTS.md CONTRIBUTING* TESTING* PRD* 2>/dev/null;
     git ls-files '*/README.md' 'docs/**/*.md' 're/**/*.md' 2>/dev/null; } | sort -u

   Fewer than ~3 overlapping docs ⇒ skip the fan-out and read them inline; spawning agents for two files is wasted latency.
2. Fan out — one read-only sub-agent per document (via the Task tool; agentType Explore or general-purpose). Give every agent the same canonical-axes list and this contract:
   • Extract, do not judge. For each axis its doc speaks to, return axis | verbatim quote | file:line. It does not edit, rank, or compare to other docs — it cannot see them.
   • Quote, never paraphrase a status (paraphrase is how drift sneaks back in), and never echo a secret — if a doc embeds one, return its location only.
   • Structured return (one line per axis) so the main loop can diff mechanically.
   • Scale: one agent per doc up to ~12; beyond that, cluster (e.g. all of re/** into one agent) or sample — and log what you dropped, never silently truncate. Send all the agent calls in one batch so they run concurrently.
3. Reconcile in the main loop (you, not the agents). Build an axis × document matrix from the returned stances. For each axis where two docs disagree — especially contradict (static-only vs live-runs; login-pending vs login-works; make build vs just build) — that's a drift finding. Verify against the code (grep the symbol, run the command) to decide which doc is right, so the finding names the stale one — never "they differ, pick one".
4. Name a source of truth per axis (usually the code itself, else the most-maintained doc) and align the others to it — do not average contradictory claims into mush.

Output (drift matrix + findings)

Cross-document drift:  6 docs · 7 axes · 2 conflicts

axis            README.md        <sub>/README.md         CLAUDE.md
--------------  ---------------  ----------------------  --------------------
methodology     static + live    (silent)                "static only"  ✗ STALE
status/login    works            works                   "pending"      ✗ STALE
build verb      just             just                    just            ✓

[DRIFT-HIGH] methodology — CLAUDE.md:<line> says "Static analysis only. No live capture,"
but README.md:<line> and the working live path disagree (verified: the documented live
recipe runs). SOURCE OF TRUTH: the code (a live code path exists behind a feature
flag and runs). FIX: update CLAUDE.md:<line> to describe both the static and live paths.

Each conflict lists the axis, every doc's claim + location, the verified source of truth, and ONE fix per stale doc.

In --fix mode, align the stale docs to the source of truth — but treat CLAUDE.md / AGENTS.md / PRD as higher-stakes than a README: they steer agents and humans, so show the diff and confirm before editing them, and keep each one in its own commit.

Recommended skeleton (consolidated structure)

Order matters (funnel). Omit sections the project doesn't need; never pad.

# Project Name
> One concrete line: what it is + the problem it solves.

[a few meaningful badges: CI · version · license]

Short paragraph — the *why*: the pain it removes vs the obvious alternative.

## Quick start
```sh
<install one-liner>
```
```<lang>
<smallest runnable example, with the real output shown>
```

## Usage / Examples
The 2–3 highest-value examples (real input → real output). Link to `examples/`
or the docs for the rest.

## Install
Average-user install. Dev/build prerequisites + steps (or `just build` / a link to CONTRIBUTING).

## Configuration
Required env/config/secrets to run it for real, and where they live.

## Documentation
Link out to the full docs / API reference — keep the exhaustive material out of here.

## Contributing
One line + link to CONTRIBUTING; how to build & test (e.g. `just test`).

## License
SPDX id + link to LICENSE.  (For research code: "How to cite" + DOI here.)

Output format (audit mode)

Lead with the verdict, then findings grouped by severity — each one actionable:

README audit: <path>   VERDICT: needs-work | solid | exemplary
Top-half answers the 4 questions:  what ✓  why ✗  trust ✓  learn-more ✓

[HIGH] Why-it-exists missing — jumps from the title straight to the API with no
problem statement; a reader can't tell what pain this removes.
FIX: add 1–2 sentences after the one-liner contrasting with <the obvious alternative>.

[MED] Information overload — §"All options" is a 120-line flag table (L<start>–<end>),
pushing Contributing/License off the bottom.
FIX: move the table to docs/options.md; leave a 6-line "common options" + a link.

[MED] Stale — `make build` (L<n>) but there is no Makefile; repo uses just.
FIX: replace with `just build` (verified: `just --list` shows it).

[LOW] Badge wall — 9 badges (L<n>); 5 are vanity counters.
FIX: keep CI · version · license; drop the rest.

In --fix mode: show this plan, apply edits with Edit/Write, move (don't delete) overload to docs/ and stale content to cruft/ via git mv, re-verify commands, then re-run the audit to confirm.

Anti-patterns (don't introduce these while "improving")

• Replacing a crisp, opinionated voice with bland corporate copy.
• Adding a giant logo / badge wall that buries the hook below the fold.
• Inventing benchmarks, "used by", citations, or a roadmap.
• Turning the README back into the manual (re-inlining what belongs in docs/).
• Deleting content outright when a cheap, honest move-to-cruft/ records it instead.