# Write Readme

> >

- **Type:** Skill
- **Install:** `agentstack add skill-urmzd-dotfiles-write-readme`
- **Verified:** Pending review
- **Seller:** [urmzd](https://agentstack.voostack.com/s/urmzd)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [urmzd](https://github.com/urmzd)
- **Source:** https://github.com/urmzd/dotfiles/tree/main/dot_agents/skills/write-readme

## Install

```sh
agentstack add skill-urmzd-dotfiles-write-readme
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# README Standards

## Centered Header Template

Every README starts with a centered header block:

```html

  {Display Name}
  
    {One-line description}
    
    Download
    ·
    Report Bug
    ·
    {Third Link}
  

```

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

```html

  
   
  

```

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

  

```

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

        

Label 1 · Label 2 · Label 3
```

## Prose Style

- **No em-dashes** (` — ` or `—`). 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}
\```

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

```

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [urmzd](https://github.com/urmzd)
- **Source:** [urmzd/dotfiles](https://github.com/urmzd/dotfiles)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-urmzd-dotfiles-write-readme
- Seller: https://agentstack.voostack.com/s/urmzd
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.