Promptfilm skill

Promptfilm

Make one self-contained .html file that plays a real-time 3D film: a subject shown with striking light, clear motion and captions, looping seamlessly, ready to be recorded straight into a video. (A later stage records it and adds subtitles and music; this skill makes the HTML.)

The quality bar is two films the requester praised (in examples/): a GPU from the data hall down to one silicon atom, and a size ladder from Earth to the observable universe. Their principles, engine and checks are in this skill; their content and format are not a template. Any subject, any format: derive everything from the request.

Recommended environment: Claude Code, with Claude Opus 5.5, Sonnet 5.5 or Fable 5.1 — or a newer version of any of them — at medium effort or above — the setup the skill is made and checked in. Elsewhere it still runs, with a notice that the quality can't be guaranteed (step 0).

Who this is for — the taste profile

Who the films are for, how to talk to them, their format defaults, pace and look, and what must never happen are in the taste profile: ./.promptfilm/taste.md in the working folder if it exists, else ~/.promptfilm/taste.md, else <skill>/taste.md (the default: a Korean creator making Shorts for a general audience, who gives nothing but the request). Where the profile and the principles disagree, the profile wins. This skill is written in English for clarity; talk to the requester in their language (the language of the request), unless the profile says otherwise.

Workflow

<skill> below is this skill's folder (where this SKILL.md is). Work through the steps in order, with a one-line progress note to the requester at each step (a film takes hours; silence is worse).

0. Setup and environment notice (first, once per session)

One command makes sure this machine can make films — installing what is missing — and checks that this is the recommended environment (Claude Code, Claude Opus 5.5, Sonnet 5.5 or Fable 5.1 or newer, effort medium or above):

sh <skill>/scripts/setup.sh --model <your exact model id> --lang ko|en      (ko for a Korean-speaking requester, else en)

