/readme-writing

name: readme-writing
description: How to write a README that gets a project understood and running fast — lead with what/why, a 60-second quickstart, then usage, config, contributing, and license. Covers required sections, show-don't-tell examples, scannability, badges, and failure modes. Use when writing or auditing a project README.
type: skill
version: 2.0.0
updated: 2026-06-29

README Writing

The README is the **front door** of a project. Most readers arrive with one of three jobs: *decide if this is worth their time*, *get it running*, or *find one specific answer*. A good README serves all three in the order they appear — orientation first, action second, depth on demand. This skill is the deep reference for writing one: the required sections, the writing moves that make it scannable, the runnable-example discipline, and the failure modes that quietly drive readers away. Heavy detail lives in `references/`; copy-paste material in `examples/`; a runnable linter in `scripts/`.

Mental model

A README is read in **three passes**, and you write top-to-bottom to match them:

| Pass | Reader's question | What answers it | |---|---|---| | Skim (10s) | "What is this and is it for me?" | Title + one-line description + badges | | Try (60s) | "Can I get it running?" | Install + minimal quickstart | | Use (later) | "How do I do X specifically?" | Usage, configuration, links to deeper docs |

Optimize ruthlessly for the first 60 seconds. A reader who can't tell what the project does, or who hits a broken install command, leaves and does not come back. Everything else is recoverable; the first screen is not.

The required sections (in order)

A complete README has these, roughly in this sequence. Not every project needs every one, but you must make a deliberate choice to omit, never an accidental one.

1. **Title + one-line description** — what it is and who it's for, no preamble, no "Welcome to". 2. **Badges** — build status, version, license, coverage. Signal of health, scanned in a glance. 3. **Why / value** — the problem it solves, optionally a screenshot, GIF, or short result example. 4. **Install** — the minimal commands to get the dependency in place, copy-pasteable and verified. 5. **Quickstart / Usage** — the smallest end-to-end example that produces a visible result. 6. **Configuration** — options, env vars, defaults — as a table, not prose. 7. **Contributing** — how to set up a dev environment and the contribution flow (link to `CONTRIBUTING.md`). 8. **License** — the SPDX name and a link to the `LICENSE` file.

The full anatomy, with what to include and skip per project type (library vs CLI vs service vs framework), is in `references/anatomy.md`.

Lead with what and why

The opening is the most-read and most-botched part. State the **what** in one line, then the **why**. Do not bury it under a logo, a table of contents, or a wall of badges.

# Forge

Forge builds and maintains AI agents and skills through a self-improving maker/checker loop —
so your automation gets better on every run instead of rotting.

[![build](https://img.shields.io/badge/build-passing-brightgreen)]()
[![npm](https://img.shields.io/npm/v/forge)]()
[![license](https://img.shields.io/badge/license-MIT-blue)]()

Within two sentences the reader knows the category (agent tooling), the mechanism (maker/checker loop), and the payoff (self-improving, no rot). Compare the anti-pattern: *"Welcome to Forge! Forge is a powerful, flexible, modern, enterprise-grade platform for..."* — three adjectives and zero information. See `references/writing-style.md` for the full list of filler phrases to cut.

The 60-second quickstart

The quickstart is a promise: *paste these commands and see it work.* It must be **copy-pasteable**, **self-contained**, and **actually run** — test it in a clean checkout before shipping.

## Quick start

\`\`\`bash
git clone https://github.com/acme/forge && cd forge
npm install
npx forge audit ./my-project    # prints a scorecard
\`\`\`

You should see a table of findings within a few seconds. Next, try `forge fix` to apply them.

Rules that make or break it:

• **Show the expected output**, or at least describe it ("you should see a table"). A command with no

visible result leaves the reader unsure it worked.

• **One happy path only.** Do not branch into "if you use yarn / pnpm / bun" in the quickstart — pick

one, link the rest. Optionality kills momentum.

• **No undeclared prerequisites.** If it needs Node 20+, a running Postgres, or an API key, say so

*before* the commands, not in a stack trace the reader hits later.

Show, don't tell

Prose describing behavior ages badly and is hard to trust. A **runnable example** is self-verifying — either it works or the reader sees it break. Prefer concrete examples over adjectives at every turn.

## Usage

\`\`\`js
import { Forge } from 'forge';

const forge = new Forge({ target: './my-project' });
const report = await forge.audit();

console.log(report.score);        // 87
console.log(report.findings[0]);  // { rule: 'no-secrets', severity: 'high', file: '.env' }
\`\`\`

The inline comments showing return values turn a snippet into documentation. This is why `examples/` ships a `good-readme-example.md` and a `README.template.md` you can adapt — see *Files in this package*.

Make it scannable

Readers skim, they do not read. Structure for the eye:

• **Headings every few paragraphs** so the table of contents (and the reader's scroll) has anchors.
• **Tables for anything with structure** — config options, CLI flags, comparison matrices. A 5-row

table beats two paragraphs of "the `--depth` flag controls...".

• **Code blocks for anything runnable**, always fenced with a language for syntax highlighting.
• **Short paragraphs.** One idea each. Walls of text are scrolled past, not read.
• **Link out for depth.** The README is a launchpad, not the manual. Link to `docs/`, the wiki, or