← All Skills

snappy-walkthrough

v1.0.0
19 files, 97.9 KB ~3,236 words · 13 min read Updated 2026-09-09

snappy-walkthrough skill

The card OpenAPI 3.1 ↗
42 of 49 checks pass
What it can do
annotate out-dirwrite-reversible
capture recipewrite-reversible
gates out-dirread
lesson out-dirread
run recipewrite-reversible
statusread
What does not pass yet
$ npx snappy-skills install snappy-walkthrough
zip ↓
File Tree
├── AGENTS.md ├── SKILL.md ├── api.ts ├── contract-gates.md ├── faces/ │ ├── components/ │ │ ├── walkthrough-faces.css │ │ └── walkthrough-faces.tsx │ ├── family.tsx │ └── fixtures/ │ └── walkthrough-steps.json ├── out/ │ └── smoke-test/ │ └── manual/ │ ├── gates.log │ ├── lesson.md │ ├── recipe.json │ ├── step-01.meta.json │ ├── step-01.overlay.svg │ ├── step-01.png │ ├── step-01.raw.png │ └── step-01.svg ├── recipes/ │ └── claude-code-first-session.json ├── refusals.test.ts └── steps-face.test.ts
Documents
AGENTS.md

snappy-walkthrough -- Agent Loader#

Capture step-by-step walkthroughs (Claude Code setup, skill install, MCP

wiring) as annotated PNG sequences + markdown lesson blocks. Recipe-driven.

The setpoint for "premium" lives in contract-gates.md -- every hand

review tightens it. The skill does NOT auto-tune.

Operating principle#

One recipe, one pipeline, one gate file. Recipes declare steps.

Each step has a source (where the image comes from) and annotations (boxes,

arrows, callouts, pins) in pixel coordinates. The pipeline is

capture -> annotate -> runGates -> buildLessonBlock. The gate file is the

memory of quality across runs.

When you review output and spot a defect: add a rule to

contract-gates.md, wire it in api.ts's GATES array, re-run. That

defect now can't happen again silently.

API module#

typescriptimport {
  loadWalkthroughRecipe,
  runRecipe,
  captureStep,
  annotateStep,
  runGates,
  buildLessonBlock,
} from "../snappy-walkthrough/api.ts";
Function What it does
loadWalkthroughRecipe(path) Parse JSON recipe, validate required fields, return Recipe
runRecipe(recipe) Full pipeline: capture -> annotate -> gates -> lesson. Returns output dir
captureStep(step, outDir) Dispatch to source handler; writes raw PNG + returns CaptureResult
annotateStep(step, capture) Write SVG overlay + composited PNG + meta.json
runGates(outDir) Read meta.json files, evaluate GATES array, write gates.log
buildLessonBlock(outDir, recipe?) Emit lesson.md ready for snappy-course

CLI:

bashnpx tsx ~/.claude/skills/snappy-walkthrough/api.ts run recipes/claude-code-first-session.json
npx tsx ~/.claude/skills/snappy-walkthrough/api.ts capture recipes/<name>.json
npx tsx ~/.claude/skills/snappy-walkthrough/api.ts annotate out/<recipe>/<stamp>
npx tsx ~/.claude/skills/snappy-walkthrough/api.ts gates out/<recipe>/<stamp>
npx tsx ~/.claude/skills/snappy-walkthrough/api.ts lesson out/<recipe>/<stamp>

Sources (v0 wired, v1+ planned)#

Source Status How
macos-window WIRED (v0) peekaboo image --app or screencapture -l
browser v1 planned delegates to snappy-browse (agent-browser)
file-render v1 planned silicon CLI for code->PNG
terminal-exec v1 planned run command, pipe stdout through silicon

The skill throws a clear "Source X not wired in v0" error if a recipe

uses an unwired source. That is a boundary failure, not a silent pass.

Interactive capture flow (important)#

