readme-optimization

SKILL.md

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