agentleFS
vargHQvargHQ/skills/code-3d-explainer/SKILL.md

code-3d-explainer

Skill34 starsChanged 8 months agoMITView on GitHub

Make a 3D explainer video of something you cannot film (a cell, an atom, a virus, a protein, an engine, a reactor, a black hole, a maths idea) entirely in code: a sourced fact sheet checked by a fresh critic subagent before any 3D work, the subject built in three.js from procedural geometry (and real data such as PDB coordinates) one part per beat with a label and a one-line fact, a camera that tours the build and zooms through scales to an x-ray cutaway of the whole, a live scale bar, deterministic 1080p rendering with headless Chrome (scripts/capture.ts) or HyperFrames, and QA scripts that check label overlap, phone legibility, reading time and that every word on screen is in the approved fact sheet. Includes a working 21 s animal-cell film to copy. Use when someone asks for a 3D explainer, a science explainer video, "explain how X works in 3D", a cell / atom / virus / molecule / engine / reactor / black hole animation, "build it one part at a time", a cutaway or exploded view explained, a Kurzgesagt-style 3D explainer, a "zoom into the invisible" film, or a Fable 5.2 code explainer. Not for 2D maths and equation animations (manim-skill), short 2D motion formats (motion-formats), general HTML-to-video work (hyperframes), writing the script itself (video-script) or sound design and music (video-sound).

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every string the film will show, word for word, with a source that actually says it.

    line 69
  2. Very specific:

    Critic pass 1: before any 3D work: a fresh subagent (Agent tool, web access) with the prompt in references/critic-prompt.md.

    line 73
  3. Very specific:

    look at qa/sheet.png and qa/phone.png yourself with the Read tool.

    line 99
  4. Distinctive:

    Put the caveat on screen: "Simplified: far fewer parts, colours invented" / "Small parts drawn larger than real", ≥ 2 s, 44 px, near-white …

    line 114

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

3D explainers built from code

A film of the invisible, made entirely in code: a cell built one organelle at a time, a zoom from a fingertip to electron clouds, a reactor you take apart. Nothing is filmed or generated, so every frame is exact, re-renderable and free. And because it looks authoritative, a wrong claim spreads further than it would in a sketch. This skill makes the facts the first step and the last check.

The format went viral with Claude Fable 5.2 (2026-11-09). Science explainers built from code were the #2 use case on launch day (1.37M views, 5.8k bookmarks across 12 posts):

PostWhatLesson
@claudeai, by @kevin_t_ngo (448k views, 2.7k bookmarks)"A 3D model of a cell, built entirely from code one organelle at a time"the build-up is the explanation: one part per beat
@anxuanng (586k views)a 3D film zooming into atoms: "why your fingers never really touch"the replies took apart the physics: it is electrostatic repulsion and Pauli exclusion, not Zeno's paradox. Beautiful frames, wrong mechanism. Hence the fact sheet and the critic
@konstantinsaifo"explain how a nuclear reactor works by building one you can take apart in three.js"exploded views: parts slide out on their beats
@cube_224a ~3 min film on Rubik's cubes and maths, "understandable by middle-schoolers, avoiding the usual clichés"compute every number; ban the clichés in the brief

The example here is our own build (not a copy): examples/animal-cell/, 21 s at 1080p, 9 parts, ending on a labelled cutaway: the full film (1920×1080, 17.7 MB). Your own renders go to renders/master.mp4.

Quick start

cp -r <skill>/examples/animal-cell my-film && cp -r <skill>/scripts my-film/scripts && cd my-film
bun scripts/capture.ts . --stills 2.6,8.4,20.5                 # look at qa/stills/*.png first
bun scripts/capture.ts . --out renders/master.mp4 --labels qa/labels.json
bun scripts/check_labels.ts qa/labels.json                     # overlap, safe area, phone size, reading time
bun scripts/check_facts.ts factsheet.md qa/labels.json         # every word on screen is in the sheet
bun scripts/sheet.ts renders/master.mp4 qa/sheet.png --n 24 --cols 6 --tile 400
bun scripts/sheet.ts renders/master.mp4 qa/phone.png --phone   # 390 px tiles = a phone feed

Open index.html?dev=1 through any static server for a scrubber (space plays, arrows step frames). Then replace factsheet.md, story.json and cell.js with your subject; lib/ is the engine.