When wait_for_enter: true, after you press ENTER the skill sleeps 3 seconds before capturing. Use that window to CMD+TAB or bring the target window to the front. This exists because the controller (Claude Code in Terminal.app) and the demo target (another Terminal.app window) share an app -- peekaboo's "frontmost of Terminal" will pick whichever window you touched most recently. The 3-second delay lets you move focus after committing the ENTER.

If the controller and target are in different apps (e.g. Claude Code in iTerm2 driving a demo in Terminal.app), peekaboo targets by --app cleanly and the delay is still harmless.

macos-window resolution#

peekaboo (preferred) takes an app name directly:

bashpeekaboo image --app "Terminal" --path /tmp/step.png

Fallback via screencapture -l <id> requires a CGWindowID. The skill

resolves it from window_title via AppleScript at capture time:

bashosascript -e 'id of window 1 of application "Terminal"'

Set window_title in the recipe -- the skill picks the right primitive.

Annotations#

All four kinds use image-pixel coordinates. Origin is top-left.

Kind Fields Renders as
box box: [x, y, w, h] Rounded outline (stroke width 4)
arrow from: [x, y], to: [x, y] Line with filled arrowhead
callout at: [x, y], text: "..." Rounded white bubble w/ colored border
pin at: [x, y], number? Filled circle w/ white number

Optional color: "#hex" on any annotation; default is snappy primary orange.

The annotate layer writes:

  • step-NN.svg -- overlay SVG containing the base image + annotation shapes
  • step-NN.overlay.svg -- annotations only, used for ImageMagick compositing
  • step-NN.png -- flat composited PNG (falls back to raw if ImageMagick missing)
  • step-NN.meta.json -- step definition, dimensions, timestamp

Brew deps: brew install imagemagick peekaboo (both optional -- skill

degrades to SVG-only + screencapture fallback).

Contract gates (the PID setpoint)#

contract-gates.md holds the rubric. api.ts GATES array implements

each rule. v0 rules:

Rule ID What
step-ids-monotonic Step IDs unique and sorted
caption-length Captions <=12 words
annotation-in-bounds All coordinates inside the image
png-exists Every step produced a PNG
banned-phrases No "let's/simply/just/easily/seamlessly"

To add a rule: review a run, identify a defect, add an object to

GATES in api.ts, document it in contract-gates.md, re-run. Human

drives the tune -- the skill is the enforcer.

Output layout#

out/<recipe-name>/<YYYY-MM-DD-HH-MM-SS>/
  recipe.json           # copy of the recipe run
  step-01.raw.png       # unannotated capture
  step-01.png           # composited (ImageMagick)
  step-01.svg           # overlay with base image (editable)
  step-01.overlay.svg   # overlay only (used for compositing)
  step-01.meta.json     # step + dims + capturedAt
  ...
  lesson.md             # ready for snappy-course
  gates.log             # PASS/FAIL lines; this is the certificate

gates.log is the verification certificate for the run -- produced by a

fresh filesystem read after capture + annotate finish. Actor (capture) is

not auditor (gates).

Common operations#

First run on a new machine:

bashbrew install imagemagick peekaboo
cd ~/.claude/skills/snappy-walkthrough
npx tsx api.ts run recipes/claude-code-first-session.json
# ENTER to capture each step when Terminal.app is in the right state

Iterate on coordinates after a first capture: edit the recipe JSON, then

re-run only annotate + gates + lesson:

bashnpx tsx api.ts annotate out/<recipe>/<stamp>
npx tsx api.ts gates out/<recipe>/<stamp>
npx tsx api.ts lesson out/<recipe>/<stamp>

This reuses the raw PNGs -- no re-capture needed.

Review the gate report:

bashcat out/<recipe>/<stamp>/gates.log

Any FAIL lines are defects the skill wants you to address before this run

counts as shippable.

Used by#

Nothing in the collection names this skill.

<!-- SNAPPY-CONTRACT-VERBS-START -->

Contract verbs#

