Index of every page on this site: llms.txt
All skills
openclaw avatar

/readme-standard

@0a5ba4b
by openclawopenclaw/agent-skills1.1k stars
126
Run it yourself

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

Use this Skill: https://skilld.dev/gh/openclaw/agent-skills/readme-standard

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈36 tokens for metadata: the name and description. ≈1.4k when used: this file.

Description uses 1.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈145 characters, or 1.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    This skill provides a standard for README documentation within the openclaw organization. It defines structure, tone, badge usage, and verification steps to ensure documentation accuracy and consistency. No security risks were identified.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: LOW · No issues

Signed by skilld at 0a5ba4b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 months ago

README badge

README badge for openclaw/agent-skills/readme-standard