readme-best-practices — Claude Code skill for README files
The readme-best-practices Claude Code skill guides README writing and review. It activates for a new project README, a rewrite, or a repository documentation check.
Apache-2.0 121 installs ★ 312 updated 2026-10-08
npx skills add Mindrally/skills --skill readme-best-practices -a claude-codeWhat readme-best-practices does
The skill gives an README a clear path from a concise project introduction to a working example, then to installation and supporting sections. Its guidance covers repositories, libraries, and CLI tools.
It recommends feature tables, runnable snippets, and checks for linked assets and internal anchors. Sections belong in the file only when they add useful project information. Build, version, license, and coverage badges fit projects with CI or publishing set up.
What it helps with
- draft a README for a new project
- rework an existing README structure
- review repository documentation quality
- write a quick start with a working example
Example prompts for the agent
- Write a README for my library with installation steps and a short example.
- Restructure this CLI README and add a clear quick start.
- Review the repository README for links, examples, and core sections.
How to install readme-best-practices
1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill readme-best-practices -a claude-code2Manually: put the files in place
~/.claude/skills/readme-best-practices/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/readme-best-practices/
1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill readme-best-practices -a codex2Manually: put the files in place
.agents/skills/readme-best-practices/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill readme-best-practices -a cursor2Manually: put the files in place
.cursor/skills/readme-best-practices/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Mindrally/skills readme-best-practices2Manually: put the files in place
.github/skills/readme-best-practices/SKILL.md1Skills CLI (Vercel)
npx skills add Mindrally/skills --skill readme-best-practices -a gemini-cli2Platform CLI
gemini skills install https://github.com/Mindrally/skills --path readme-best-practicesManually: put the files in place
.devin/skills/readme-best-practices/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Mindrally/skills --skill readme-best-practices -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about readme-best-practices
How do I install readme-best-practices in Claude Code?
Run npx skills add Mindrally/skills --skill readme-best-practices -a claude-code. The skill file is at ~/.claude/skills/readme-best-practices/SKILL.md.
What does readme-best-practices do?
It guides README creation and review, with advice on structure, quick starts, code examples, feature descriptions, badges, and common documentation sections.
When does the skill activate?
It is used to write a new README, revise an existing one, or assess documentation for a repository, library, or CLI tool.
Source text
SKILL.md · Apache-2.0
---
name: readme-best-practices
description: "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."
metadata:
maintainer: Mindrally
source: https://github.com/Mindrally/skills
---
# 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.
## Standard Structure
A typical README benefits from these sections, roughly in this order — include only the ones that add real information for this project:
1. **Title + one-liner** — project name and the bold hook sentence.
2. **Badges** — build status, latest version, license, test coverage.
3. **Quick demo** — a code snippet, GIF, or screenshot showing the thing working.
4. **Features** — a two-column table, not a wall of bullets (see below).
5. **Installation** — the exact command(s) to install, per package manager if there's more than one.
6. **Quick Start / Usage** — copy-paste-ready minimal example, then a couple of more advanced examples.
7. **Configuration** — options, environment variables, config file format, with defaults noted.
8. **API Reference** (or a link to one) — for libraries with a non-trivial public surface.
9. **FAQ / Troubleshooting** — the 3-5 questions people actually ask in issues.
10. **Contributing** — how to set up the dev environment, run tests, and submit a PR; link to `CONTRIBUTING.md` if it exists.
11. **License** — name and link to the license file.
12. **Author / Acknowledgments** — credit maintainers and major dependencies.
## Feature Presentation
- Use feature tables (two columns: feature, description) instead of `**Feature:**` bullet lists — tables scan faster than repeated bold-prefix bullets.
```markdown
| Feature | Description |
|---|---|
| Zero-config | Works out of the box with sensible defaults |
| Streaming | Handles gigabyte-scale files without loading them into memory |
| Type-safe | Full TypeScript definitions, no `any` in the public API |
```
## Quick Start Requirements
- Must be copy-paste ready: zero to running in 30 seconds.
- Do not prefix shell commands with `$` — it breaks copy-paste.
- Show the install command and the minimal usage example together, not split across distant sections.
```bash
npm install awesome-lib
awesome-lib run --input data.csv --output report.json
```
```js
import { parse } from "awesome-lib";
const result = parse("data.csv");
console.log(result.summary);
```
## Prose and Formatting
- Vary sentence length and structure — mix one-liners with short paragraphs and tables. Walls of same-length bullets read as filler.
- Use headings to let readers jump straight to the section they need; don't force a linear read.
- Prefer runnable examples over prose descriptions of behavior wherever both are possible.
- Keep line-level formatting consistent: one fenced code block per language/command, explicit language tags (` ```bash `, ` ```json `) for syntax highlighting.
## Badges
- Use badges for objective, machine-checkable facts: CI status, published version, license, downloads, coverage.
- Keep the badge row short — 3-6 badges. A wall of badges is as noisy as a wall of bullets.
- Common sources: shields.io for custom badges, the CI provider's own badge markdown, npm/PyPI's official badge snippets.
## Assets and Links
- Check that referenced assets (`demo.gif`, screenshots) actually exist on disk before adding image links — a broken image in the first screen kills credibility instantly.
- Verify internal anchor links (table of contents, "see Configuration below") resolve to real headings.
- Prefer relative paths for repo-local assets so they render correctly on the git host and in package registries alike.
## Author / Contact Section
- Include a visual card or badge for the author/maintainer rather than plain text like "Made by username" — a GitHub profile badge, a small avatar + link, or a sponsor button reads as more intentional.
- For multi-maintainer projects, list maintainers with their role or area of ownership rather than a flat name list.
## Common Mistakes to Avoid
- Leading with installation instead of value — readers don't know why they should install it yet.
- Documenting every configuration option in prose instead of a table.
- Letting the README drift from the actual CLI/API surface — stale examples that no longer run are worse than no examples.
- Mixing marketing language ("blazing fast", "enterprise-grade") with technical documentation — pick one register and stay technical.
- Duplicating full API docs in the README when a generated reference (TypeDoc, Sphinx, godoc) already exists — link to it instead.
© Mindrally · Apache-2.0 · Mindrally/skills