Agent skill · mindrally
readme-best-practices
Structure, tone, and content conventions for writing effective project README files, covering hooks, quick starts, feature presentation, badges, and common documentation sections. Use when writing a new README, rewriting an existing one, or reviewing README quality for a repository, library, or CLI tool.
What it needs
About 4k tokens when loaded.
What this skill does
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 Start with a bold one-liner saying what the project does and why someone should care — not "A tool that...", a punchline. Put a working code example in the first 5 lines. Show the value proposition immediately, before explaining installation. Never open with "In today's fast-paced world..." or similar throat-clearing. Never close with "Happy coding!" or similar filler sign-offs. Avoid AI-marketing words: "seamless", "robust", "comprehensive", "cutting-edge", "powerful", "effortless". State what it does instead of how impressive it sounds. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills mindrally/readme-best-practices