Generated from api.ts HAND_CONTRACT. Do not hand-edit this block.

Verb Contract arguments Effect First call
annotate out-dir write-reversible npx tsx ~/.claude/skills/snappy-walkthrough/api.ts annotate <out-dir>
capture recipe write-reversible npx tsx ~/.claude/skills/snappy-walkthrough/api.ts capture <recipe>
gates out-dir read npx tsx ~/.claude/skills/snappy-walkthrough/api.ts gates <out-dir>
lesson out-dir read npx tsx ~/.claude/skills/snappy-walkthrough/api.ts lesson <out-dir>
run recipe write-reversible npx tsx ~/.claude/skills/snappy-walkthrough/api.ts run <recipe>
status — read npx tsx ~/.claude/skills/snappy-walkthrough/api.ts status

Show the result#

When an answer carries face_hint, show it with one snappy_present(<answer>) call.

See /snappy-faces for face selection. Human-facing images must crop to the

element, render at 2x on Retina, and fill the destination channel instead of

placing a small card in a full-page screenshot.

<!-- SNAPPY-CONTRACT-VERBS-END -->

Self-correcting loader (PID feedback)#

The system spec lives at ~/.claude/skills/snappy-settings/skill-spec.md. It defines the entire Snappy operating system. You enforce it.

Before you finish, do two things:#

1. Fix gaps (P -- proportional). MANDATORY. If this AGENTS.md didn't cover your case -- if you had to read another file, run a command not documented here, work around a wrong selector, or discover a quirk -- you MUST attempt an Edit before you can log.

  • Default action: edit this AGENTS.md. Surgical. Add the missing line, table row, or code example where it belongs. No restructuring.
  • Only LOGGED is allowed when: the fix needs >10 lines, spans multiple files, or requires a structural rewrite (in which case the drain-skill-regen.sh queue picks it up).
  • "I didn't have time" / "it's minor" / "the next agent will figure it out" are NOT valid reasons to skip the Edit. The whole point of this loop is that minor gaps compound.
  • The goal: the next agent never has to leave the loader.

2. Validate structure. Check this skill against the spec:

  • api.ts exists with typed exports, CLI mode, import { env } from "../snappy-settings/load.ts" (if credentials are needed)
  • api.ts calls APIs directly (no Xano proxy, unless this skill IS a Xano DB skill)
  • AGENTS.md has API module section with import + function table + CLI
  • No shell fallback paths, no hardcoded tokens anywhere
  • Every action row carries a certificate: block (premises / action / trace / evidence / conclusion). Same-session toasts are NOT evidence -- must be a fresh independent read. For this skill the certificate is gates.log, written after capture+annotate by a fresh filesystem read.
  • DRY: before you add a new function or new skill, run ~/.claude/skills/snappy-settings/scripts/dry-check.sh <name-or-keyword>. If it matches an existing skill, extend that one instead.
  • If any check fails -> fix it or log it

2b. If you just reported an action as successful, verify your certificate. You may not claim PASS unless the evidence: line is a fresh independent read. If your evidence is a toast, a return value, or a same-session DOM read, downgrade the claim to INCONCLUSIVE and log to ~/.claude/logs/verification-gaps.log.

3. Log always.

bashecho "[$(date -u +%FT%TZ)] snappy-walkthrough: <what was missing or fixed> [FIXED|LOGGED]" >> ~/.claude/logs/agents-md-feedback.log

FIXED = you patched it. LOGGED = too large for inline fix, queued for drain-skill-regen.sh.

Do not skip this. Every agent run must leave the system better than it found it.

Show produced work with snappy-faces: call draw for image channels or lang for MCP Apps.

<!-- SKILL-INDEX-START -->

[snappy-walkthrough Index]|root: ~/.claude/skills/snappy-walkthrough|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md,contract-gates.md}|out:{smoke-test/manual/lesson.md}

<!-- SKILL-INDEX-END -->

