readme-standard

README Standard

One structure for every public README in the steipete and openclaw orgs. Load

this skill before writing or reviewing a README. The reference implementation

is openclaw/fs-safe — read its README

first if unsure what "good" looks like.

The spine

Every README answers, in order, with no detours:

1. What is this? — one sentence a stranger understands.
2. How do I use it? — smallest real install + a quickstart that proves the pitch.
3. Progressively more complex — each section assumes the previous one; deep

reference material moves to docs/ (or the docs site) and gets linked.

Concretely:

# <name> <one emoji> — <playful tagline, one line>

<badge row>

<1–2 sober sentences: what it is, who it is for. No adjectives doing the work
nouns should do.>

<OPTIONAL: one small code/terminal sample (≤10 lines) that demonstrates the
core value. If one sample can prove the pitch, put it here.>

## Install          ← smallest path first (brew/npm/npx), alternatives after
## Quick start      ← 60 seconds to first success; commands must actually run
## <core sections>  ← 2–6 sections, each one level deeper than the last
## Development      ← build/test/lint in ≤10 lines, link CONTRIBUTING if present
## License          ← one line

Rules

• Title/tone: playful tagline with one emoji is welcome; the body is sober.

First paragraph states plainly what the tool does and for whom.

• No feature walls. A list of >6 marketing bullets is a smell. Fold real

capabilities into the sections where they are demonstrated.

• No changelog-speak ("now supports", "new in 3.2", "coming soon"). The

README describes the present tense of the tool. Version-specific migration

notes live in the changelog or docs/.

• Length: aim ≤250 lines for tools/libraries, ≤350 for large surfaces.

Anything beyond that moves to docs/ with a link. Exhaustive command/flag

references belong in docs/ or the docs site, never in the README — a

summary table with links is fine.

• Progressive depth: a reader should be able to stop after any section and

have a working setup for that level of use.

• Screenshots/banners: keep existing project art. Apps and TUIs should show

one screenshot near the top. Compress; no >500 KB images.

• Docs sites win: when the repo has a docs site (fs-safe.io, gitcrawl.sh,

…), the README is a front door, not a mirror. Link, don't duplicate.

Badge row

Style: flat-square, always dynamic — a badge that can go stale is a bug.

Never hardcode versions into img.shields.io/badge/... URLs.

Order: CI · version · platform/runtime · license · extras (Homebrew, docs).

[![CI](https://img.shields.io/github/actions/workflow/status/OWNER/REPO/ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/OWNER/REPO/actions/workflows/ci.yml)

Per ecosystem, add what applies:

• npm: https://img.shields.io/npm/v/PKG?style=flat-square → npm page
• GitHub release (Go/Swift binaries): https://img.shields.io/github/v/release/OWNER/REPO?style=flat-square
• Runtime/platform: npm/node/v badge for npm packages; static

badge/platforms-... or badge/Swift-6.x-... is acceptable for facts that

only change with a commit (platforms, language version, min OS).

• License: https://img.shields.io/github/license/OWNER/REPO?style=flat-square
• Homebrew: static badge linking the tap, when a formula/cask exists.

Use the repo's actual workflow filename and default branch in the CI badge.

Verify every badge URL renders (HTTP 200 and not the shields "invalid" card)

before shipping.

Per-archetype templates

CLI tool (Go/TS binary) — Install (brew → go install/npm), Quick start

(3–6 commands with one-line comments showing a real session), Commands

(summary table linking docs/), Configuration, JSON/automation output if

agent-facing, Development, License.

npm library — Install, one core-usage sample that compiles, then one

section per capability tier (basic → options → advanced/edge), API reference

link (docs site or generated docs), Development, License.

Swift package — badges (Swift version, platforms, CI), SPM install snippet

(both Package.swift lines), Quick start compiling sample, capability

sections, platform notes, Development, License.

macOS app — screenshot first, Install (brew cask → direct download link),

what-it-does tour keyed to the screenshot, permissions/setup notes,

Development, License.

Web service / site — what it is + hosted URL, self-host/deploy path,

local development, architecture pointer, License.

Verification gates (all mandatory)

1. Every command in the README runs. Build the repo binary (or install the

package) and execute each quickstart/example command, or validate flags

against real --help output when execution needs credentials/hardware.

Fix the README, not the transcript.

1. Every code sample compiles/typechecks against the current API (a scratch

file in the repo's toolchain is enough).

1. Every relative link resolves to a file in the repo; every external link

returns non-404; every badge renders.

1. Version facts are dynamic or current: no hardcoded package versions,

stale minimums, or "coming soon" for shipped things. Check package.json/

go.mod/Package.swift for the real runtime floors.

1. Existing factual content that gets removed from the README must either

exist in docs/ already, be moved there in the same PR, or be genuinely

obsolete (state which in the PR body).