---
name: snapcode-readme
description: Write or improve a README (or docs landing page) with Snapcode-rendered code visuals — hero snippets, feature examples, and before/after diffs placed where they help most. Requires the snapcode base skill for render mechanics.
---

# Snapcode README

A recipe skill for writing READMEs that use Snapcode images well. It assumes the **`snapcode` base skill** is installed — that skill owns the mechanics of calling the CLI/MCP tool; this one owns *where images go and why*.

## Structure that works

A strong README answers, in order: what is this, why should I care, show me, how do I run it.

1. **Title + one-liner** — what the project does in a single sentence.
2. **Hero visual** — a Snapcode render of the 5–15 lines that best show the project's value. This replaces a wall of badges as the first thing under the intro.
3. **Features** — short bullets; one Snapcode visual per *non-obvious* feature, not per feature.
4. **Quickstart** — real install + run commands as copy-pasteable text (never an image — people copy these).
5. **Usage examples** — Snapcode renders for the 1–3 most common tasks, each with a one-line caption.
6. **API/config reference** — text tables and fenced code blocks, not images.

## Where each image goes

| Image | Location in README | Snapcode settings |
|---|---|---|
| Hero snippet | Immediately after the intro paragraph | `--title <entry-file>`, the project's most impressive short example, 5–15 lines |
| Feature visual | Inside the feature's subsection, after its one-line description | Trim with `--lines`, emphasize the key lines with `--highlight` |
| Before/after (migration, fix, refactor) | Under a "Before / After" heading | Use `--diff added:<lines>,removed:<lines>` on the *after* code so the change itself is visible |
| Error/diagnostic example | In troubleshooting sections | Plain theme, no background gimmicks — clarity first |

## Rules

- **Quickstart commands stay text.** Images are for code the reader admires; text is for code the reader runs. Never screenshot an install command.
- **Every image gets an alt text and a one-line caption** telling the reader what they're looking at.
- **Store images in `docs/assets/`** (or `.github/assets/` for README-only images) and reference with relative paths — absolute URLs break in forks.
- **Keep examples runnable.** The code in a visual should be copyable from the repo (an `examples/` file), not a hand-typed fragment that drifts out of date. Render from the real file with `--file examples/...`.
- **Regenerate, don't edit.** When the example code changes, re-run the render — never hand-edit the PNG.
- **Match theme to context**: dark themes (`github-dark`, `dracula`, `nord`) read best on GitHub's dark mode; if unsure, `github-dark` is the safe default.

## Workflow

1. Draft or read the example file (e.g. `examples/quickstart.ts`) — 5–15 lines that actually run.
2. Render it (base skill): `snapcode generate --file examples/quickstart.ts --theme github-dark --title quickstart.ts --out docs/assets/hero.png`
3. Place the markdown: `![Quickstart](docs/assets/hero.png)` with a caption line.
4. Repeat only for features that genuinely need a visual — a README with 2–4 well-placed images beats one with ten.