---
name: snappy-walkthrough
role: Recipe-driven annotated tutorial capture with contract-gate PID loop
loaded-by: PreToolUse hook (auto-injected when "snappy-walkthrough" is mentioned)
---

# snappy-walkthrough -- Agent Loader

Capture step-by-step walkthroughs (Claude Code setup, skill install, MCP
wiring) as annotated PNG sequences + markdown lesson blocks. Recipe-driven.
The setpoint for "premium" lives in `contract-gates.md` -- every hand
review tightens it. The skill does NOT auto-tune.

## Operating principle

**One recipe, one pipeline, one gate file.** Recipes declare steps.
Each step has a source (where the image comes from) and annotations (boxes,
arrows, callouts, pins) in pixel coordinates. The pipeline is
`capture -> annotate -> runGates -> buildLessonBlock`. The gate file is the
memory of quality across runs.

When you review output and spot a defect: add a rule to
`contract-gates.md`, wire it in `api.ts`'s `GATES` array, re-run. That
defect now can't happen again silently.

## API module

```typescript
import {
  loadWalkthroughRecipe,
  runRecipe,
  captureStep,
  annotateStep,
  runGates,
  buildLessonBlock,
} from "../snappy-walkthrough/api.ts";
```

| Function | What it does |
|----------|-------------|
| `loadWalkthroughRecipe(path)` | Parse JSON recipe, validate required fields, return Recipe |
| `runRecipe(recipe)` | Full pipeline: capture -> annotate -> gates -> lesson. Returns output dir |
| `captureStep(step, outDir)` | Dispatch to source handler; writes raw PNG + returns CaptureResult |
| `annotateStep(step, capture)` | Write SVG overlay + composited PNG + meta.json |
| `runGates(outDir)` | Read meta.json files, evaluate GATES array, write `gates.log` |
| `buildLessonBlock(outDir, recipe?)` | Emit `lesson.md` ready for snappy-course |

CLI:

```bash
npx tsx ~/.claude/skills/snappy-walkthrough/api.ts run recipes/claude-code-first-session.json
npx tsx ~/.claude/skills/snappy-walkthrough/api.ts capture recipes/<name>.json
npx tsx ~/.claude/skills/snappy-walkthrough/api.ts annotate out/<recipe>/<stamp>
npx tsx ~/.claude/skills/snappy-walkthrough/api.ts gates out/<recipe>/<stamp>
npx tsx ~/.claude/skills/snappy-walkthrough/api.ts lesson out/<recipe>/<stamp>
```

## Sources (v0 wired, v1+ planned)

| Source         | Status      | How                                        |
|----------------|-------------|--------------------------------------------|
| `macos-window` | WIRED (v0)  | `peekaboo image --app` or `screencapture -l` |
| `browser`      | v1 planned  | delegates to `snappy-browse` (agent-browser) |
| `file-render`  | v1 planned  | `silicon` CLI for code->PNG               |
| `terminal-exec`| v1 planned  | run command, pipe stdout through silicon  |

The skill throws a clear `"Source X not wired in v0"` error if a recipe
uses an unwired source. That is a boundary failure, not a silent pass.

### Interactive capture flow (important)

When `wait_for_enter: true`, after you press ENTER the skill **sleeps 3 seconds before capturing**. Use that window to CMD+TAB or bring the target window to the front. This exists because the controller (Claude Code in Terminal.app) and the demo target (another Terminal.app window) share an app -- peekaboo's "frontmost of Terminal" will pick whichever window you touched most recently. The 3-second delay lets you move focus after committing the ENTER.

If the controller and target are in different apps (e.g. Claude Code in iTerm2 driving a demo in Terminal.app), peekaboo targets by `--app` cleanly and the delay is still harmless.

### macos-window resolution

`peekaboo` (preferred) takes an app name directly:

```bash
peekaboo image --app "Terminal" --path /tmp/step.png
```

Fallback via `screencapture -l <id>` requires a CGWindowID. The skill
resolves it from `window_title` via AppleScript at capture time:

