Communitygithub.com

explainer-video

Create 2-3 minute vertical (9:16) tech explainer videos for non-technical viewers, presented by the cartoon architect "Hellboy", in the style of the reference reels (chapter tracker, building diagrams, karaoke captions, lip-synced character, Indian-English voice). Use when asked to make, script, storyboard, render or improve an explainer video / reel / short about any technical topic.

What is explainer-video?

explainer-video is a Claude Code agent skill that create 2-3 minute vertical (9:16) tech explainer videos for non-technical viewers, presented by the cartoon architect "Hellboy", in the style of the reference reels (chapter tracker, building diagrams, karaoke captions, lip-synced character, Indian-English voice). Use when asked to make, script, storyboard, render or improve an explainer video / reel / short about any technical topic.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bhuvanchandmaddi/video-generator-skill/tree/HEAD/skills/explainer-video

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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:

  1. Make a slug from the topic (how-dns-works) and run python engine/make_video.py new videos/<slug>.
  2. Write videos/<slug>/script.md (docs/02), then videos/<slug>/storyboard.json (docs/03 + docs/04). Copy patterns from examples/upi-explained/.
  3. Run python engine/validate_storyboard.py videos/<slug>. Fix every ERROR and repeat until it prints 0 error(s).
  4. Run python engine/make_video.py preview videos/<slug>. If you can see images, check build/preview.png against docs/06 section B and fix.
  5. Run python engine/make_video.py render videos/<slug>. Reply with the path output/<slug>.mp4, the duration and a 2-line summary.

The non-negotiables

  1. Hellboy is never redrawn. He comes only from character/hellboy/hellboy.js. You may set show, arm (down/point/explain) and expression, nothing else. Read character/hellboy/CHARACTER_BIBLE.md once.
  2. The voice is fixed in engine/config.json. Don't change it per video.
  3. Length: 360–470 words of narration, 2:00–2:50. Sentences ≤ 20 words.
  4. Every sentence changes something on screen. Items appear on their spoken keyword ("at").
  5. Correct beats simple. Simplify by leaving things out, never by saying something false.
  6. Validator must pass (0 errors) before rendering.

Workflow (do these in order)

#StepReadOutput
1Scaffold–python engine/make_video.py new videos/<slug>
2Plan + write the scriptdocs/02-script-writing.mdvideos/<slug>/script.md (360–470 words, 7 beats)
3Plan the visualsdocs/03-visual-planning.mdscene list: narration → type, headline, character
4Write the storyboarddocs/04-storyboard-reference.mdvideos/<slug>/storyboard.json (or meta.json + scenes.jsonl → assemble)
5Validate–python engine/validate_storyboard.py videos/<slug> → fix until 0 errors
6Preview + QAdocs/06-qa-checklist.mdmake_video.py preview videos/<slug> → inspect build/preview.png, fix
7Renderdocs/05-production.mdmake_video.py render videos/<slug> → output/<slug>.mp4
8Final QAdocs/06-qa-checklist.mdscore ≥ 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.type from the decision table in docs/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": true items 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) and examples/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).

Related Skills