GitHub README checklist: 15 things to check before you publish

  1. The title is the project name, as an H1.
  2. One sentence under the title says what it does and for whom.
  3. The repo description (the box under the repo name) repeats that sentence in 120 characters or fewer.
  4. Topics are set (6 to 10, lowercase) so people can find the repo.
  5. Prerequisites are listed: language version, OS, required tools.
  6. Install is one copy-pasteable command or short block.
  7. A first command works exactly as written. Test it on a clean machine or container.
  8. Usage has at least one example with the output shown.
  9. A screenshot or GIF is included if the project has visual or terminal output.
  10. Configuration lists only the options most people need, and links to the rest.
  11. Badges (if any) come after the tagline and are not more than a handful.
  12. Links all work, especially to the issues page and docs.
  13. Contributing: how to report a bug, how to send a patch.
  14. License is named in the README and a LICENSE file exists.
  15. No secrets, tokens or personal paths appear in examples.

Paste your README into the free checker to test items 1, 2, 5 to 9 and 13 to 14 automatically. For a full rewrite that fixes them, see below.

Rewrite my README - $5

After checkout you fill in a short form and the AI-written result appears on screen in under a minute. Not affiliated with GitHub.