walkthrough-gif

The full skill.

Original instructions from the publisher’s SKILL.md

# Walkthrough GIF Skill

Generates a self-contained Node.js project that records a browser walkthrough and exports MP4 + GIF.

## When to use this skill vs. claude-in-chrome gif_creator

For a quick, one-off capture inside the user's live browser session (their profile, their open
tabs, already logged in), the `claude-in-chrome` `gif_creator` tool is far simpler — no project
scaffolding, no API keys. Reach for this skill when the user needs something gif_creator can't
give them: a **re-runnable/versionable script** (re-record after every UI change), **MP4 output**,
a **high-quality gifski GIF**, a **clean-profile recording** (no personal bookmarks/extensions in
frame), or **CI repeatability**.

## Architecture

```
Natural language description
        ↓
Claude generates TypeScript script
        ↓
Stagehand v3 (AI browser control) — Playwright attached over CDP
        ↓
Playwright recording context captures video (.webm)
        ↓
ffmpeg converts → .mp4
gifski converts frames → .gif
        ↓
Output: walkthrough.mp4 + walkthrough.gif + walkthrough.md
```

## Workflow

### Step 1: Gather Requirements

**Prerequisite — LLM API key:** Stagehand calls an LLM for every AI action. The user needs
`ANTHROPIC_API_KEY` (or the provider key matching the configured model, e.g. `OPENAI_API_KEY`)
available for `.env`. Confirm this upfront — without it the generated script cannot run.

Before generating any code, confirm:

1. **Target URL** — Where does the walkthrough start? (e.g., `https://app.example.com/login`)
2. **Flow description** — What steps should be demonstrated? (natural language is fine)
3. **Auth situation** — Is the page public, or does it need login? If login: will they hardcode creds in `.env`, use a pre-authenticated session/cookie export, or start from a logged-in state?
4. **Output format** — GIF only, MP4 only, or both? (default: both)
5. **Duration / pace** — Fast demo or deliberate step-by-step? (~1-2s pause between steps is default)
6. **Viewport** — Default is 1280×800. Narrower for mobile-style demos.

If the user gives a rich description upfront, infer what you can and ask only about gaps.

### Step 2: Generate the Project

Output a complete, runnable project at `./walkthrough-[name]/`:

```
walkthrough-[name]/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   └── walkthrough.ts      ← main script
└── scripts/
    └── convert.sh          ← ffmpeg + gifski conversion
```

Read `references/stagehand-patterns.md` for the Stagehand API and step translation patterns.
Read `references/output-pipeline.md` for the ffmpeg/gifski conversion commands and GIF tuning.

### Step 3: Translate Steps

Convert the user's natural language into `stagehand.act()` calls (v3: `act()` lives on the
stagehand instance and takes a plain string, with options like `variables` and `page`). See
`references/stagehand-patterns.md` for patterns and gotchas.

Key translation rules:
- Each logical UI action = one `stagehand.act("...", { page })` call with a clear English instruction
- Typed input goes through `variables` (`%name%` placeholders) — never inline secrets in the instruction string
- Add `page.waitForTimeout(1500)` between major steps for pacing (visible to viewer)
- Add `page.waitForLoadState('networkidle')` after navigations
- Never hardcode selectors — Stagehand figures those out from natural language instructions
- For flows that have auth: use `.env` for credentials, never hardcode

### Step 4: Recording Strategy

Always use **Playwright video recording** as the primary capture method:
- Stagehand v3 has no built-in recording — connect Playwright to Stagehand's browser via
  `chromium.connectOverCDP({ wsEndpoint: stagehand.connectURL() })`, create a context with the
  `recordVideo` option, and drive that context's page (see `references/stagehand-patterns.md`)
- Record full session as `.webm` via that recording context
- Do NOT try to stitch individual screenshots into GIF directly — video → frames → GIF is higher quality
- After script completes, run `convert.sh` to produce MP4 and GIF

**Never make GIF the primary artifact.** MP4 is always produced first. GIF is derived from it. GIFs are large and low quality for anything over 15 seconds — warn the user and suggest keeping walkthroughs under 60s.

### Step 5: Click/Cursor Overlays (Optional but recommended)

Inject a click-highlight overlay via `page.addInitScript()` before the walkthrough starts. See `references/stagehand-patterns.md` → "Click Overlay" section for the snippet.

This adds a subtle ripple animation at each click point — makes walkthroughs dramatically more readable without post-processing.

### Step 6: Output

After generation, produce:
1. The project directory (all files)
2. A brief setup checklist in the conversation:

```
## Setup
npm install
npx playwright install chromium
cp .env.example .env  # fill in ANTHROPIC_API_KEY + any credentials

## Run
npx tsx src/walkthrough.ts

## Convert to GIF + MP4
bash scripts/convert.sh
```

Also tell the user what to expect: approximate duration, viewport size, output filenames.

**Offer to run it:** Claude Code can execute the whole pipeline itself — `npm install`,
`npx playwright install chromium`, run the walkthrough script, then `bash scripts/convert.sh` —
if the user agrees (they still need to provide the `.env` values). When running it yourself,
verify the output before declaring success: `ffprobe` the MP4 for a sane duration and check the
GIF/MP4 file sizes are non-trivial (`convert.sh` prints these in its verification tail).

---

## Warnings / Bail Conditions

Tell the user upfront if any of these apply:

| Condition | Guidance |
|---|---|
| Page requires login with MFA/SSO | Script can't handle this automatically — user must export cookies from a logged-in browser session |
| CAPTCHA on target page | Playwright will stall — use a demo/sandbox environment instead |
| Heavy animations / infinite scrollers | Recording will capture them, but GIF conversion will be large — suggest clipping |
| Flow is >90 seconds | Recommend MP4 only; GIF will be unusably large |
| Page content is randomized/dynamic | Stagehand handles visual targeting, but warn that reruns may look different |

---

## Output Naming Convention

```
walkthrough-[slug]/
  output/
    walkthrough.webm     ← raw Playwright recording
    walkthrough.mp4      ← converted (H.264, web-safe)
    walkthrough.gif      ← gifski output, max 800px wide
    walkthrough.md       ← step-by-step annotation (auto-generated)
```

The `.md` file lists each `act()` call as a numbered step with timestamps — useful for embedding as a caption alongside the GIF.

---

## Reference Files

- `references/stagehand-patterns.md` — Stagehand API, step translation, click overlay snippet, auth patterns
- `references/output-pipeline.md` — ffmpeg commands, gifski flags, GIF optimization, troubleshooting