write-readme git:20260712.ae7b7ceB

Immutable. This exact content never changes and is served at /api/v1/blob/7e1b57fb942863c3.

---
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:

```html
<p align="center">
  <h1 align="center">{Display Name}</h1>
  <p align="center">
    {One-line description}
    <br /><br />
    <a href="...releases">Download</a>
    &middot;
    <a href="...issues">Report Bug</a>
    &middot;
    <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 | `![CI](https://github.com/{owner}/{repo}/actions/workflows/ci.yml/badge.svg)` |
| License | always | `![License](https://img.shields.io/github/license/{owner}/{repo})` |
| Registry | published libraries only | crates.io / npm / PyPI / pkg.go.dev shield |
| Release | projects with downloadable binaries | `![Release](https://img.shields.io/github/v/release/{owner}/{repo})` |

Personal sites, curricula, and archives ship with CI + License only. Do not add badges that link to empty or placeholder resources.

```html
<p align="center">
  <a href="...ci.yml"><img src="...badge.svg" alt="CI"></a>
  &nbsp;
  <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%.

```html
<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.

```markdown
## 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):

```html
<p align="center">
  <img src="..." width="30%"> &nbsp; <img src="..." width="30%"> &nbsp; <img src="..." width="30%">
</p>
<p align="center"><em>Label 1 &middot; Label 2 &middot; 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.

```markdown
## 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:

```markdown
## 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:

```markdown
## 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/`:

```markdown
## 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:

```markdown
## 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`:

```markdown
## 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:

```markdown
## 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](https://github.com/urmzd/fsrc) markers to keep code examples in sync with actual source files. This prevents documentation drift.

```markdown
<!-- 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:

```sh
#!/usr/bin/env sh
set -eu

REPO="{owner}/{repo}"
INSTALL_DIR="${{INSTALL_DIR:-$HOME/.local/bin}}"
VERSION="${{VERSION:-}}"

# Detect platform
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

# Resolve version
if [ -z "$VERSION" ]; then
  VERSION=$(gh api "repos/$REPO/releases/latest" --jq '.tag_name')
fi

# Download and install
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}"

# PATH hint
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:

```markdown
## 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](https://llmstxt.org/) (see `create-llms-txt` skill for format).

## Documentation Philosophy

- **README.md** human-facing documentation; stays at root
- **[AGENTS.md](https://agents.md/)** AI-facing project context; stays at root
- CONTRIBUTING.md, LICENSE, CODEOWNERS = standard root files
- `skills/<name>/SKILL.md` = agent instructions
- `llms.txt` = LLM discovery ([spec](https://llmstxt.org/))
- **All other documents belong in `docs/`** organized into subdirectories: `guides/`, `rfcs/`, `plans/`, `runbooks/`, `architecture/`, etc.