The README opens with one sentence saying what the project does
A reader decides in about five seconds whether to keep reading. A title followed by a badge wall or a table of contents spends that budget on nothing.
Observable check
the first paragraph of README.md after the title is a single sentence naming what the project is and who it is for, and it appears before any table of contents, badge row, or ## heading.
Where this comes from
- https://github.com/evilmartians/agent-skills/blob/main/skills/good-readme/SKILL.md
- https://evilmartians.com/chronicles/how-to-make-your-open-source-popular
Last read against these sources on 2026-07-28.
Neither source is a specification, and both are weaker than the primary sources elsewhere in this file. They are recorded because they are where this opinion actually came from: oss-readme is a fork of that skill, pinned in skills/oss-readme/sources.json at SHA 0813c8304717dc2fa392b6f4a475f3ac6c8f7336, and the essay is the same argument in prose by the same authors. Upstream's opening block asks for what it does in plain conversational language, the user benefit, and the differentiation from alternatives; this rule keeps only the first and caps it at one sentence. The reading on 2026-07-28 was of the current upstream file, not the pinned SHA.