{One-line description}
Download
·
Report Bug
·
{Third Link}
Label 1 · Label 2 · Label 3
``` ## 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 → Development → Documentation → Agent Skill → 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} \``` 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. ``` ### No Architecture or Ecosystem Sections Every README sells its own project as if it were the only one. A reader should be able to install, run and ship with it without knowing it belongs to a larger stack. - No `## Architecture`, `## Where this sits`, `## Composition` (as a stack map), `## Related` or `## Ecosystem` sections. - No layer diagrams or "X is layer N of M" framing. No tables of which sibling project owns which concern. - No internal package tours (`pkg/foo does...`). That belongs in AGENTS.md. - Mention a sibling project only where the reader must act on it: an install requirement, an import in Quick Start, or a dependency the user configures. - Link architecture, design and ecosystem docs from **Documentation** as one line each. Do not summarize them. - Content that tells the reader how to configure or extend the project stays, under **Configuration**, **Usage** or **API**, written as what the reader does, not how the system is layered. ### 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 ``` 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 - `skills/