People getting impressive results use Claude as motion designer, creative director, animator and developer, with a workflow that lets them inspect and improve the actual video. Separate creative decisions from implementation, and implementation from quality assurance. Never generate the whole video in one shot.
<VS> = <repo>. Paper trail: <VS>\projects\<yyyy-mm-dd>-<slug>\ with brief.md, reference.md, directions.md, storyboard.md, review.md, notes.md, and renders in out/ (gitignored). For the HTML engine the film project itself goes in film/ inside that folder. Templates for the documents: ~/.claude/skills/motion-director/templates/.
The five phases
| Phase | What happens | Stop? |
|---|---|---|
| 1 Understand and plan | Brief from the 10 ingredients (assume and document, ask only critical gaps); reference breakdown if any; three genuinely different directions with a recommendation; storyboard of the chosen one with hits table; design system; which assets are code-made versus real | Stop after directions (user picks) and after the storyboard (user approves) |
| 2 Design for quality | Hierarchy and negative space, one focal point per scene, consistent type/spacing/colour/alignment, purposeful easing and duration, controlled stagger and layering, meaningful transitions, depth/texture/light only where justified, sound synced to events, readable text in safe margins | |
| 3 Implement | Inspect the project first; tokens and timings centralised; deterministic (every frame from t); reusable pieces; real assets at their aspect ratio; audio and picture timing coordinated. One scene first | |
| 4 Render, inspect, improve | Stills and sheets, look, fix, independent scored review, fix the top defects, re-render, repeat to the stop rule (review.md); then the remaining scenes | Show the user only after a passing round |
| 5 Deliver | Final render at spec, ffprobe, sync check, poster, delivery report, learnings (delivery.md) |
Prioritise creative quality, visual consistency, deterministic rendering and verified output over adding effects.
The 10 ingredients of a brief
- Purpose: what the video must achieve, the audience, the one thing to remember.
- Format: 16:9 / 9:16 / 1:1 / 4:5, resolution, frame rate, duration.
- Art direction: aesthetic, references, palette, contrast, materials, texture, atmosphere.
- Composition: where things sit, negative space, foreground / background layers.
- Typography: typeface, weights, hierarchy, line breaks, tracking, alignment, exact on-screen text.
- Movement: what moves, direction, distance, speed, trigger.
- Timing: scene durations, delays, holds, overlaps, reveal times, ending.
- Transitions: cut, match cut, mask reveal, wipe, zoom, morph, camera move, each supporting the story.
- Audio: music mood, SFX, voice-over, accents and silence, and where they occur.
- Quality constraints: no clipped text, broken layouts, random decoration, accidental overlaps, inconsistent fonts or unreviewed final renders.
Full guidance and a weak-versus-strong example: ~/.claude/skills/motion-director/references/brief.md.
The staged prompts (one stage per turn)
- Directions: three genuinely different directions (visual language, palette, type, pacing, animation style, transitions, audio), which is strongest and why. No code.
- Storyboard: timestamps and a clear arc. For every scene: first frame, last frame, focal point, exact text, animation, easing, transition, audio cue, purpose, how it connects to the next; flag visually repetitive scenes. Plus the hits table.
- Build one scene: only scene 1 from the approved storyboard; composition, type, timing and motion quality; reusable pieces; frame-based. Render representative frames, inspect, fix before moving on.
- Quality review: a strict director (best a fresh subagent with
motion-review) scores typography, hierarchy, spacing, timing, easing, transitions, consistency, pacing, sound sync; names the five most consequential defects with fixes; the builder fixes the highest-impact ones and re-renders. No new effects unless they solve a real problem.
The same prompts, for humans, are in <VS>\prompts\ (see prompts/INDEX.md).
When the user says "just make it"
Still write a short brief and storyboard (minutes, not hours), say that you skipped the approval stops at their request, and keep the one-scene-first and review loop: those protect the result, not the process.
Additions to the staged workflow
- Tagged brief.
brief.mdcarries fixed headings:inputs(what to ask the user, defaults if skipped),direction(concept triple, look, Banned for this film),structure(beat map or timed scenes),build(numbered engineering rules),gotchas(known failures from gotchas.md that apply),start(the gate). Template:~/.claude/skills/motion-director/templates/brief.md. Why: a contract the model cannot quietly reinterpret, with the stop where it is cheapest. Evidence: the same skeleton recurs in five finished films by two authors (F-B1). - Banned list per film in the direction tag, seeded from banned-effects.md; the reviewer checks it.
- Start gate. Before any code: the beat map or line-to-visual map plus 4 to 8 named stills. See golden-scene.md.
- Build loop. Five-line plan before each scene, golden scene as the template for the rest, local commit per approved scene with a diff read, decision log, acceptance criteria and a per-film glossary: golden-scene.md.
- Storyboard rules. Transition column reads "X becomes Y" (transitions.md); colour-flow table, a density tag per scene (sparse, medium, dense; dense is rare and deliberate; "dead air" is a static screen under the voice) and a list of where real footage replaces animation (templates in
motion-director). - Say what you cannot do. At the start say what can only be previewed (no render possible, no way to view images). Never describe results you have not seen. Evidence: only claimed in one prompt (F-B14); it extends our "not visually verified" rule to render capability.
- Earns its place. In the plan review, each scene must earn its place within about 3 seconds or be cut; if every transition has the same duration, flag it (name the one hard cut and the one fast fade). Why: the even, tensionless rhythm commenters mock. Evidence: widely reported, judgement not a recipe (F-C5).