```bash
osascript -e 'id of window 1 of application "Terminal"'
```

Set `window_title` in the recipe -- the skill picks the right primitive.

## Annotations

All four kinds use image-pixel coordinates. Origin is top-left.

| Kind | Fields | Renders as |
|------|--------|-----------|
| `box` | `box: [x, y, w, h]` | Rounded outline (stroke width 4) |
| `arrow` | `from: [x, y]`, `to: [x, y]` | Line with filled arrowhead |
| `callout` | `at: [x, y]`, `text: "..."` | Rounded white bubble w/ colored border |
| `pin` | `at: [x, y]`, `number?` | Filled circle w/ white number |

Optional `color: "#hex"` on any annotation; default is snappy primary orange.

The annotate layer writes:
- `step-NN.svg` -- overlay SVG containing the base image + annotation shapes
- `step-NN.overlay.svg` -- annotations only, used for ImageMagick compositing
- `step-NN.png` -- flat composited PNG (falls back to raw if ImageMagick missing)
- `step-NN.meta.json` -- step definition, dimensions, timestamp

Brew deps: `brew install imagemagick peekaboo` (both optional -- skill
degrades to SVG-only + screencapture fallback).

## Contract gates (the PID setpoint)

`contract-gates.md` holds the rubric. `api.ts` `GATES` array implements
each rule. v0 rules:

| Rule ID                | What |
|------------------------|------|
| `step-ids-monotonic`   | Step IDs unique and sorted |
| `caption-length`       | Captions <=12 words |
| `annotation-in-bounds` | All coordinates inside the image |
| `png-exists`           | Every step produced a PNG |
| `banned-phrases`       | No "let's/simply/just/easily/seamlessly" |

**To add a rule**: review a run, identify a defect, add an object to
`GATES` in `api.ts`, document it in `contract-gates.md`, re-run. Human
drives the tune -- the skill is the enforcer.

## Output layout

```
out/<recipe-name>/<YYYY-MM-DD-HH-MM-SS>/
  recipe.json           # copy of the recipe run
  step-01.raw.png       # unannotated capture
  step-01.png           # composited (ImageMagick)
  step-01.svg           # overlay with base image (editable)
  step-01.overlay.svg   # overlay only (used for compositing)
  step-01.meta.json     # step + dims + capturedAt
  ...
  lesson.md             # ready for snappy-course
  gates.log             # PASS/FAIL lines; this is the certificate
```

`gates.log` is the verification certificate for the run -- produced by a
fresh filesystem read after capture + annotate finish. Actor (capture) is
not auditor (gates).

## Common operations

**First run on a new machine:**

```bash
brew install imagemagick peekaboo
cd ~/.claude/skills/snappy-walkthrough
npx tsx api.ts run recipes/claude-code-first-session.json
# ENTER to capture each step when Terminal.app is in the right state
```

**Iterate on coordinates after a first capture**: edit the recipe JSON, then
re-run only annotate + gates + lesson:

```bash
npx tsx api.ts annotate out/<recipe>/<stamp>
npx tsx api.ts gates out/<recipe>/<stamp>
npx tsx api.ts lesson out/<recipe>/<stamp>
```

This reuses the raw PNGs -- no re-capture needed.

**Review the gate report:**

```bash
cat out/<recipe>/<stamp>/gates.log
```

Any FAIL lines are defects the skill wants you to address before this run
counts as shippable.

## Used by

Nothing in the collection names this skill.

<!-- SNAPPY-CONTRACT-VERBS-START -->
## Contract verbs

Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.

