---
name: readme-best-practices
description: Apply consistent structure, tone, and formatting to README.md files. Use when drafting, rewriting, or reviewing a project README to make it scannable and developer-friendly.
user-invocable: false
---

<objective>
Principles and patterns for writing effective README files for developer-facing projects. A README answers three questions in 30 seconds: What is this? Why should I care? How do I start? It is a storefront, not a manual — everything else links out.
</objective>

<essential_principles>

**Show, don't claim.** Developers distrust vague promises. Instead of "saves you hours" or "improves your workflow," show the tool doing something useful in three lines. The value should be self-evident — let the reader draw their own conclusions.

**Progressive disclosure.** Front-load the most important information. Push complexity into later sections, collapsible blocks, or linked docs.

**Scanability is non-negotiable.** Engineers scan, they don't read. Short paragraphs (2-3 sentences max), headers as signposts, code blocks for anything executable.

**The top 20% is the pitch.** Everything above the installation section should work as a standalone pitch. Everything below is reference material for people already convinced.
</essential_principles>

<readme_skeleton>
Include only sections that apply. This is the order — do not rearrange.

```
# Project Name
> One-line tagline: names the category and key differentiator

## What This Is
2-3 sentences. What it does, who it's for, what problem it solves.

## Features / What's Included
Scannable list or table grouped by use case.
Each item: verb-first description + "Use when:" trigger scenario.

## Quick Start
Fastest path to a working result. Copy-paste ready.

## Usage Examples
2-3 concrete examples, simple to complex.
Each example should reveal something new — don't repeat patterns.

## Configuration (if needed)
Only required config. Link out for advanced options.

## Updating
How to get new versions.

## Contributing (if applicable)
Brief guidance or link to CONTRIBUTING.md.

## License
One line with link.
```
</readme_skeleton>

<tone_and_language>

**Voice:** Senior engineer explaining their tool to a peer. Confident without boastful, specific without exhaustive.

**Do:**
- State facts, let value be obvious: "Generates type-safe API clients from OpenAPI specs in under 5 seconds."
- Use second person, active voice: "Run the command to install."
- Be specific, not superlative: "Reduces boilerplate by eliminating manual model mapping."
- Acknowledge tradeoffs: "Optimized for speed over flexibility — if you need custom X, see alternatives."
- Show personality through brevity: "No config files. No build step. Just works."

**Don't:**
- Hype language: "Revolutionary AI-powered developer experience!" — triggers immediate skepticism
- Vague benefits: "Improve your workflow and boost productivity" — says nothing concrete
- Condescending simplifiers: "Simply run..." / "It's easy" — implies the reader is foolish if they struggle
- Overly formal: "The aforementioned utility enables acquisition of..." — creates distance, wastes time

**Banned words:** "supercharge," "streamline," "empower," "leverage," "seamlessly," "simply," "just," "next-generation," "enterprise-grade," "cutting-edge" — "simply" and "just" imply the step is trivial; if it were, the reader wouldn't need documentation. Also watch for equivalent phrases ("all you need to do is…", "it's easy to…").

**Preferred verbs:** "automate," "generate," "skip," "replace," "handle," "check," "run"

**Framing:** Describe what each tool *does* (verb-oriented), not what it *is* (noun-oriented). "Use this to..." not "This will make you..."

**Calibration test:**
- Too informal: "Dude! This API is totally awesome!"
- Right: "This API lets you collect data about what your users like."
- Too formal: "The API documented by this page may enable the acquisition of information pertaining to user preferences."
</tone_and_language>

<formatting_rules>

**Tables vs lists vs prose:**
- Tables for comparing items with short, uniform attributes (~30 chars per cell). If content wraps on GitHub, switch to bullet lists.
- Bullet lists for everything else, including collections with longer descriptions.
- Prose only for narrative context (the "What This Is" section).

**Collapsible sections** (`<details>`) for content useful to <20% of readers: platform-specific installs, advanced config, edge case behaviors.

**Badges:** 3-5 max (build status, version, license). More signals insecurity, not quality.

**Code blocks:**
- No `$` prefix — prevents clean copy-paste.
- One logical action per block so each is independently copy-pasteable.
- State prerequisites before the install command, not after.
- Use `bash` syntax highlighting on fenced code blocks.

