# Readme Standard > House README standard: structure, badge row, tone, per-archetype templates, and verification gates for steipete/openclaw repos. - Skill: `openclaw/readme-standard` (Agent Skill) - Install (CLI): `npx skillmds@latest add openclaw/readme-standard` - Raw SKILL.md: https://api.skillmd.com/api/skills/openclaw/readme-standard/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: OpenClaw (https://skillmd.com/u/openclaw) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/openclaw/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`](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: ``` # — <1–2 sober sentences: what it is, who it is for. No adjectives doing the work nouns should do.> ## Install ← smallest path first (brew/npm/npx), alternatives after ## Quick start ← 60 seconds to first success; commands must actually run ## ← 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). ```markdown [![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).