The workflow

  1. Fact sheet first (references/fact-sheet.md, worked example examples/animal-cell/factsheet.md). Every string the film will show, word for word, with a source that actually says it; the real size of every part next to the model size; every simplification on purpose (counts, enlargements, invented colours, empty space, missing parts); the claims you deliberately do not make. If the film explains why something happens, the mechanism is its own sourced row.
  2. Critic pass 1 before any 3D work: a fresh subagent (Agent tool, web access) with the prompt in references/critic-prompt.md. It must not be the agent that wrote the sheet. Apply every FIX, paste the verdict into the sheet's "Critic log", set Status: **approved for build**. On the cell it found a dozen real problems (see below).
  3. Beat sheet in story.json: one entrance window per part (timing), one label per part (labels: anchor, side, in/out, name, fact, factId), titles and end card (texts), the scale bar and where it must hide, the camera keys. ~2.2 s per part is the floor (reading time, below).
  4. Build the subject in code, one part at a time (references/build-and-camera.md): procedural geometry in real units, real data where it exists (PDB coordinates for molecules, published dimensions for machines), no downloaded models. Each part enters on its own beat: grow, slide in, draw on, sweep in with a glowing front. Heroes (what the camera visits) are hand-placed; everything else is scattered by a seeded sampler that keeps clear of the heroes and of the camera path.
  5. Camera tour through scales: establish the whole → part by part, closer and closer (the live scale bar goes 5 µm → 500 nm → 200 nm) → x-ray → pull out to a cutaway of the whole, held ≥ 2.5 s with every part tagged. Move-hold-move: an arrive key and a slow push-in key per part, monotone interpolation (never overshoots), holds as long as the label needs to be read.
  6. Optional narration (references/narration.md): script only from sheet rows, estimate_cost then varg generate_speech (ElevenLabs), word timestamps drive label in-times; capture.ts --audio.
  7. Render deterministically at 1920×1080 (references/render.md): render(t) is a pure function of t; capture.ts screenshots the page (labels are HTML) frame by frame in parallel tabs and pipes them into ffmpeg. The same index.html renders through HyperFrames (bunx hyperframes@0.9.15 render). Prove it: capture.ts --check 10.
  8. QA, every render (references/labels.md):
    • check_labels.ts: no overlapping text, 64 px side margins, names ≥ 46 px (9 px on a phone), every label readable for 0.3 s + words / 4.5 s;
    • check_facts.ts: on-screen text equals the sheet, every claim sourced, critic verdict PASS;
    • look at qa/sheet.png and qa/phone.png yourself with the Read tool;
    • critic pass 2: a new subagent compares the frames with the sheet and signs off.
  9. Preview: bash scripts/cut_preview.sh renders/master.mp4 <start> <dur> preview.mp4 (1280×720, 6–10 s, 0.4–2 MB; raise CRF if the grain makes it big).

Rules that came from real failures

Accuracy

  • The sheet's source must say it. Our first sheet cited Wikipedia for a mitochondrion "0.5–1 µm wide"; Wikipedia gives an area (0.75–3 µm²). It quoted a sentence about ATP that is no longer in the article.
  • Hedge to the truth, not to vagueness: "Holds the DNA" became "Holds nearly all the cell's DNA" (mitochondria have their own); "Digest waste with acidic enzymes" became "Break down waste in an acidic interior" (the enzymes are hydrolases in an acidic lumen, not acids).
  • Enlarged parts break the scale bar: hide it in those shots (the ribosome close-up would have shown a 500 nm bar next to 120 nm ribosomes labelled "25–30 nm").
  • Put the caveat on screen: "Simplified: far fewer parts, colours invented" / "Small parts drawn larger than real", ≥ 2 s, 44 px, near-white (34 px grey was unreadable on a phone).
  • A label must never sit over a different part, and its dot must sit on its part. Text lingers at most 0.25 s after its anchor leaves the frame; 0.5 s left "Golgi apparatus" floating over mitochondria. The frame critic also caught a ribosome dot on empty space and a cytoskeleton dot hidden behind a mitochondrion.

Labels and timing

  • Name 64 px / fact 40 px / end tags 46 px with a soft dark scrim; the 40 px end tags failed the phone check (8.1 px on a 390 px feed).
  • Reading time is the binding constraint: nine labelled parts with 7–9 words each need ~21 s. Our first timing gave the ER label 1.5 s; the check caught it and the camera holds grew to fit.
  • Alternate label sides between beats; consecutive labels overlap in time by ~0.5 s and must not overlap in space. End-card tags go in columns sorted by anchor height, laid out all at once.