**Collections** (multiple tools/commands/features):
- Group by use case, not alphabetically.
- **Commands and CLI tools** — use the code-block-then-paragraph format. The code block is copy-pasteable; the paragraph describes what happens and when to use it:
  ~~~
  ```
  /command-name
  ```

  Verb-first description of what it does. Use when trigger scenario.
  ~~~
- **Features and capabilities** — use a bold heading followed by 1-2 paragraphs of prose. No bullet lists, no code blocks for the heading — the heading is the visual anchor, the paragraphs explain what it does and why it matters:
  ```
  ### Feature name

  First paragraph explains the core mechanic. Second paragraph
  adds nuance, tradeoffs, or how it connects to the rest of the system.
  ```
- **Short-description items** (reference docs, config options, file listings) — use the inline bold format:
  ```
  - **`name`** — Verb-first description of what it does.
    - Use when: short trigger scenario that helps the reader recognize relevance.
  ```
- Add a "How These Fit Together" section only when it reveals non-obvious connections. If you'd just be listing tools in order, cut it.

**Installation paths:**
- Present from most common to most specialized.
- Use clear headers and explain when to use each.
- Put rare methods in `<details>` blocks.
- When scoped install exists (user vs project), explain the tradeoff upfront:

  ```
  **User scope** — available across all your projects, only on your machine.
  **Project scope** — shared with your team via version control.
  ```
</formatting_rules>

<common_pitfalls>

1. **Wall of text at the top.** If the first three paragraphs are prose, most readers are gone. Lead with a one-liner, then a code block or table.

2. **Feature lists without context.** "Supports X, Y, Z" means nothing without showing when and why to use each. Pair features with use cases.

3. **Assuming the reader already cares.** Answer "why should I use this?" before "how do I use this?" If the reader scrolls past a ToC, feature matrix, and architecture diagram before finding how to install, the README has failed.

4. **Stale content.** Outdated installation commands or broken links erode trust faster than anything. Keep installation instructions tested.

5. **Not saying when NOT to use it.** Honest scoping builds trust. "If you need X, check out Y" makes people trust your recommendations for when your tool *is* appropriate.

6. **Documenting the self-evident.** Don't tell users `--help` exists or that they can read the source code. Every line should earn its place.

7. **Usage examples that repeat patterns.** Three examples showing different interaction styles are better than four where the last repeats the third. Each example should reveal something new.

8. **No subtraction pass.** After writing, re-read and ask "does removing this lose information?" for every section. Workflow sections, closing summaries, and scope sections often restate what's already covered.
</common_pitfalls>

<process>

1. **Explore the project**
   Investigate the codebase to understand: project name, what it does, who it's for, primary language/ecosystem, installation mechanism, key features, and existing documentation. Read manifest files, entry points, CLI definitions, and any existing README.

2. **Identify the project type**
   Determine: CLI tool, library, framework, collection of tools, web app, API, or other. This affects structure — collections need "What's Included" tables, single tools need "Features" lists.

3. **Fill gaps with the user**
   Clarify anything exploration could not determine: target audience, preferred installation method, features to highlight, sections to include/exclude, existing content to preserve or drop.

4. **Draft the README using the skeleton**
   Apply the structure from `<readme_skeleton>`. Include only sections that apply. Write the tagline first — it forces you to name the category and differentiator in one line.

5. **Subtraction pass**
   Re-read every section and ask "does removing this lose information?" Cut workflow sections that restate individual item descriptions. Cut scope sections that repeat the tagline. Cut closing summaries.

6. **Write the file**
   If an existing README exists, show a summary of key changes and confirm before overwriting.
</process>

<success_criteria>
README writing is complete when:
- [ ] Subtraction pass completed — no section restates content from another section
- [ ] Tagline names category and key differentiator in one line
- [ ] Top 20% works as standalone pitch — answers what/why/how in 30 seconds, quick start not buried
- [ ] Features grouped by use case with "Use when:" context, not bare lists
- [ ] Honest scoping — mentions when NOT to use the tool if applicable
- [ ] No banned words appear anywhere in the output
- [ ] Code blocks have no `$` prefix and are independently copy-pasteable
</success_criteria>