write-readme

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>
    &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	
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>
  &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%.

<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%"> &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.

## 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:-}}"

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

## 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 instructions
• llms.txt = LLM discovery (spec)
• All other documents belong in docs/ organized into subdirectories: guides/, rfcs/, plans/, runbooks/, architecture/, etc.