• Setup (setup.mjs): Node.js 20+ (installed with Homebrew when missing and Homebrew is there), the scripts' packages (npm), a Chrome that runs headless (else Playwright's Chromium) and ffmpeg (else a local copy in the skill's node_modules) — nothing needs admin rights. When everything is there it takes a second and prints setup: ready — …: say nothing about it. The first run on a machine may download about 200 MB and take a few minutes (run it with a 10-minute timeout); tell the requester in one line that you are getting the tools ready, and afterwards what was installed. When it ends with SETUP MISSING … lines, show them to the requester with the command to run (they can type it with a ! in front), wait until it is done, and run setup.sh again — no film can be made without them.
• Updates (update.mjs, first): promptfilm updates the way Claude Code updates plugins — with Claude Code's own auto-update for its marketplace (/plugin → Marketplaces → Enable auto-update). Installed as a plugin, setup looks for a newer version: with auto-update on it installs it at once, with it off it does nothing, and when it was never set it prints setup: a newer promptfilm is out: … ask the requester. Then ask once (one AskUserQuestion call in their language, apart from the kickoff question; the "what changed" link in it): turn on automatic updates (recommended — Claude Code then keeps promptfilm current by itself and nobody asks again) · update just this once · don't update — and run node <skill>/scripts/update.mjs --auto-on, --install or --auto-off. When a run prints setup: promptfilm updated <old> → <new>. From now on <skill> is <path> …, say so in one line, read the SKILL.md in that folder and follow it from step 0, with that path as <skill> in every command. Never update on your own; when the requester later asks to update, or to switch automatic updates on or off, run the same commands. A line saying a version could not be installed: show it as it is and go on.
• Environment notice (env_check.mjs, printed last): pass the model id your instructions give you (e.g. claude-opus-5-5); a model that isn't Claude passes its own name. In any host that is not Claude Code the notice always shows (the script tells the host from the processes that launched it). If it prints a ⚠️ notice, show it to the requester as it is (translated, when they speak neither Korean nor English), once, at the start of your first reply — then carry on normally: it is information for them, not a reason to stop, to ask, or to lower the bar. When everything matches, say nothing about it. Without a shell (another host), judge the same three things yourself and, if one fails, show the same one line in the requester's language: "⚠️ Not the recommended setup (Claude Code · Opus 5.5+ / Sonnet 5.5+ / Fable 5.1+ · effort medium+), so quality can't be guaranteed. (Now: <what differs>)" — in Korean: "⚠️ 권장 환경(Claude Code · Opus 5.5↑ / Sonnet 5.5↑ / Fable 5.1↑ · effort medium↑)이 아니라서 품질을 보장할 수 없어요. (지금: <what differs>)"

1. Read and understand

• Read the active taste profile, then references/principles.md completely — each principle prevents a result the requester has rejected.
• Read the request. Decide the purpose, the format and the camera language yourself (references/formats.md): a journey through scale, a product ad, a game or app demo, a how-it-works explainer, a recreation of a known scene, a logo sting, a data story — or a mix, or something new derived from the plan.
• Don't ask the requester for materials or choices you can make. The one question you do ask is the kickoff question (step 2). Beyond it, ask only what nobody but them can answer — typically nothing; at most "what is the product?" when it can't be identified from the request, the working folder, their website or the conversation.
• Pick the film folder: the one the requester names, else ./<slug>/ in the working directory.

2. Kickoff question (references/research.md §1–2)

• List what you must know to show each scene truthfully. Size the research: light (~5 min), medium (10–20 min) or deep (20–60 min).

• Ask once, with one AskUserQuestion call holding up to four questions, in the requester's language:

  1. Research — only when medium or deep: what will be researched, the time estimate, deep research then build (recommended) / quick essentials only / no research.
  2. Aspect — 9:16 · 16:9 · 1:1 · 4:5.
  3. Length of one loop — 45–60 s · 25–35 s · 15–20 s · 60–90 s.
  4. Caption languages — the profile's default first (default taste: English + the requester's language — English + Korean for a Korean request, English only for an English one), then the other usual choices: the requester's language only · English only · English + Korean (others through "Other", e.g. "Japanese + English").

  The first option of each is the recommended one: last time's answer from ./.promptfilm/settings.json, else the taste profile's default. Leave out a question the request already answers ("16:9로", "30초짜리") or the format settles (a 10 s logo sting needs no length question); when nothing is left to ask, don't ask.

• Save the answers to ./.promptfilm/settings.json ({ "aspect": "9x16", "length": "45-60", "langs": "en ko" }), then start at once and continue without asking again — the storyboard (step 4) is the one review point before the build.

3. Research (references/research.md)

• Research on the web (WebSearch/WebFetch; tavily or deep-research skills if present; research subagents only after consent). Find the requester's own things yourself. Look at real photos; when the subject moves or is a scene people remember, watch it: sh <skill>/scripts/video_refs.sh <url|file> <film>/research/refs/video (contact sheets + key frames, no API keys). Write research/facts.md, inventory.md, visual-notes.md, gaps.md, sources.md.

4. Plan

node <skill>/scripts/new_film.mjs <film-dir> <name> --aspect 9x16 --length 45-60 --langs "en ko" (the kickoff answers; sh new_film.sh does the same) creates the folder (engine parts with the format written onto the frame and the right fonts, empty film parts, build.mjs + build.sh, plan.md, research/, qa/). Fill plan.md: request, purpose, format, Q1–Q9 (facts, context and ending, scenes, repeated elements and hero, every transition and camera move, insides, pace budget, risk list per principle, quality bar, fact vs illustration). Read references/pacing.md and references/layout.md (composition and text placement for the chosen aspect) now. Budget the time before the scene list is final (pacing.md §2): every thing a caption names is a stop — the camera arrives, the thing fills the frame, the camera holds while the caption is read — moves stay under 3 e-folds/s, the way back ≤ 12% of the loop. That fixes how many stops fit (45–60 s ≈ 8–11); a story with more steps is merged or cut, never flown past (P3). Each storyboard card gives the view's width at its stop (field, metres), and node <skill>/scripts/budget.mjs <film> checks the stops, the e-folds between them and the way back against the length: it must say "the plan fits" before the requester sees the storyboard (a journey whose span can't be travelled at 3 e-folds/s in the length is found here, not after hours of building).

