---
name: forge-readme
description: README discipline for libraries and applications. Title + one-sentence description + install + quickstart in the first viewport, banned marketing words, badge limits (3 max), untagged code blocks forbidden, different templates for library vs application. Contains paste-ready templates + a worked drift-style example. Use when writing or rewriting a README for a public or internal project.
license: MIT
---

# forge-readme

You are writing the document that decides whether someone uses your project or closes the tab. Default agent output produces READMEs that are either a 50-line marketing pitch with no install instructions, or a wall of badges and tables of contents that delay the first useful line by three screens. This skill exists to fix both failure modes.

A good README answers four questions in order: **What is this? How do I install it? How do I use it? Where do I learn more?** Everything else is decoration.

## Quick reference (the things you must never ship)

1. Multiple H1 headings.
2. "Welcome to..." or "In today's fast-paced world..."
3. Marketing filler: "blazingly fast", "revolutionary", "next-generation", "comprehensive", "powerful", "seamless", "robust", "world-class".
4. More than three badges in the header.
5. Badges before the one-sentence description.
6. Table of contents on a README under 200 lines.
7. Bare code fences with no language tag.
8. Install section more than two screens from the top.
9. "Made with ❤️" badge.
10. `foo` / `bar` / `example.com` placeholders that ship.

## Hard rules

### Structure

**1. Title, one-sentence description, install, quickstart - in the first viewport.** Reader on a 13-inch laptop sees all four without scrolling.

**2. One-sentence description under the title. No paragraph.**

```
BAD:  "Welcome to ProjectName! In today's evolving landscape of developer tooling..."
GOOD: "Fast SQL linter for safe Postgres migrations. 94 rules, sub-100ms runs."
```

**3. Quickstart is a copy-pastable block that works on the first try.** Not a tutorial, not options, not edge cases. Shortest path from zero to "I see it working."

```bash
npm install forge-skill
npx forge-skill verify
```

If your quickstart requires editing a config file, your quickstart is too long.

**4. One H1, the project name.** Everything else H2 or deeper.

**5. Section order:**

1. Title + one-liner
2. Install
3. Quickstart
4. Usage / features
5. Configuration
6. How it works (optional)
7. FAQ (only with real questions)
8. Contributing
9. License

### Voice

**6. Write to a reader who is skimming.** Bold the operative phrase. Bullets for parallel items. Tables for items with shared columns.

**7. No marketing copy.** Cut every "revolutionary," "next-generation," "blazingly fast," "robust," "seamless," "powerful," "comprehensive." Replace with specifics. "Blazingly fast" means nothing; "p99 under 80ms on a 1M-row table" is a real claim.

**8. Show, do not tell.** Code block > paragraph. Screenshot/GIF > ten paragraphs.

**9. Examples are real, not placeholders.** `foo`, `bar`, `myVar`, `example.com` waste attention. Use concrete domain values.

### Badges

**10. Three maximum in the header.** Status (build or version), license, one social proof.

**11. No badge that does not link somewhere useful.** "Made with love" is noise.

### Code blocks

**12. Every code block has a language tag.** ` ```bash `, ` ```ts `, ` ```sql `. Not bare ` ``` `.

**13. Code blocks tested.** At minimum, copy-paste the quickstart into a clean directory and confirm it works.

**14. No `...` in code samples meant to be copied.** Either show the full block or split into two with prose between.

### Length

**15. Library README: one to three screens.** More? Docs site or `docs/` folder.

**16. Application README: shorter.** Apps deployed, not consumed via copy-paste. README for contributors.

### Visuals

**17. Hero image or GIF at the top, if appropriate.** Under 1MB or video host.

**18. Diagrams via Mermaid, not screenshots of draw.io.** Mermaid renders in GitHub and stays editable.

## Common AI-output patterns to reject

| Pattern | Why bad | Fix |
| --- | --- | --- |
| "Welcome to FooLib!" | Marketing greeting | Direct: "Fast X for Y." |
| 7 badges before description | Chrome overload | Three badges max, after description |
| Table of contents on 60-line README | Decorative | Cut |
| `npm install` 4 screens deep | Lost the user | Install in first viewport |
| Bare ` ``` ` fences | Highlighting fails | ` ```bash ` (or appropriate) |
| "blazingly fast" / "powerful" | Filler | Specific metric |
| `myUser`, `example.com` | Placeholder ships | Real domain values |
| Multiple H1s | Breaks accessibility | One H1, rest H2/H3 |
| "Made with ❤️" badge | Decorative | Cut |
| AI attribution in README | Inappropriate | Remove |

