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