Then the storyboard (references/storyboard.md): write <film>/storyboard.json — a short card per stop the viewer would name (as many as budget.mjs allows — 45–60 s: at most 11): one picture, one plain sentence of what is seen, the caption, played seconds; camera, facts and sources only as details. The picture shows the film, not the research: build the look of the hook and the 2–3 main scenes first — following step 5 (read its references; the quality bar applies) — and put their real renders on those cards (look frames); once a build plays, the Studio fills every card with the build's own frame. Open the Studio on it and start its watcher (step 5's two commands), and wait for their answer (approve, or changes → a revised version). Skip it only when the taste profile says so or the request asks to start at once.

5. Build

• Read references/engine.md (contract, API: keys, tweens, beats, captions, labels, assets, depth of field) and references/techniques.md (proven methods for studio light, materials, repeats, detail by distance, luminous bodies, crowds of things, volumes, continuous camera moves, explaining one thing — the stop (§21), exploded views, characters, lettering; with pointers into examples/ and engine/demo*).
• Model everything to the quality bar (P29): real proportions, bevels / seams / labels, surface micro-structure, physically based materials in studio light. Nothing may look like a mock-up — not even in a test.
• Tools: step 0's setup.sh made sure of them. If a script later can't find one (Cannot find package …, no Chrome, no ffmpeg), run setup.sh again. node <skill>/scripts/selftest.mjs checks the whole toolchain on a machine, the checks catching planted faults included (≈5 min; run it with run_in_background).
• Write the world in parts/p3_*.js … p6_*.js and the timeline in parts/p8_*.js; edit the title and header comment in p1_head.html (story, data sources, look, what is illustrative, pacing, keys). Split long code over several files and writes.
• Author in τ, then mark every stretch with a beat (hook, key, normal, transit, return) — the engine plays them at the taste profile's speeds (default ×2 / ×2 / ×3.5 / ×8 / ×3) so one loop lasts the kickoff length; author each stretch with its speed in mind (pacing.md §2: a move ≤ 3 e-folds/s once played, a stop still for its reading time once played). Each caption is up for its reading time with the camera held on what it names — and says what that is: caption(t0, t1, title, line, second, THING), the object drawn for it (a mesh or group, or a subject(…, { obj })). QA read measures it on the pixels — visible, framed, ≥ 40% of the frame, while the camera holds, for the reading time; the caption goes up as the camera arrives, not during the move (techniques §21). Then set each storyboard card's at (a moment inside its stop, in playback seconds), so the storyboard shows the build's own frame of every scene.
• Close every model the camera can see from any side: a one-sided sheet seen from behind, a box without its lid, a room without walls is a hole in the picture; a two-sided shell without a roof is a hollow model. Thin parts meant to be seen from both sides are side: THREE.DoubleSide with material.userData.thin = true; a surface the camera may pass through (a water surface, a cloud layer) is userData.passable = true. Everything else the camera never enters or crosses (QA surfaces).
• Captions and labels in the kickoff languages: first language for titles and lines, the second (if any) in parentheses in plain words.
• Every number on screen comes from FACTS (from research/facts.md), with its source; derived totals are asserted.
• Build with node <film>/build.mjs (or sh <film>/build.sh; it stops if a film name repeats an engine name — all parts share one scope); serve the parent folder over http (node <skill>/scripts/serve.mjs <parent-folder> --port 8765, in the background); run node <skill>/scripts/qa.mjs <url> --out <film>/qa --only load,engine,err,pace,read,empty,surfaces after every significant change (a minute or two). Look while building: node <skill>/scripts/shot.mjs <url> --out <dir> --sheet 4 t1 t2 … gives one tiled image of chosen moments. (The scripts open the film at its own aspect and take the length target from it.)
• Back up parts before a large change (parts/v<N>/).
• After the first build that plays, open the Studio on the film and start its watcher, both in the background (node <skill>/studio/server.mjs <working-dir> --film <film-id>, then node <skill>/studio/await.mjs --film <film-id>; references/studio.md). The page opens by itself (or the open one switches to the film): they watch, scrub, change the pace, pin comments on the frame and export there. Run the server command again whenever there is something new to see — it only opens the page when the Studio is already running. When the watcher exits, they pressed Send to Claude: do step 6's comment round, then start the watcher again (always with --film: other sessions may be working on other films in the same folder).
• parts/p8z_pace.js holds the requester's own pace edits from the Studio: keep them, and carry them over when you restructure beats (references/studio.md §4).