## Templates

### Library README

```markdown
# project-name

> One-sentence description with the differentiator.

[![Build](https://...)](...)
[![License](https://...)](...)
[![npm](https://...)](...)

## Install

\`\`\`bash
npm install project-name
\`\`\`

## Quickstart

\`\`\`ts
import { thing } from 'project-name';

const result = await thing({ id: '01HXY...' });
console.log(result);
\`\`\`

## Usage

[Three to five short subsections showing real features.]

## Configuration

[Table of options or link to dedicated docs.]

## License

MIT
```

### Application README

```markdown
# project-name

> One-sentence description of what this app does and who it is for.

## Development

\`\`\`bash
pnpm install
pnpm dev
\`\`\`

App runs on http://localhost:3000.

## Stack

- Framework, version
- Database, version
- Hosting, region

## Deployment

[One paragraph or link to runbook.]

## License

MIT (or proprietary)
```

## Worked example

```markdown
# drift

> Fast SQL linter for safe Postgres migrations. 94 rules, sub-100ms runs.

[![CI](https://github.com/f4rkh4d/drift/actions/workflows/ci.yml/badge.svg)](https://github.com/f4rkh4d/drift/actions)
[![Crates](https://img.shields.io/crates/v/drift-sql)](https://crates.io/crates/drift-sql)
[![MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

## Install

\`\`\`bash
cargo install drift-sql
\`\`\`

## Quickstart

\`\`\`bash
drift lint migrations/0042_add_user_phone.sql
\`\`\`

Returns non-zero if the migration violates any of the 94 rules - things like
`ADD COLUMN ... NOT NULL` on a non-empty table, `CREATE INDEX` without
`CONCURRENTLY`, or volatile defaults that rewrite the table.

## Rules

drift catches:

- **Locking patterns** (12 rules) - operations that take ACCESS EXCLUSIVE locks on large tables
- **Volatile defaults** (8 rules) - `DEFAULT now()` / `DEFAULT gen_random_uuid()` in ADD COLUMN
- **Index discipline** (15 rules) - CREATE INDEX without CONCURRENTLY, missing FK indexes
- **Constraint hygiene** (14 rules) - NOT VALID + VALIDATE pattern, FK without NOT VALID

Run `drift rules` to see all 94 with explanations.

## Configuration

Optional `.drift.toml` at the repo root:

\`\`\`toml
[rules]
disable = ["lock-table-rewrites"]   # if you know what you're doing
fail_on = "warning"                 # default: error
\`\`\`

## Try it in the browser

[drift.frkhd.com/play](https://drift.frkhd.com/play/) runs the same rules via WASM.

## License

MIT.
```

What this does right: H1 = project name only; one-sentence description directly under; three badges max; install in first viewport; quickstart is a single copy-pastable command; real file path example; bullets describe categories with specific counts (specifics over "comprehensive"); links to deeper info; ends with license. Under three screens.

## Workflow

1. **State the one-line description out loud.** If you cannot say what the project does in one sentence without using "and," it does too much or you do not know what it is yet.
2. **Write install + quickstart first.** Test from a clean environment.
3. **Write usage examples next, copying from real working code.**
4. **Add badges and screenshots last.** Decoration on a finished cake.
5. **Read on a phone.** Mobile-readable READMEs read better on desktop too.

## Verification

```bash
bash skills/docs/forge-readme/verify/check_readme.sh path/to/README.md
```

Flags: multiple H1s, no install section, untagged code blocks, banned marketing words, more than three badges.

## When to skip this skill

- Personal scratch projects with no audience.
- Generated READMEs from tooling with a fixed format.
- Migration docs, ADRs, runbooks - their own conventions.

## Related skills

- [`forge-pr-description`](../../dx/forge-pr-description/SKILL.md) - same discipline applied to PRs.
- [`forge-commit-messages`](../../dx/forge-commit-messages/SKILL.md) - same discipline applied to commits.
- [`forge-naming`](../../dx/forge-naming/SKILL.md) - the names you describe in the README.