| name | write-readme |
| description | Structures and writes a project README: centered header, badges, demo image, section order, install.sh one-liner, Quick Start, fsrc code embeds, and the Agent Skill section. Use when creating or updating any project's README.md. Do NOT use for AGENTS.md or the skills-vs-docs taxonomy -> use configure-ai (configure-ai owns AGENTS.md and the docs taxonomy; write-readme owns README structure). For llms.txt generation -> use create-llms-txt.
|
| allowed-tools | Read, Grep, Glob, Bash(git *), Edit, Write |
| metadata | {"title":"README Standards","category":"visual","order":1} |
README Standards
Centered Header Template
Every README starts with a centered header block:
<p align="center">
<h1 align="center">{Display Name}</h1>
<p align="center">
{One-line description}
<br /><br />
<a href="...releases">Download</a>
·
<a href="...issues">Report Bug</a>
·
<a href="{url}">{Third Link}</a>
</p>
</p>
- Link 1: "Install" for libraries (Go
go get, Python uv add), "Download" for binaries
- Link 2: "Report Bug" (always links to
/issues)
- Link 3: contextual Go Docs, GitHub Action, PyPI, Crates.io, Experiments, etc.
Badges
Centered, immediately below header. Use exactly the set that applies; no more, no less. Maximum four badges.
| Badge | When | Template |
|---|
| CI | always |  |
| License | always |  |
| Registry | published libraries only | crates.io / npm / PyPI / pkg.go.dev shield |
| Release | projects with downloadable binaries |  |
Personal sites, curricula, and archives ship with CI + License only. Do not add badges that link to empty or placeholder resources.
<p align="center">
<a href="...ci.yml"><img src="...badge.svg" alt="CI"></a>
<a href="LICENSE"><img src="...license.svg" alt="License"></a>
</p>
Demo Image
Position: immediately after badges, before any ## section. One hero image per README.
Source: showcase/ directory, always. Never assets/, doc/, or a repo-root image. The showcase/ name is pinned by style-brand.
Format: .gif for terminal recordings (teasr), .png for static screenshots, .svg only for vector diagrams.
Width: 80%.
<p align="center">
<img src="showcase/demo.gif" alt="Demo" width="80%">
</p>
Projects without a visual output (libraries with no CLI, curricula, archives) skip the demo. Do not synthesize a demo for a project that has nothing to show.
Table of Contents
READMEs ≥ 300 lines must include a ToC directly after the demo (or after the badges if there is no demo). Shorter READMEs skip it.
## Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- ...
Only list top-level ## sections. Do not nest ### headings in the ToC.
Output Gallery
For projects with multiple visual outputs (3-col, 30% width):
<p align="center">
<img src="..." width="30%"> <img src="..." width="30%"> <img src="..." width="30%">
</p>
<p align="center"><em>Label 1 · Label 2 · Label 3</em></p>
Prose Style
- No em-dashes. Do not use U+2014. Use a period, a colon, or bold indexing (
**Term**) instead. Em-dashes read as AI-generated and break the visual rhythm of terse documentation.
- No emojis unless the user explicitly requests them. This includes section headers, bullet prefixes, and callouts.
- Imperative voice in instructions (
Run the build not You can run the build).
- No trailing summaries ("In summary..." / "This means..."). If the point needs a summary, the prose above is too long.
Apply this rule to READMEs, AGENTS.md, CHANGELOG entries, and any markdown a subagent generates from this skill.
Standard Section Order
Header → Badges → Demo → (ToC if ≥300 lines) → Features → Installation (with Prerequisites subsection if applicable) → Quick Start → Examples → Usage / CLI Reference → Configuration → API → Architecture → Agent Skill → Related → License
Agent Skill is always the second-to-last section, directly before License. Move it there even in existing READMEs where it appears elsewhere.
Sections
Features
Bullet list of key capabilities. Keep it scannable; 3-8 items.
Installation
Every project needs an installation section. If the project requires a runtime, toolchain, or service beyond what the install command handles, open Installation with a Prerequisites subsection.
## Installation
### Prerequisites
| Requirement | Version |
|-------------|---------|
| {tool} | {version} |
| {tool} | {version} |
Include Prerequisites when: Neovim plugin needs a specific Neovim version, a library needs a specific compiler, a web app needs a node/pnpm version, a CLI needs an external binary to function. Skip it when a plain cargo install, npm i, or curl | sh is sufficient.
For CLI tools and binaries, include an install.sh one-liner:
## Installation
### Script (macOS / Linux)
\```sh
curl -fsSL https://raw.githubusercontent.com/{owner}/{repo}/main/install.sh | sh
\```
### Manual
Download a pre-built binary from the [releases page](https://github.com/{owner}/{repo}/releases/latest).
For libraries, show the package manager command:
| Language | Install Command |
|---|
| Rust | cargo add {crate} |
| Go | go get github.com/{owner}/{repo} |
| Python | uv add {package} |
| Node | npm install {package} |
Quick Start
Always "Quick Start" (never "Quickstart" or "Getting Started"). Show the minimal path from install to first result. Every code block should be runnable as-is.
CLI projects -- shell commands that produce visible output:
## Quick Start
\```sh
curl -fsSL https://raw.githubusercontent.com/{owner}/{repo}/main/install.sh | sh
{command} --help
{command} {typical-usage}
\```
Library projects -- install command followed by a minimal working code snippet. Use fsrc referencing an actual file in examples/:
## Quick Start
\```sh
{install-command}
\```
<!-- fsrc src="examples/basic/main.{ext}" fence="auto" -->
<!-- /fsrc -->
See [`examples/`](examples/) for more.
If the Quick Start code does not exist as a standalone file, create it first in examples/basic/ then embed it. This prevents documentation drift.
Examples
If the project has an examples/ directory, add a section linking to it:
## Examples
| Example | Description |
|---------|-------------|
| [`basic`](examples/basic/) | Minimal usage |
| [`{feature}`](examples/{feature}/) | {One-line description} |
See [`examples/`](examples/) for all runnable examples.
Architecture
For complex projects, add a brief architecture summary and link to docs/architecture.md:
## Architecture
Brief overview of how the system is structured.
See [docs/architecture.md](docs/architecture.md) for the full architecture guide.
Do NOT inline detailed architecture in the README; keep it in docs/architecture.md.
Agent Skill
Every repo with a skill includes:
## Agent Skill
This repo's conventions are available as portable agent skills in [`skills/`](skills/).
No Project Structure
READMEs must NOT include directory trees, file tables, or "Key Directories" sections. Project structure is discoverable via tree and ripgrep/ag. Writing it out is duplicative and goes stale. AGENTS.md handles structural context for AI agents.
fsrc for Code Examples
Use fsrc markers to keep code examples in sync with actual source files. This prevents documentation drift.
<!-- fsrc src="example.yml" fence="auto" -->
<!-- /fsrc -->
When fsrc runs (locally or in CI), it replaces the content between markers with the referenced file. Use this for:
- Workflow examples (
example.yml, ci.yml)
- Configuration snippets (
pyproject.toml, biome.json)
- Code samples that exist as actual files in the repo
Prefer fsrc over copy-pasting code into the README. If the code doesn't exist as a standalone file, create one in an examples/ directory and embed it.
install.sh Pattern
For CLI tools with cross-platform release binaries, include an install.sh at the repo root:
#!/usr/bin/env sh
set -eu
REPO="{owner}/{repo}"
INSTALL_DIR="${{INSTALL_DIR:-$HOME/.local/bin}}"
VERSION="${{VERSION:-}}"
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
case "$ARCH" in
x86_64|amd64) ARCH="amd64" ;;
aarch64|arm64) ARCH="arm64" ;;
*) echo "Unsupported architecture: $ARCH" >&2; exit 1 ;;
esac
if [ -z "$VERSION" ]; then
VERSION=$(gh api "repos/$REPO/releases/latest" --jq '.tag_name')
fi
BINARY="{binary-name}-${OS}-${ARCH}"
URL="https://github.com/$REPO/releases/download/$VERSION/$BINARY"
echo "Installing $BINARY ($VERSION) to $INSTALL_DIR..."
mkdir -p "$INSTALL_DIR"
curl -fsSL "$URL" -o "$INSTALL_DIR/{binary-name}"
chmod +x "$INSTALL_DIR/{binary-name}"
case ":$PATH:" in
*":$INSTALL_DIR:"*) ;;
*) echo "Add $INSTALL_DIR to your PATH: export PATH=\"$INSTALL_DIR:\$PATH\"" ;;
esac
echo "Installed {binary-name} $VERSION"
Adjust binary naming to match your release artifact convention (see scaffold-rust and scaffold-go for naming).
Documentation Links
When a project has docs beyond the README, link to them:
## Documentation
- [Architecture](docs/architecture.md)
- [Contributing](CONTRIBUTING.md)
- [API Reference](docs/api.md)
Only link docs that exist. Do not create placeholder links.
llms.txt
Every repo should have llms.txt at root per the llms.txt specification (see create-llms-txt skill for format).
Documentation Philosophy
- README.md human-facing documentation; stays at root
- AGENTS.md AI-facing project context; stays at root
- CONTRIBUTING.md, LICENSE, CODEOWNERS = standard root files
skills/<name>/SKILL.md = agent instructionsllms.txt = LLM discovery (spec)- All other documents belong in
docs/ organized into subdirectories: guides/, rfcs/, plans/, runbooks/, architecture/, etc.