Look

  • Near-black, two accents (orange #ff5315, teal), colour by system, soft depth from DOF + bokeh specks + fog-dark background, grain. Bloom threshold ≥ 0.7: bright cream parts and sharp speculars became glowing balls and light bulbs.
  • Translucent "x-ray" shells for containers (membrane, envelope, ER) so the inside reads; opaque stylized solids for parts; shells must not write the DOF depth.
  • A part rendering as one flat colour = its faces are back faces (a LatheGeometry profile drawn top to bottom). The Golgi was a flat teal leaf until the profile was reversed; then it became the best shot.
  • Cutaway = clip the containers with two shared planes (clipIntersection), rebuild the cut faces as geometry with a bilayer line at the edge, keep small parts whole, turn the wedge ~28° off the camera.

Rendering

  • Headless Chrome on macOS uses the Metal GPU with no flags; Linux without a GPU falls back to SwiftShader (~1 frame/s at 1080p for this scene).
  • PNG encoding is the bottleneck: JPEG frames are ~3× faster (SSIM 0.98); keep PNG for the master.
  • A CDN import that never arrives hangs a render forever (we lost one to a DNS outage): capture.ts now times out every DevTools call; vendor three.js with scripts/vendor_three.sh (load 0.5 s vs 2–13 s).
  • HyperFrames needs data-no-timeline on a three-only root (or each render waits 45 s for a GSAP timeline) and local @font-face files.

The example: an animal cell, built one part at a time

examples/animal-cell/: membrane → nucleus with pores → x-ray to the nucleolus → rough ER growing from the nuclear envelope (with ribosomes on it and on the outer nuclear membrane) → Golgi stack and vesicles → mitochondria with cristae → a polysome (ribosomes on one mRNA) → lysosomes with enzyme granules → microtubules from the centrosome → a 100° wedge cut, labelled. 21 s, 630 frames, 1 unit = 1 µm, a 20 µm cell. All on-screen text from factsheet.md (25 rows, 7 simplifications). Critic pass 1 on the sheet: PASS WITH FIXES, all applied. Critic pass 2 on the frames: FIX FIRST, 9 findings, 7 fixed and 2 listed as limits. QA on the final render: check_labels all pass, check_facts 36 texts all sourced, --check 10 byte-identical.

filewhat
index.htmlpage + HyperFrames root, import map (three r185), fonts, label CSS
story.jsonpalette, look, timing, labels, texts, scale bar, camera keys
cell.jsthe subject: geometry, placement, anchors, update(t)
lib/explainer.jsengine: renderer + post, PCHIP camera keys, labels and columns, scale bar, window.__film, hf-seek, dev scrubber
lib/materials.jsshell, solid, glow, bokeh shaders with clipping and focus dimming
factsheet.mdthe approved sheet with the critic log
fonts/Inter and JetBrains Mono (OFL)
qa/written by the QA commands: labels.json, sheet.png, phone.png (not kept in the repo)

Scripts

scriptdoes
scripts/capture.tsrender MP4 / stills / label boxes / determinism check / --eval from any page that publishes window.__film; system Chrome over DevTools, no npm
scripts/check_labels.tsoverlap, safe area, anchor covered, phone size, reading time on the real render
scripts/check_facts.tson-screen text vs the fact sheet, sources, critic verdict, approval
scripts/sheet.tscontact sheets from a video or a stills folder, --phone 390 px tiles, --at times
scripts/cut_preview.shthe 1280×720 catalog preview with duration and size checks
scripts/vendor_three.shcopy three.js into the project and point the import map at it

References

fileread it for
references/fact-sheet.mdthe template, source rules, real-data sources (PDB, PubChem, NASA, NIST)
references/critic-prompt.mdthe critic prompts (sheet, then frames) and the Zeno lesson
references/labels.mdlabel anatomy and sizes, placement, reading time, the scale bar, the checker
references/build-and-camera.mdpart recipes, placement, the look, the cutaway, camera keys and pacing
references/render.mddeterminism contract, capture.ts, HyperFrames, measured speeds, troubleshooting
references/narration.mdoptional voiceover on varg and syncing labels to words
references/subjects.mdatoms, viruses, proteins, DNA, reactors, engines, black holes, maths: parts, data, traps

Related skills

threejs-animatic (three.js previz and the seek-safe rendering it shares), hyperframes and hyperframes-animation (HTML → video, the three.js adapter), manim-skill (2D maths), motion-formats (short 2D formats), video-script (writing the script), video-sound (sound and music), varg-ai (voiceover and any generated media).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.