/readme-standard

name: readme-standard
description: "House README standard: structure, badge row, tone, per-archetype templates, and verification gates for steipete/openclaw repos."

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`](https://github.com/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. 2. **Every code sample compiles/typechecks** against the current API (a scratch file in the repo's toolchain is enough). 3. **Every relative link resolves** to a file in the repo; every external link returns non-404; every badge renders. 4. **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. 5. 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).