README Best Practices

This skill covers how to write a README that reads like a landing page rather than an API reference — the reader decides whether to keep reading within 3-5 seconds, so the first screen has to earn the rest.

Workflow for Writing a README

1. Draft the one-liner — Write a bold, specific sentence stating what the project does and why someone should care. Avoid "A tool that..."; aim for a punchline.
2. Write a working code example first — Put a copy-pasteable example in the first 5-10 lines of content, before installation instructions. Show the value proposition immediately.
3. Add badges — Build status, version, license, and coverage badges directly under the title, if the project has CI/publishing set up.
4. Write Quick Start — Zero-to-running in under 30 seconds, with no placeholder values the reader has to mentally substitute.
5. Fill in supporting sections — Features, Usage, Configuration, Contributing, License — using the structure below, only including sections that carry real information.
6. Verify every asset and link — Confirm referenced images (screenshots, demo.gif) exist on disk and that internal links resolve before publishing.
7. Read it cold — Reread the first screen as if seeing the project for the first time; cut anything that doesn't help a decision to keep reading or stop.

Opening Hook