Explainer Video Skill (Hellboy)
You turn one tech topic into a finished 2–3 minute 1080×1920 MP4 that a non-technical person understands on first viewing. The visual style, pacing and script structure are cloned from a reference channel (analysed in docs/01-style-bible.md). Two things are deliberately ours: the character (Hellboy) and the voice.
You only write text files (a script and a storyboard.json). The engine in engine/ does the voice, captions, animation, character, music and rendering.
When the user just gives a topic
Do the whole job without asking further questions:
- Make a slug from the topic (
how-dns-works) and runpython engine/make_video.py new videos/<slug>. - Write
videos/<slug>/script.md(docs/02), thenvideos/<slug>/storyboard.json(docs/03 + docs/04). Copy patterns fromexamples/upi-explained/. - Run
python engine/validate_storyboard.py videos/<slug>. Fix every ERROR and repeat until it prints0 error(s). - Run
python engine/make_video.py preview videos/<slug>. If you can see images, checkbuild/preview.pngagainst docs/06 section B and fix. - Run
python engine/make_video.py render videos/<slug>. Reply with the pathoutput/<slug>.mp4, the duration and a 2-line summary.
The non-negotiables
- Hellboy is never redrawn. He comes only from
character/hellboy/hellboy.js. You may setshow,arm(down/point/explain) andexpression, nothing else. Readcharacter/hellboy/CHARACTER_BIBLE.mdonce. - The voice is fixed in
engine/config.json. Don't change it per video. - Length: 360–470 words of narration, 2:00–2:50. Sentences ≤ 20 words.
- Every sentence changes something on screen. Items appear on their spoken keyword (
"at"). - Correct beats simple. Simplify by leaving things out, never by saying something false.
- Validator must pass (
0 errors) before rendering.
Workflow (do these in order)
| # | Step | Read | Output |
|---|---|---|---|
| 1 | Scaffold | – | python engine/make_video.py new videos/<slug> |
| 2 | Plan + write the script | docs/02-script-writing.md | videos/<slug>/script.md (360–470 words, 7 beats) |
| 3 | Plan the visuals | docs/03-visual-planning.md | scene list: narration → type, headline, character |
| 4 | Write the storyboard | docs/04-storyboard-reference.md | videos/<slug>/storyboard.json (or meta.json + scenes.jsonl → assemble) |
| 5 | Validate | – | python engine/validate_storyboard.py videos/<slug> → fix until 0 errors |
| 6 | Preview + QA | docs/06-qa-checklist.md | make_video.py preview videos/<slug> → inspect build/preview.png, fix |
| 7 | Render | docs/05-production.md | make_video.py render videos/<slug> → output/<slug>.mp4 |
| 8 | Final QA | docs/06-qa-checklist.md | score ≥ 85, all MUST items pass |
Small/local model? Follow docs/07-small-model-playbook.md instead of steps 2–5. It breaks the work into one-scene-at-a-time prompts.
The 7-beat script (memorise)
Hook (≤ 22 words: "X explained." / "How does X actually work?" / surprising claim / relatable action) → Tension (the mystery) → Roadmap ("Let's follow…") → Body (3–6 chapters: concept → plain meaning → everyday example → consequence; ONE running example with a named person) → Twist ("But here's the interesting part…") → Recap ("So remember it like this." one line per chapter) → Punchline (fragments that echo the hook: "One scan. Four players. Two seconds.").
Scene recipe (memorise)
- 1 scene = 1–3 sentences (8–28 words, 3–8 s); 20–32 scenes per video.
- Pick
visual.typefrom the decision table indocs/03-visual-planning.md. Use 7–12 different types per video. - Show Hellboy in 40–70 % of scenes (always: first scene, twist, recap, last scene). Hide him for
sequence,hub,diagram,compare. - Build big diagrams over 2–4 scenes with
"continue": true+"shown": trueitems and the same headline. - Headlines 2–6 words with one
*accent*word. On-screen labels 1–4 words.
Commands (from the repository root)
# activate first: source .venv/bin/activate | Windows: .\.venv\Scripts\Activate.ps1
python engine/make_video.py new videos/<slug> # templates
python engine/make_video.py assemble videos/<slug> # meta.json + scenes.jsonl -> storyboard.json
python engine/validate_storyboard.py videos/<slug> # must be 0 errors
python engine/make_video.py preview videos/<slug> # build/preview.png (1 frame per scene)
python engine/make_video.py render videos/<slug> [--fast]
First time on a machine: ./setup.sh (Linux/macOS) or setup.ps1 (Windows). Finished videos land in output/<slug>.mp4.
Reference material
examples/upi-explained/(warm-paper) andexamples/load-balancer-explained/(blueprint) — complete worked examples. Copy their patterns.templates/—script.template.md,storyboard.template.json.docs/01-style-bible.md— what the reference does, measured (why the rules exist).engine/icon_names.txt— all 2,359 allowed icon names (Lucide).