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. GitHub's platform surfaces around the page - Discussions, release notifications, star policy - belong to samber/developer-platform-skills@github-engagement-playbook.