A README is the front door. Its first screen must answer three questions: what is this, is it for me, how do I try it. Everything after that is in order of how soon a new user needs it. The README is verified against the code, not written from memory of the code.
Read before writing
- The manifest (
package.json, pyproject.toml, Cargo.toml, go.mod): name, version, entry points, scripts, dependencies, engines.
- The entry point and the public surface: CLI flags (
--help output if it runs), exported functions, routes, config schema.
- Existing docs,
CONTRIBUTING, LICENSE, CI config, examples directory, tests (they show real usage).
- Run the quick start you intend to document. If it does not work, the README says what actually works.
Structure
# name
One sentence: what it does and for whom. (Badges on the next line, at most four: CI, version, license, one more.)
Two or three sentences: the problem it solves and the one thing that distinguishes it. Optional: a screenshot or a 10-line example that shows the payoff.
## Quick start
Prerequisites in one line (runtime version, accounts, keys).
The minimal commands, copy-pasteable, that produce a visible result. Nothing optional here.
What the user should see when it worked.
## Usage
The three to five most common tasks, each: one sentence, one code block, one sentence on the result. Link to full reference docs for the rest.
## Configuration
Table: option, env var or flag, default, what it does. Only options a user will actually set.
## How it works (optional)
Three to six sentences or a diagram, for the reader deciding whether to trust or extend it.
## Development
Clone, install, test, lint, in four commands. Link to CONTRIBUTING for the rest.
## License
Omit a section rather than fill it with filler. A library README leads with the API example; a CLI README leads with the command; a service README leads with the deploy or run command.
Rules
- Verify every command by running it (or by reading the script it invokes when running is not possible) and say the runtime version it was verified with.
- Match the manifest: the install command uses the real package name and manager; scripts named in the README exist in the manifest.
- No aspirational features. If it is planned, it goes in a roadmap section or an issue, not in Usage.
- Sentence case headings, short paragraphs, no em dashes, no "simply", no "just".
- Keep the top stable: the first screen changes rarely; volatile detail (options, versions) lives lower or in generated sections between markers so a script can update it.
- Badges are signals, not decoration: a red CI badge on the README is honest; ten badges are noise.
- Link, do not duplicate: the changelog, the API reference, and the contribution guide each live in one place.
- Run
humanize on the prose before returning.
Restructuring an existing README
- Inventory: list every section and what question it answers.
- Check each claim against the code; mark stale ones.
- Reorder by the new user's timeline; move contributor material below user material.
- Cut what the code no longer does; move history to the changelog.
- Keep the URL anchors people may have linked (
#install, #usage) even when renaming headings, via a short redirect line if needed.
Report what was removed and why, separately from the new text.
1---2name: readme-writing3description: "Write or restructure a README that gets a reader from landing to first success in minutes: a one-line purpose, a working quick start verified against the actual code, then usage, configuration, and contribution pointers in the order a new user needs them, with nothing the code contradicts. Reads the repository first and never documents behaviour it has not confirmed. Use when a project has no README, when the README has drifted from the code, or before publishing a package or repository."4argument-hint: "(optional) the audience (users, contributors, both) and anything the README must cover"5metadata:6 source: https://skillmd.com/skills/khaledsaeed18/readme-writing7---89A README is the front door. Its first screen must answer three questions: what is this, is it for me, how do I try it. Everything after that is in order of how soon a new user needs it. The README is verified against the code, not written from memory of the code.1011## Read before writing12131. The manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`): name, version, entry points, scripts, dependencies, engines.142. The entry point and the public surface: CLI flags (`--help` output if it runs), exported functions, routes, config schema.153. Existing docs, `CONTRIBUTING`, `LICENSE`, CI config, examples directory, tests (they show real usage).164. Run the quick start you intend to document. If it does not work, the README says what actually works.1718## Structure1920```markdown21# name2223One sentence: what it does and for whom. (Badges on the next line, at most four: CI, version, license, one more.)2425Two or three sentences: the problem it solves and the one thing that distinguishes it. Optional: a screenshot or a 10-line example that shows the payoff.2627## Quick start2829Prerequisites in one line (runtime version, accounts, keys).30The minimal commands, copy-pasteable, that produce a visible result. Nothing optional here.31What the user should see when it worked.3233## Usage3435The three to five most common tasks, each: one sentence, one code block, one sentence on the result. Link to full reference docs for the rest.3637## Configuration3839Table: option, env var or flag, default, what it does. Only options a user will actually set.4041## How it works (optional)4243Three to six sentences or a diagram, for the reader deciding whether to trust or extend it.4445## Development4647Clone, install, test, lint, in four commands. Link to CONTRIBUTING for the rest.4849## License50```5152Omit a section rather than fill it with filler. A library README leads with the API example; a CLI README leads with the command; a service README leads with the deploy or run command.5354## Rules5556- **Verify every command** by running it (or by reading the script it invokes when running is not possible) and say the runtime version it was verified with.57- **Match the manifest**: the install command uses the real package name and manager; scripts named in the README exist in the manifest.58- **No aspirational features.** If it is planned, it goes in a roadmap section or an issue, not in Usage.59- **Sentence case headings**, short paragraphs, no em dashes, no "simply", no "just".60- **Keep the top stable**: the first screen changes rarely; volatile detail (options, versions) lives lower or in generated sections between markers so a script can update it.61- **Badges are signals, not decoration**: a red CI badge on the README is honest; ten badges are noise.62- **Link, do not duplicate**: the changelog, the API reference, and the contribution guide each live in one place.63- Run `humanize` on the prose before returning.6465## Restructuring an existing README66671. Inventory: list every section and what question it answers.682. Check each claim against the code; mark stale ones.693. Reorder by the new user's timeline; move contributor material below user material.704. Cut what the code no longer does; move history to the changelog.715. Keep the URL anchors people may have linked (`#install`, `#usage`) even when renaming headings, via a short redirect line if needed.7273Report what was removed and why, separately from the new text.