6. QA and review (references/qa.md, references/studio.md)

Comments first: at the start of every round, when the watcher (await.mjs) exits with a request, and whenever the requester says they left comments, read <film>/review.json — every pin not done (time, spot, the snapshot image, the authored τ) is a finding. Fix it and its kind across the film, then answer in the file (status: "done", a short reply in their language, resolvedIn); the Studio shows the answer and reloads the new build by itself — run the server command again at the end of the round so the page is in front of them.

Then, whenever a round is done: node <skill>/scripts/ship.mjs <film>, with run_in_background (about 4–5× the loop: a 60 s loop ≈ 5 min, more on a slower machine — too long for a foreground command's time limit) — it builds, runs the full QA (every check passes or you fix it; for flicker, find the kind and the cause with scripts/flicker_probe.mjs first, qa.md §5), makes the visual review's material and prints the brief. Look yourself at what QA flagged and at every stop (qa.md §4); then give the brief to a fresh subagent that did not build the film (references/visual-review.md) — it writes <film>/qa/visual-review.md. Fix every finding (and its kind across the film), run ship.mjs again, review again: a build that failed a review stays failed until it is rebuilt. The film is done only when node <skill>/scripts/gate.mjs <film>/<name>.html says READY — this build passed the full QA and its visual review. Nothing short of that is reported as finished. A check the requester explicitly accepts as it is ("깜빡임은 그대로 둬도 돼") goes in <film>/qa/accepted.json with their words (qa.md §3) — never on your own judgement.

7. Deliver

• Save <name>.html (latest) and <name>.v<N>.html (this version) side by side; never delete earlier versions.
• The video: the Studio's "MP4 만들기" (Export), or node <skill>/scripts/render.mjs <film>/<name>.html --out <film>/render/<name>.v<N>.mp4 (frame-exact, one seamless loop, 1080 px on the short side; a few minutes: with run_in_background). The video only — the captions are already in the picture; write a subtitle file (--srt) only when the requester asks for one. Render the final once the requester is happy, or when asked. render.mjs makes a final video only of a build the gate calls READY; when the requester wants a video of a build that isn't ("일단 뽑아줘"), finish the checks first if they are close, else render with --unchecked and say plainly in the report that this video has not passed its checks, and which ones (a --draft preview needs no gate).
• If the session can publish Claude artifacts and the requester uses them, update the same private artifact URL each version (the page body without <!DOCTYPE>, <html>, <head>, charset/viewport meta and the <body> wrapper).
• Open the Studio on the film (the server command again) as you report, so they can watch it at once.
• Report in the requester's language, plainly, with the taste profile's labels (default: exactly 한줄 결론: / 바뀐 점 / 검사 결과 / 한계 / 파일 in Korean; Bottom line: / What changed / Checks / Limits / Files in English). Only measured numbers; say what could not be checked; list what was drawn as illustrative because it is not public, and any principle the taste profile overrode. 검사 결과 (Checks) starts with the gate line for this build (READY, or NOT READY and why) and the visual review's verdict — never "passed" for checks that ran on an earlier build or only in part. Keep it short.

Pace in one table (default taste; details: references/pacing.md)

Beat	Plays at	Use for	Played length
hook	×2	a striking opening + title	1.5–3.5 s, the title readable
key	×2	what people came for: the hero alone and large, an inside or mechanism revealed, the climax, the end card	its caption's reading time (≈ 2.5–4 s), camera held ≥ 2.4 s
normal	×3.5	moving on, comparisons, a run of steps or shots	held ≥ 1.8 s where it carries a caption
transit	×8	long moves where nothing new appears	as long as the move needs at ≤ 3 e-folds/s
return	×3	back to the opening frame	≤ 12% of the loop

Every caption is a stop: up for its reading time, the camera held on what it names, framed and large. Nothing but the way back zooms faster than 3 e-folds/s (the requester's fastest edit ran 2.4); the camera holds for at least half the loop. QA pace, read, empty and surfaces measure it; the visual review (fresh eyes) and the gate make sure nothing ships without it.

Ambient motion (spin, flow, flames, pulsing lights) runs on playback time with whole cycles per loop; every animated value is back at its first-frame value when the loop closes.

Never do these

The taste profile's §5 lists what the requester has rejected — popping in, lighting up on entry, cuts and camera jumps, mock-up modelling, fake or wrong objects, runs of near-identical shots, flicker, skipping steps (flown past, captions over something else, empty frames), anything that looks broken, changing the text design, asking for things you can find. Read it at step 1 and check the film against it before delivering. And never call a film finished, or render its final video, before the gate says READY (step 6).

Reference map

File	Read when
taste.md (or the user's own profile)	first, always
references/principles.md	first, always
references/formats.md	step 1 — deciding the film's shape
references/research.md	steps 2–3 — the kickoff question and research
references/plan-template.md	copied to plan.md by new_film.sh
references/pacing.md	planning beats; when the requester re-edits a film (then scripts/edit-analysis)
references/layout.md	composing shots and placing text, per aspect
references/engine.md	before writing film code
references/techniques.md	building the world
references/qa.md	QA (incl. pace, read, empty, surfaces) and your own look-through
references/visual-review.md	the review by fresh eyes before anything is delivered; the gate (with review-examples/: rejected and praised frames)
references/storyboard.md	step 4: the plan as scene cards with real renders (look frames, then the build's frames), reviewed in the Studio before the build
references/studio.md	the Studio (look, comment, render), review.json, rendering the MP4
references/bugs.md	when something breaks
references/cases.md	how principles became decisions in the two reference films
examples/	code patterns only (cosmic-scale parts; the Blackwell film as one file); not content
engine/build_demo.sh	test films for the engine and QA: a journey (demo) and a product film at the quality bar (demo-ad)
scripts/video_refs.sh	reference frames from a video (a scene to recreate, an ad, a demo): contact sheets + key frames
scripts/flicker_probe.mjs	what flickers at one moment and which kind (nondeterministic / static / motion stepping), by group
scripts/embed_assets.mjs	packing found or supplied images / models into the film
scripts/serve.mjs	the local http server QA and rendering open films from (127.0.0.1 only)
studio/server.mjs	the Studio: a local page to play, scrub, comment and render; opens itself on --film (references/studio.md)
scripts/render.mjs	the MP4 (or one frame as PNG), frame-exact and deterministic; a final video only of a build the gate calls READY
scripts/budget.mjs	step 4: does the storyboard fit the length with every card a real stop?
scripts/ship.mjs	step 6: build → full QA → the review's material and brief → the gate, in one command
scripts/review.mjs · scripts/gate.mjs	step 6: the visual review's material · is this build READY (full QA + visual review)?
scripts/setup.sh	step 0: installs what this machine is missing (setup.mjs), then the environment notice (env_check.mjs: host, model, effort)
scripts/update.mjs	step 0, run by setup.sh first: a newer promptfilm, through Claude Code's own auto-update switch (--auto-on · --install · --auto-off)
scripts/selftest.mjs	after changing the engine, the scripts or the Studio (and on a new machine): the skill checks itself end to end