| Verb | Contract arguments | Effect | First call |
|---|---|---|---|
| `annotate` | `out-dir` | `write-reversible` | `npx tsx ~/.claude/skills/snappy-walkthrough/api.ts annotate <out-dir>` |
| `capture` | `recipe` | `write-reversible` | `npx tsx ~/.claude/skills/snappy-walkthrough/api.ts capture <recipe>` |
| `gates` | `out-dir` | `read` | `npx tsx ~/.claude/skills/snappy-walkthrough/api.ts gates <out-dir>` |
| `lesson` | `out-dir` | `read` | `npx tsx ~/.claude/skills/snappy-walkthrough/api.ts lesson <out-dir>` |
| `run` | `recipe` | `write-reversible` | `npx tsx ~/.claude/skills/snappy-walkthrough/api.ts run <recipe>` |
| `status` | — | `read` | `npx tsx ~/.claude/skills/snappy-walkthrough/api.ts status` |

## Show the result

When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.
See `/snappy-faces` for face selection. Human-facing images must crop to the
element, render at 2x on Retina, and fill the destination channel instead of
placing a small card in a full-page screenshot.
<!-- SNAPPY-CONTRACT-VERBS-END -->

---

## Self-correcting loader (PID feedback)

The system spec lives at `~/.claude/skills/snappy-settings/skill-spec.md`. It defines the entire Snappy operating system. You enforce it.

### Before you finish, do two things:

**1. Fix gaps (P -- proportional). MANDATORY.** If this AGENTS.md didn't cover your case -- if you had to read another file, run a command not documented here, work around a wrong selector, or discover a quirk -- you MUST attempt an `Edit` before you can log.

- **Default action: edit this AGENTS.md.** Surgical. Add the missing line, table row, or code example where it belongs. No restructuring.
- **Only LOGGED is allowed when:** the fix needs >10 lines, spans multiple files, or requires a structural rewrite (in which case the drain-skill-regen.sh queue picks it up).
- "I didn't have time" / "it's minor" / "the next agent will figure it out" are NOT valid reasons to skip the Edit. The whole point of this loop is that minor gaps compound.
- The goal: the next agent never has to leave the loader.

**2. Validate structure.** Check this skill against the spec:
- `api.ts` exists with typed exports, CLI mode, `import { env } from "../snappy-settings/load.ts"` (if credentials are needed)
- `api.ts` calls APIs directly (no Xano proxy, unless this skill IS a Xano DB skill)
- `AGENTS.md` has API module section with import + function table + CLI
- No shell fallback paths, no hardcoded tokens anywhere
- **Every action row carries a `certificate:` block** (premises / action / trace / evidence / conclusion). Same-session toasts are NOT evidence -- must be a fresh independent read. For this skill the certificate is `gates.log`, written after capture+annotate by a fresh filesystem read.
- **DRY:** before you add a new function or new skill, run `~/.claude/skills/snappy-settings/scripts/dry-check.sh <name-or-keyword>`. If it matches an existing skill, extend that one instead.
- If any check fails -> fix it or log it

**2b. If you just reported an action as successful, verify your certificate.** You may not claim PASS unless the `evidence:` line is a fresh independent read. If your evidence is a toast, a return value, or a same-session DOM read, downgrade the claim to INCONCLUSIVE and log to `~/.claude/logs/verification-gaps.log`.

**3. Log always.**

```bash
echo "[$(date -u +%FT%TZ)] snappy-walkthrough: <what was missing or fixed> [FIXED|LOGGED]" >> ~/.claude/logs/agents-md-feedback.log
```

`FIXED` = you patched it. `LOGGED` = too large for inline fix, queued for drain-skill-regen.sh.

**Do not skip this.** Every agent run must leave the system better than it found it.


Show produced work with `snappy-faces`: call `draw` for image channels or `lang` for MCP Apps.

<!-- SKILL-INDEX-START -->
[snappy-walkthrough Index]|root: ~/.claude/skills/snappy-walkthrough|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md,contract-gates.md}|out:{smoke-test/manual/lesson.md}
<!-- SKILL-INDEX-END -->
Enter = next · Esc = close

Keyboard Shortcuts

Search in document⌘K
Focus search/
Previous file tab←
Next file tab→
Close overlayEsc
Show shortcuts?