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:

• What is this? — one sentence a stranger understands.
• How do I use it? — smallest real install + a quickstart that *proves the pitch*.
• 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)

• 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.

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

file in the repo's toolchain is enough).

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

returns non-404; every badge renders.

• 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.

• 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).