readme-optimization

README Optimization

You are working on the single page that decides whether a developer tries a project or closes the tab. Diagnose the existing README against evidence, then rewrite it so a stranger can evaluate the project quickly and accurately - including deciding not to use it, which is a correct outcome you should never optimize away.

A README is not a documentation type. It is a landing page and a router: it answers what and why in seconds, then sends the reader onward. Judge it on whether it converts a visitor into a trial, not on documentation completeness.

Put the rewrite budget where the scarcity is. Across 393 sampled GitHub repositories (Prana et al. 2019, cited in ./references/published-findings.md; the sample is late-2010s, read it as a baseline, not a census):

• What the project is: 97.0% - table stakes.
• How to use it: 88.5% - table stakes.
• Why to pick it over the alternatives: 25.7% - scarce.
• What state the project is in: 21.4% - scarce.

Those two scarce categories are exactly what an evaluating developer must answer before adopting anything.

Stay inside this page and its repository furniture - the description, website link, topics, and social preview that surround the file. When the user's real problem is a docs site, a getting-started page, the contribution path, release notes, a launch, or a profile README, route them to the sibling skill under Reference instead of stretching the README to cover it.

Folklore statistics to refuse

Never repeat these folklore statistics in your own reasoning or to the user - all three circulate widely on invented attributions:

• "repos with detailed READMEs get 50% more contributions"
• "a star-history chart lifts star conversion ~15%"
• "62% of top repos have GIF demos"

When a user cites one, say it is unsourced rather than building on it. Every figure this skill does quote is cited in ./references/published-findings.md; read it before repeating a statistic to a user.

Promise a better-evaluated project, never a percentage lift.

Invocation examples and output shape

Typical requests:

• "audit the README of this repo"
• "our GitHub gets traffic but no installs"
• "rewrite the top of our README before launch"
• "make our README readable by someone evaluating us for their company"

Every run produces a scorecard first, in this shape, before any prose is written:

README audit - acme/flowmatic   (audience: solo developer)
Band A: A1 pass · A2 FAIL (install needs Node >=20, undocumented) · A3 FAIL · A4 pass · A5 pass
Verdict: does not pass - A2 and A3 blocking; B1 returns the most per hour spent

The rewrite follows only after the user agrees with that diagnosis. The full report format, including the claim check, Band B, and the fix order, is in ./references/audit-scorecard.md.

Interview

Ask one question at a time, multiple-choice where you can, and skip anything you can determine yourself by reading the repository. Questions 1-4 gate the rewrite - do not draft prose before they are answered.

Memory: Store a few info about the current task or project context. When memory lives in a file, use devrel-context.md; if a different memory system is in use, rely on that instead. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

1. Which repository, and can I read it and run commands in it?
2. What is the project: library or SDK, CLI tool, application or service, framework or platform, or template and learning resource?
3. Who lands on this page: developers in one language ecosystem, polyglot developers, platform or ops engineers, or non-developer evaluators such as security and procurement?
4. How does adoption happen - an individual developer installs it and decides alone, or a company adopts it and someone else approves the licence, the security posture, and the support story? Both is a valid answer, and it changes the middle of the page.
5. What outcome do you want more of: installs, contributors, stars, hiring signal, enterprise conversations, or fewer repetitive support questions?
6. What is the honest project status: experimental, actively maintained, stable and feature-frozen, or seeking maintainers?
7. Which alternatives do readers arrive already knowing? What do those do better than you?
8. What must appear for legal or policy reasons - licence terms, trademark notice, export or compliance statements, employer disclosure?
9. Is there existing brand material - a logo, a tagline, a positioning sentence used on a website - that the README should match?
10. Is the README also published elsewhere: a package registry page, a mirror, a docs-site landing page? Each render target has different rules.
11. Is there a date this has to be done by - a launch, a conference, a funding conversation - or is the page just overdue?
12. Do you want a one-off win before that date, or an asset that keeps paying: a positioning sentence and a page shape you reuse for the next two years?
13. What is your ceiling - an afternoon, a week of someone's time, permission to ask customers for a logo, appetite for a governance or foundation commitment you cannot easily undo?

Answers 11-13 re-rank every ordering below; say which answer moved which fix when presenting the plan.

• Hard date (Q11) - promotes the fixes that land in an hour, drops the funnel restructure from this pass.
• Compounding mandate (Q12) - promotes the differentiation paragraph and the restructure, whose one-liner propagates into the registry page, the launch post, and every link unfurl.
• Low ceiling (Q13) - deletes the terminal demo and the enterprise signals outright, rather than parking them at the bottom of a list.

If the user cannot answer 7, treat that as a finding rather than a blocker. A maintainer who cannot name their alternatives usually has a README that cannot differentiate either, and that is the most valuable thing you will fix.

Step 1 - Declare the audience, then check the README is the bottleneck

Answer 4 decides the whole audit. The enterprise evaluator and the solo developer want structurally different content, and optimizing for one degrades the other: a hobbyist bounces off a wall of compliance badges, and a procurement reader distrusts a page with no security or governance signal. Write the declared audience at the top of your scorecard so every later judgement is checkable against it.

Then confirm the README is what is broken. If the code host exposes traffic data, take unique visitors and clones for the last two weeks.

• Decent traffic with a clone-to-visitor ratio of only a few percent: this is the case this skill is for - people arrive and leave unconvinced.
• Few visitors in the first place: a distribution problem, not a prose problem - route the user to launch or distribution work instead of rewriting a page almost nobody reads.

That "few percent" boundary is a working heuristic, not a benchmark; on a borderline number, look at referrers rather than ruling.

Step 2 - Gather evidence

Never audit from memory of what good READMEs look like.

