# Readme That Converts

> Write or rewrite a README that turns a visitor into a user. Use when creating a README, when a project's README is a wall of text or a stub, when the user says "nobody understands what my project does", or when preparing a repo for launch. Covers the 30-second rule, section ordering, badge discipline, install and quickstart blocks, screenshots/demos, comparison tables, and multi-language README structure. Also use for polishing package-registry descriptions (npm, PyPI, crates.io) and the GitHub repo About blurb.

- Skill: `the-open-agent/readme-that-converts` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add the-open-agent/readme-that-converts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/the-open-agent/readme-that-converts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: the-open-agent (https://skillmd.com/u/the-open-agent)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/the-open-agent/readme-that-converts

---


# A README That Converts

The README is the product page. For most visitors it is the *entire* product — they
will decide in under 30 seconds whether to keep reading, and they are on a phone about
40% of the time.

## The 30-second test

A first-time visitor must be able to answer, above the fold, without scrolling past
the first screen:

1. **What is this?** (category — "a CLI", "a Python library", "a Postgres extension")
2. **What problem does it solve?** (their problem, in their words)
3. **Should I keep reading?** (is it for their language/platform/scale)

If a visitor must scroll to learn what the project *is*, the README has already failed.
Badges, logos, and tables of contents are not answers to those questions.

Apply the test literally: read only the first 15 lines aloud and ask whether a
stranger could describe the project. If not, cut until they can.

## Section order

Ordered by how many readers get that far. Later sections cost nothing; earlier ones
are expensive real estate.

```markdown
# Name
> One sentence. Under 15 words. Category + differentiator.

[badges: build | version | license]     ← 3–5 max, one line

[hero: screenshot, GIF, or 6-line code sample]

## Why <Name>?              ← 3–5 bullets, comparative, concrete
## Install                  ← copy-pasteable, one command if possible
## Quickstart               ← smallest complete working example
## Usage / Features         ← progressive depth
## Documentation            ← link out once docs exceed the README
## Comparison               ← if entering a crowded space
## Contributing             ← one line + link to CONTRIBUTING.md
## License
```

Notably absent near the top: table of contents (GitHub renders one from the outline
menu), long feature matrices, architecture diagrams, and the origin story. They belong
in `docs/`, or below the fold.

## Writing the one-liner

Formula: `<category> for <audience> that <differentiator>`

- "A build tool for JavaScript that skips bundling in development."
- "A Rust HTTP client with connection pooling and no async runtime."
- "Kubernetes operator that snapshots Postgres to S3 on a schedule."

Delete these words: *modern, blazing-fast, simple, powerful, elegant, robust,
lightweight, next-generation, developer-friendly, opinionated, batteries-included*.
They carry zero information because every project claims them. If removing an adjective
does not change the meaning, it was noise.

Use the same one-liner in the GitHub About field, the package description, and the
social preview. Consistency compounds recognition.

## The hero

Pick exactly one, matched to the project type:

| Project type | Best hero |
|---|---|
| CLI tool | Terminal recording (asciinema, VHS) or a copy-pasteable session |
| Library / API | 6–10 line code sample showing the core call |
| UI / app | Screenshot, dark mode, real data, no lorem ipsum |
| Infrastructure | A small architecture diagram, or a config + result pair |

Rules:

- **Real output, real data.** `foo`/`bar` examples read as untested.
- **Under 10 lines** for code heroes. If the minimum viable example is 40 lines, the
  API is the problem — see `api-design`.
- **GIFs under ~3 MB**, or the mobile experience is a gray box. Prefer
  [VHS](https://github.com/charmbracelet/vhs) for terminal demos: it is scripted, so
  it regenerates when the CLI changes instead of rotting.
- **Host images in-repo** (`docs/assets/` or `.github/assets/`), not on an image host
  that will 404 in two years.

## Install and quickstart

The single highest-value block in the file. Requirements:

- **Copy-pasteable verbatim.** No `<your-token-here>` in the first command.
- **Ordered by likelihood.** Put the package manager 80% of users have first; hide
  the rest behind a `<details>` block.
- **Show the expected output.** It tells the user it worked.
- **Test it.** Run the exact commands in a clean container before shipping. A broken
  install command is the most expensive bug a project can have — it converts every
  arriving user into a lost one, silently.

````markdown
## Install

```bash
npm install -g widget
```

<details>
<summary>Other install methods</summary>

```bash
brew install widget          # macOS
cargo install widget         # from source
docker run ghcr.io/org/widget:latest
```
</details>

## Quickstart

```bash
widget init my-app && cd my-app
widget dev
```
```
✓ Ready on http://localhost:3000 (142ms)
```
````

## Badges

Three to five, one line, all meaningful. Each badge must answer a question a user
actually has:

- **Build status** — is `main` healthy?
- **Latest version** — is this maintained?
- **License** — may I use it?
- **Downloads** — do others use it? (only once the number is non-embarrassing)
- **Discord/Slack** — where do I get help? (only if it is staffed)

Skip: code style, PRs-welcome, made-with-love, "awesome" self-badges, and coverage
percentages under 80%. A wall of 14 badges reads as compensating and pushes the
one-liner below the fold.

## Comparison tables

Only if entering a crowded category. Rules that keep it credible:

- **Be fair.** Users will verify, and a dishonest table is remembered longer than the
  project. Include a column where a competitor wins.
- **Compare on axes users choose by** — not on feature counts.
- **Date it.** "As of 2026-03, v2.1 vs v4.0." Comparisons rot.
- **Never disparage.** "X is bloated" reads as insecurity; "X bundles a runtime; we
  don't" is a fact the reader can act on.

Alternative that ages better: a **"When not to use this"** section. It builds more
trust than any table, costs three lines, and filters out users who would have opened
mismatched issues.

## Multi-language READMEs

For projects with international users, a language switcher at the top:

```markdown
<div align="center">

**English** · [简体中文](i18n/README.zh-CN.md) · [日本語](i18n/README.ja.md) · [Español](i18n/README.es.md)

</div>
```

Conventions that work:

- **English is `README.md`** at the root — GitHub renders it by default and it is the
  lingua franca of the issue tracker. Translations live in `i18n/README.<tag>.md`,
  using BCP-47 tags (`zh-CN`, `pt-BR`, `es`, `ja`, `ko`, `fr`, `de`).
- **Same switcher block at the top of every translation**, with the current language
  bolded and un-linked.
- **Translations are contributions.** Name a maintainer per language in
  `CONTRIBUTING.md` and stamp each file with the commit or version it tracks.
- **A stale translation is worse than none** — it ships wrong install commands. If a
  translation falls more than a minor version behind, add a banner linking to English.
- **Never machine-translate code blocks, flags, or error strings.** Translate prose;
  leave the commands identical.

## Anti-patterns

- **README as changelog.** Move it to `CHANGELOG.md`.
- **The origin story first.** "In 2023 I was frustrated with..." Nobody has bought in
  yet. Put it at the bottom, or in a blog post.
- **Install instructions that don't work.** Test in a clean container, every release.
- **Screenshots of code.** Unsearchable, uncopyable, inaccessible. Use code fences.
- **A wall of badges above the name.**
- **"Documentation coming soon."** Three honest sentences beat a promise.
- **Emoji headers on every section.** Fine in moderation; at every heading it reads as
  filler and hurts screen readers.
- **Full API reference inline.** Once it exceeds a screen, move to `docs/` and link.
- **No link back to the docs site** from the README, and no link back to the repo
  from the docs site.

## Maintenance

The README decays fastest of any file, because it is the one nobody re-reads.

- Re-run every command block at each minor release (automate it — see `ci-pipelines`)
- Regenerate terminal recordings when the CLI output changes
- Re-check comparison tables twice a year, or delete them
- When the project's scope changes, rewrite the one-liner *first* — everything
  downstream inherits its framing