papercut-explainer
Make short vertical explainer reels that look like layered construction paper, with Claude Code doing the work.
The bundled example reel (examples/hello-reel), rendered from this repo. Silent placeholder voice, real captions, camera and cuts.
This repo is two things that work together:
- Nine Claude Code skills that run the whole pipeline: strategy, hook, script, storyboard, voice, build, QA, and an installer. Ask for a reel, or run one stage on its own.
- A Remotion library the skills build on: a paper-cut component kit, 24 backdrops, 17 camera moves, 10 scene transitions, film-look layers, 79 sound effects and 8 music beds, plus the scripts that tie them into an episode.
You describe the video ("explain this repo in 25 seconds"). The skills research it, write a script on a fixed spoken spine, plan every camera move and cut, make or fake the voiceover, and build the scenes in Remotion. You review stills and the final cut.
Contents
What is in the box · Install · Use it · Examples · How the workflow runs · Voice · Customising · Requirements · Cost · Troubleshooting · Limits · Licence
What is in the box
| Skills | papercut-explainer (router), papercut-setup, papercut-strategy, papercut-hook, papercut-script, papercut-storyboard, papercut-voice, papercut-build, papercut-qa |
| Subagent | papercut-scene, a scene builder with only file and shell tools, so parallel scene agents start small |
| Backdrops | 24 paper-diorama sets at 1080×1920 with measured floor lines (sheet) |
| Camera | OrbitCamera + Depth, SnapZoom, Crane, CrabTrack, DollyZoom, RackFocus, ForegroundPass, PullBack, FreezeFrame, PovMask, TimeRamp, DutchTilt, TiltShift, FocusPulse, FocusHunt, Handheld, CameraPush |
| Cuts | whip, zoomThrough, pageTurn, tearAway, tapePull, stampCut, infiniteZoom, popUpBook, keyhole, burnAway, chained with CutSeries |
| Film look | gate weave and flicker, moving felt fibre, lens dirt, lamp flicker, halftone, graph paper |
| Overlays | taped headline banner, word-by-word torn caption tags, hook title, real-screenshot proof card with marker circles |
| Kit | 188 exports in library/papercut/kit: paper primitives (Paper, Slab, Disc, Pill, Card), a base critter with accessories, prop sets, rough UI rebuilds, a comment-keyword CTA scene |
| Sound | 79 synthesised SFX and 8 music beds, picked by name, rendered with Web Audio (no audio files to license) |
| Tools | scaffold, cue sheets, cached renders, QA contact sheets, catalog generator, placeholder narration, optional local TTS setup |
Each camera move and cut, with its props and when to use it, is in library/papercut/CATALOG.md (sections paper/camera.tsx and paper/transitions.tsx).
Install
You need Node 20+, npm, ffmpeg, rsync and Python 3. Claude Code is the front end.
With npx skills (skills only, fastest):
npx skills add 0xS4N4TG/papercut-explainer
This installs the nine skills into your agents' skill folders (Claude Code and the others the CLI supports). It does not fetch the Remotion library or the scripts. Open Claude Code and say "set up papercut-explainer": papercut-setup clones the repo, asks how much you want (Minimal, Standard, Full) and installs it. Add -g for a user-wide install, --skill papercut-hook to take one skill.
With git (everything, including the library):
git clone https://github.com/0xS4N4TG/papercut-explainer
cd papercut-explainer
./install.sh
The installer asks how much you want to set up and does only that.
| Mode | What you get | Cost |
|---|---|---|
| 1. Minimal | The skills, the scene-builder subagent and the config file. Strategy, hook, script, storyboard and style prompts work. Nothing renders. | seconds |
| 2. Standard | Minimal, plus: a dependency check, the Remotion agent skills, a Python venv for QA sheets, and a self-test that scaffolds a project, typechecks it and renders a still. You can build and render full reels with a placeholder voice (silent, or macOS say). |
about 0.7 GB (the first project's node_modules) and a few minutes |
| 3. Full | Standard, plus local voiceover: a Qwen3-TTS venv, the model download, an ASR backend for word timings, and a smoke test that generates a line and checks the audio. | 4–6 GB more (1.5 GB venv plus a 2.3 or 4.2 GB model) |
| 4. Custom | Pick any of: skills, deps, remotion-skills, pytools, tts, verify. |
varies |
You can move up later: ./install.sh --mode custom --components deps,remotion-skills,pytools,verify.
Non-interactive and scoped installs:
./install.sh --mode standard --yes # no questions
./install.sh --mode full --tts-model 0.6B --yes # lighter voice model (2.3 GB)
./install.sh --mode minimal --project ~/code/my-videos # skills for one project only
./install.sh --mode minimal --copy # copy skills instead of symlinking
./install.sh --dry-run --mode full # print what would happen
./install.sh --doctor # check what is installed
./install.sh --uninstall # remove the links it made
By default skills are symlinked into ~/.claude/skills and the subagent into ~/.claude/agents, so a git pull updates them. The installer writes ~/.config/papercut-explainer/config.env with PAPERCUT_LIB and the Python paths it created; the library scripts and the skills read it. It never installs system packages (it prints the brew or apt line instead), replaces an identical existing skill folder (such as one from npx skills add) and moves a different one to ~/.config/papercut-explainer/backups/ instead of the skills folder, and does not touch your shell profile.
Prefer to let Claude do it? Open Claude Code in this folder and say "set up papercut-explainer". The papercut-setup skill asks which mode you want, confirms any large download, runs the installer with the right flags and checks the result.
Install by hand: symlink or copy each folder in skills/ into ~/.claude/skills/, agents/papercut-scene.md into ~/.claude/agents/, then export PAPERCUT_LIB="$PWD/library".
Use it
Open Claude Code in any folder you want the episode to live in and ask for a reel:
Make a papercut explainer about https://github.com/example/echolark. 25 seconds, comment keyword PAPER.
The papercut-explainer skill takes the lead. It asks only for what is missing (the one claim the video proves, the audience level, what a commenter gets), then walks the stages below, handing each to its skill. Every stage writes a file, so you can stop, edit and resume.
You can also call one stage directly:
| Say | Skill | Writes |
|---|---|---|
| "set up papercut-explainer", "check my install" | papercut-setup |
installed components, a --doctor report with the install level |
| "what should this reel be about? what format?" | papercut-strategy |
the BRIEF block at the top of research/facts.md: topic, familiar format, audience, funnel |
| "write 5 hooks for this fact list" | papercut-hook |
the HOOK block (SAY / WRITE / SHOW / ALIGN) at the top of papercut/STORYBOARD.md |
| "script this", "write the banner track" | papercut-script |
research/facts.md, narration/script.json, the staging table (banner, set and gag per beat) in STORYBOARD.md |
| "storyboard this script" | papercut-storyboard |
the camera and cut table, frame-level scene blocks and SFX plan in STORYBOARD.md |
| "set up the voice", "re-voice with another speaker" | papercut-voice |
narration/voice/, public/vo/captions.json, src/plan.json |
| "scaffold the episode", "build scenes S03 to S06", "render it" | papercut-build |
the project, episode.json, scenes, SFX cues, audio, out/<name>.mp4 |
| "QA the reel", "check the stills" | papercut-qa |
contact sheets, a pass/fail checklist, fixes |
Run modes the router offers at the start: full reel, script only, storyboard from a script you already have, style prompt for another tool (Sora, Runway, an image model), or fix one scene.
More prompts, with what each one loads and writes: examples/prompts.md.
What works in which install mode
| Stage | Minimal | Standard | Full |
|---|---|---|---|
| Strategy, hook, script, storyboard, style prompts | yes | yes | yes |
| Scaffold, build scenes, SFX and music, stills QA, render to mp4 | no | yes, placeholder voice | yes |
| Voiceover from text, word-timed captions from real audio | no | placeholder timing only | yes |
If a stage needs more than you installed, the skill says so in one line and hands over to papercut-setup rather than improvising.
Examples
| Example | What it is |
|---|---|
examples/hello-reel |
A two-scene reel that runs through the real pipeline: script, placeholder narration, plan, scenes, SFX cues. It is what library/tools/selftest.sh builds and what the GIF above shows. |
examples/paper-trail |
Every file one episode produces, for an invented product: BRIEF and facts with sources, HOOK block, script on the 10-beat spine, storyboard with camera and cut table, episode.json, cue sheet, voice.json. Read it to see what each stage hands the next. |
examples/prompts.md |
Copy-paste prompts for every skill and for common edits. |
Run the fir