1. Read the README in full and note where you personally got confused. Your first-read confusion is the closest thing you have to a cold reader.
2. Run the mechanical audit: scripts/readme-audit.sh <repo-root>. It reports:
   • shadowed copies
   • truncation risk
   • the heading tree
   • section count against the median of 7
   • words before the first copyable command
   • badge count
   • missing alt text
   • registry-hostile raw HTML
   • broken relative links
   • placeholder text
   • missing content categories
3. Read the repository around the README: manifests for the real runtime requirements, the licence file, recent commit dates, open-issue volume, and whether the examples it references exist on disk.
4. If your environment can browse the web, open the project's package-registry page and compare it to the code-host render. Relative links and raw HTML frequently break there, and that page is often the higher-traffic one.
5. If your environment has persistent memory, reuse any stored positioning statement, audience definition, or competitor list for this project instead of re-deriving it.

Optionally add a structural README scorer and the code host's community-standards checklist as a second opinion, treating both as hygiene baselines - see the validity ceiling in ./references/tooling-and-measurement.md. The script reports facts, not judgements: a section count of 25 is a question to answer, not a verdict.

Step 3 - Score the current README

Work through ./references/audit-scorecard.md and produce the scorecard in the shape above.

• Band A: five blocking checks - identity, the install actually running, every claim verifiable, honest status, reachable licence.
• Band B: eight scored checks, worth two points each.

Attach evidence to every check - a line number, a quoted sentence, or the terminal output of a command you ran. Get the user's agreement on the score before rewriting anything: a maintainer who rejects the diagnosis rejects the treatment, and they are sometimes right, since a constraint invisible from the repository can justify a check you scored zero.

Order the fixes

Order the fix list by what each fix returns per hour spent, not by how easy it is to write and not by how much damage it undoes - those three orderings disagree, so state all of them and lead with the third:

• effort, least first: status line == badge row > claim check > install path > differentiation paragraph > funnel restructure
• value, most first: install path > differentiation paragraph > claim check > status line > funnel restructure > badge row
• efficiency, do first: status line > install path > claim check > differentiation paragraph > badge row > funnel restructure

The status line and the badge row tie on effort: each is one edit to one block, written from what the maintainer already knows, verified against nothing - no command run, no source read. They separate on value, since a status line answers a question only 21.4% of READMEs answer and a badge row answers one 61% of contributors ignore.

Default to the top three for a first pass; move down once the blocking checks are green, or when the cold-reader test fails on a question none of the three touches.

The funnel restructure loses every round - a week against fixes that land in an hour - so this order under-invests in the one change that makes the page work. Promote it when the cold reader answers wrong because they never scrolled far enough, or when a launch is the reason for the audit, and say you are promoting it against the ratio.

The ordering is a default, not a law, and it shifts with who executes it. Re-rank it against what you already know:

• A maintainer who can name their alternatives in one sentence gets the differentiation paragraph nearly free, which promotes it above the install path.
• A project with no install command - a spec, a dataset, a template - deletes that row rather than scoring it zero forever.

Delete every fix answer 13's ceiling rules out instead of listing it last.

Step 4 - Verify every claim against the source

A README is a set of claims about a codebase, and every claim is checkable. Agents and maintainers alike write from memory of how an API usually looks; a reader cannot tell a verified line from an invented one, and you can, because you have the repository.

List every claim:

• command
• flag
• default value
• environment variable
• config key
• endpoint
• exported symbol
• file path
• version requirement
• behavioural assertion hidden in a verb, e.g. "automatically reconnects", "retries three times", "case-insensitive"

Verify each against its own source of truth - the argument parser, the definition site, the route table, the changelog - by reading it, not recalling it. A flag documented in the README but absent from the parser is a hallucination, not a typo.

Then run the install path itself, because it catches the most real damage:

1. Start from a clean state - a container, a fresh virtual environment, a temporary directory, whatever your environment supports. If you cannot execute commands, say so plainly and ask the user to run the sequence and paste the output; never mark this check passed on inspection.
2. Execute the documented install command exactly as written, then the first usage example exactly as written.
3. Record every gap: an undocumented runtime version, a system package assumed present, a required environment variable, an output that differs from the README.
4. Fold each gap into the README as an explicit prerequisite or a verification step, then run the sequence again from clean.

Repeat until the documented path runs end to end with no undocumented step. Any performance number, compatibility matrix, scale limit, or "production ready" claim needs a source inside the repository - a benchmark script, a CI matrix, a changelog entry - or it comes out. When you cannot verify something, downgrade the claim to what you can verify and say which part is unconfirmed.

Step 5 - Choose the shape, then rewrite section by section

Pick the skeleton from ./references/readme-skeletons.md that matches what the reader is deciding, not what the code happens to be.

• A library reader is judging fit with an existing codebase.
• A CLI reader is comparing against a tool already installed.
• A framework reader is making a multi-year bet.

Order sections by how quickly each lets a reader disqualify the project. This is cognitive funneling, named by Kira in Art of README: widest and most disqualifying information first, narrowing to detail only a committed reader reaches. One consequence: a non-permissive licence belongs near the top, because it disqualifies fastest and hiding it wastes the reader's time.

Before writing, brainstorm the positioning explicitly instead of reaching for the first phrasing. Draft three candidate one-liners on different axes:

• what it does mechanically
• what problem it removes
• what it lets you stop using

Present them with each one's trade-off and your recommendation, and let the user choose. The one-liner propagates into the repository description, the registry page, and every link unfurl.

Draft one section at a time and get agreement before moving on; per-section approval surfaces a disagreement while it is still cheap to fix. For each section:

1. Write the shortest version that answers its question completely.
2. Replace every unfalsifiable claim ("simple", "blazing fast", "developer-friendly") with something a reader could check - a number, a dependency count, a supported-platform list, a

...