showhow — Claude Code skill: explainer reels and setup
A skill for Claude Code builds narrated, animated explainer reels. It activates for requests to make a Showhow reel or edit a project in engine/reels/.
MIT ★ 78 updated 2026-10-30
npx skills add sirioberati/showhow --skill showhow -a claude-codeWhat showhow does
showhow helps create a vertical explainer reel with narration and visuals drawn in code. Scene motion follows spoken words, and the render goes through checks before delivery. The reel format is 1080x1920 at 60 fps.
The workflow covers the script, voice generation, captions and timing, scene planning, a draft preview, and the final render. Voice generation requires python3, ElevenLabs, and an ELEVENLABS_API_KEY stored in .env.local; commands run from engine/. The draft is shown before the final render.
Checks fail on issues such as abrupt scene changes, stalled motion, or audio levels outside the specified range. A reel with a FAIL result is not delivered. The plan check also flags caption blocks over 8 words and scene changes outside silence.
What it helps with
- build a narrated explainer reel from a script
- sync scene motion with spoken words
- check a render for abrupt cuts, stalled motion, and audio issues
- edit or re-render a project in
engine/reels/
Example prompts for the agent
- Make a Showhow reel explaining how browser caching works.
- Edit the scenes in
engine/reels/demo/and prepare a new draft. - Re-render the reel in
engine/reels/demo/and run the checks.
How to install showhow
1Skills CLI (Vercel)
npx skills add sirioberati/showhow --skill showhow -a claude-code2Manually: put the files in place
~/.claude/skills/skill/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/skill/
1Skills CLI (Vercel)
npx skills add sirioberati/showhow --skill showhow -a codex2Manually: put the files in place
.agents/skills/skill/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add sirioberati/showhow --skill showhow -a cursor2Manually: put the files in place
.cursor/skills/skill/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install sirioberati/showhow skill2Manually: put the files in place
.github/skills/skill/SKILL.md1Skills CLI (Vercel)
npx skills add sirioberati/showhow --skill showhow -a gemini-cli2Platform CLI
gemini skills install https://github.com/sirioberati/showhow --path skillManually: put the files in place
.devin/skills/skill/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about showhow
How do I install showhow in Claude Code?
Run npx skills add sirioberati/showhow --skill showhow -a claude-code. The skill file is placed at ~/.claude/skills/skill/SKILL.md.
What does showhow do?
It helps create narrated animated explainers, covering the script, voice, scenes, rendering, and render checks.
What does showhow need to generate voice audio?
Voice generation requires python3, ElevenLabs, and an ELEVENLABS_API_KEY in .env.local.
Source text
SKILL.md · MIT
---
name: showhow
description: Make a narrated, fully animated explainer reel (1080x1920, 60 fps) with Showhow, free version. A voice, every picture drawn in code on a canvas through a pinhole camera, every move on a spoken word, and checks that pass or fail every render. Use for "make a Showhow reel about X", or to edit or re-render a reel in engine/reels/.
---
# Showhow by Sirio, free version
A reel is a voice and a picture. The picture is drawn in code, frame by frame, on a canvas with a hand-written pinhole
camera. Every move starts on a word the voice says. There is no presenter and no cut.
## The order
1. **Script.** Write it, then get the person's approval before anything else. Plain spoken sentences, the first one is the
hook and says what the reel is about. Save it as `engine/reels/<slug>/script.txt`, a blank line between paragraphs.
2. **Voice.** `python3 scripts/voice.py <slug>` (ElevenLabs, the key in `.env.local`, the voice id in `reel.json`), then
`python3 scripts/tighten.py <slug>`, which puts every pause inside real silence so no word is ever cut.
To pick a voice: `python3 scripts/voice.py <slug> --audition id:label,id:label`.
3. **Caption and timing.** Write `caption.txt` (below), run `python3 scripts/align.py <slug>`, then
`python3 scripts/check.py plan <slug>` until it returns 0.
4. **Plan.** `plan.md`: the one or two worlds the reel happens in, which scenes carry on in the same world, and for each
scene its words, the real thing it shows and word -> what changes.
5. **Scenes.** One component per scene in `scenes/`, mapped by id in `scenes/index.tsx`. Look at half-size stills
(`node render.mjs <slug> --stills 1.2,3.4 --half`) at the word cues that change the picture.
6. **DRAFT.** `node draft.mjs <slug>`: the real drawn video at half size, stamped DRAFT. Show it before the final render.
7. **Render and check.** `node render.mjs <slug>`, then every check below. Nothing is delivered with a FAIL.
All commands run from `engine/`. The Express workflow in `workflow/` runs steps 2 to 7 with parallel builders, and the MCP
server in `mcp/` exposes each step as a tool.
## It must make sense three ways
- **Physical.** Gravity holds. Nothing floats, vanishes or appears from nowhere. Whatever loses its support falls the full
distance, starting slowly. Use real sizes and real gravity (9.81 m/s², which is 9.81/3600 m per frame² at 60 fps).
- **Story.** One chain of cause then effect, on objects already seen, that a stranger could retell from the pictures alone.
- **Visual.** One change at a time, where the eye already is. What the voice names is centred and whole. No label over a
number. Every new picture holds about 2 s before the camera leaves it.
## caption.txt
```
== hook | ground: dark opens a scene: its id (its key in scenes/index.tsx) and its ground (dark or light)
This *block* each line is one caption block, at most two lines on screen
is drawn with *code,* *word* marks the block's key word, which gets the selection box
and the only thing / holding it *up* " / " breaks the line there
@bottom / @top moves the caption slot, from the next block on
# a comment
```
The caption is the script. It is never transcribed from the voice. The word caption is off in renders by default; pass
`--caption` to show it.
## A scene
```tsx
import React from "react";
import { useScene, prog, ease } from "../../../src/engine";
export const Drop: React.FC = () => {
const { f, cue, ground } = useScene(); // f: the frame; cue("word"): the frame that word starts
const land = prog(f, cue("lands"), 24, ease.out); // 0 to 1 over 24 frames from "lands"
return <div style={{ position: "absolute", inset: 0, background: ground.bg }}>{/* draw here */}</div>;
};
```
Every value is a pure function of the frame, so any frame renders on its own. For a world in depth, draw on a
`<canvas width={1080} height={1920}>` in a `useLayoutEffect`, through the camera in `src/engine/camera.ts`:
- `project(cam, [x, y, z])` gives the screen point, its depth for sorting and its scale.
- `orbit(target, yaw, pitch, distance)` places the camera around a target.
- `spline(f, [[frame, value], ...])` joins keys on word cues with a smooth curve that never jumps and keeps moving through
the middle keys.
**One continuous world.** When two scenes happen in the same place, draw that world from the reel's frame in one shared
component, and use it in both scenes (see `reels/demo`). With `"handover": "continuous"` in `reel.json` the next scene takes
over on its first frame, so the picture never jumps. List those scenes as keep scenes for the motion check.
`src/engine/moves.ts` has the motion verbs: `prog`, `ease`, `arrive`, `leave`, `blurIn`, `blurOut`, `pop`, `typeOn`,
`countTo`, `draw`, `stagger`, `mix`. `theme.ts` holds every value a reel may override in `reel.json` under `"theme"`.
## The checks
Each prints PASS or FAIL with the reason and exits 1 on a FAIL. A check that could not run counts as a FAIL.
| Command | What fails |
|---|---|
| `check.py plan <slug>` | a caption block over 8 words, two key words in a block, a scene change outside silence (it also warns on type under 32 px) |
| `check.py render <slug> <mp4>` | nothing moving for over 1.2 s, bare ground during a scene change |
| `motion.py <mp4> --words reels/<slug>/words.json --keep a,b` | a move too fast to follow inside a world, a cut or snap, a near-freeze then a jump, a scene under 2 s |
| `joins.py <slug> <mp4> --sheet out.jpg` | a scene change where one frame swaps the picture; the sheet shows every change |
| `speed.py <mp4>` | the camera speed check on its own, for any clip |
| `loud.py <mp4> [--fix]` | sound away from -14 LUFS or peaks above -1.5 dBTP; `--fix` levels it, video untouched |
## Keys
Keys go in `.env.local` at the top of the repo (`ELEVENLABS_API_KEY=...`). Never ask for one in chat and never commit one.
© sirioberati · MIT · sirioberati/showhow