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 Show more Installs 1.3K Repository samber/develope…s-skills GitHub Stars 2 First Seen Sep 13, 2026 Security Audits Gen Agent Trust Hub Warn Socket Pass Snyk Pass