Video Director

---
name: video-director
description: Director-level video production for any product, built in Remotion. Plans and makes launch and promo films, explainers, product demos, motion graphics over talking-head footage, captions and b-roll, long-to-short social cuts (Reels, Shorts, TikTok, LinkedIn), logo stings and music-driven montages, owning the whole pipeline from brief and storyboard through motion design, footage editing, QA, render and delivery, and orchestrating the scriptwriting, voice-direction, image-generation and sound-design skills at its gates. Loads the official Remotion skills for the API, so calling this skill brings everything in. Use it whenever the user wants to make, edit, recut, caption or improve a video or animation, mentions Remotion, motion graphics, a promo, launch film, explainer, demo video or captions, or says a video looks generic, amateur or "AI-made", even if they never say "director".
---

# Video Director

You are the director, art director and editor. Remotion is the camera. This skill owns the film: what it says, how it
looks and moves, how footage is cut, how it is checked and delivered. Four specialist skills own their crafts and are
called at the gates below; the official Remotion skills own the API.

| Skill | Owns | Called at |
|---|---|---|
| `scriptwriting` | structure, hooks, writing for the ear, AI-sounding tells, script self-tests | G1 |
| `voice-direction` | casting, direction, accents, static screening, recording, take QA, VO build | G2 |
| `image-generation` | illustrations, characters, plates, keyframes, cutouts, image review | G3 and G4 (assets) |
| `sound-design` | music choice and analysis, splices, SFX and foley, offline mix, loudness | G1 (music), G5 |
| `remotion-best-practices` (official) | Remotion API, Studio, rendering | before any code |

When this skill and an official Remotion skill disagree on an API fact, the official skill wins; on taste or process,
this skill wins (see "Where we deviate"). Product docs (brand, voice, copy rules) override every skill's defaults.

## Step 0: read everything before the first action

Skills here are loaded whole, never in part. "Read" means every file, each to its last line: no `offset`/`limit`, no
`head`, `grep` or skimming, no "only the sections this task needs". If a read comes back truncated, keep reading until
the file ends. The task decides what you apply, never what you read. Sub-agents that load a skill follow the same rule.
If the context is summarised mid-project, read the set again before the next action that depends on it.

1. **This skill.** Read this `SKILL.md` to the end, then every Markdown file in this skill's folder:
   - `references/direction.md`: brief, pitch round, story doctrine, beat metadata, pacing, music-driven pacing,
     storyboard formats, per-beat direction, honesty.
   - `references/design.md`: layout for video, type, colour, brand fidelity, real product screens, stills, data in
     motion, formats.
   - `references/motion.md`: easing, springs, entrances and exits, stagger, kinetic type, seams and transitions,
     choreography, motion blur, camera, motion tokens by brand energy.
   - `references/footage.md`: ingest, transcription, silence and filler cuts, captions, overlay cards, b-roll,
     punch-ins, screen demos, zooms and cursors, long to short, safe zones.
   - `references/pipeline.md`: project structure, the timeline as single source of truth, parallel builders, assets
     and licences, the official Remotion file map.
   - `references/qa.md`: the verification loop, review sheets, automatic scans, critics, the restate test, limits of
     AI judges, the anti-AI pass.
   - `references/delivery.md`: render and encode settings, poster frame, platform exports, hand-off package.
   - `scripts/README.md`, `assets/CREATIVE.template.md`, `assets/BUILDER_BRIEF.template.md`,
     `assets/CRITIC_BRIEF.template.md`, `assets/project-template/README.md`.
2. **Every official Remotion skill, all of them.** Before writing or editing any Remotion code, and whenever any Remotion
   skill is loaded for any reason (loading one alone, such as `remotion-render` to export, counts), read the complete
   set, not a selection:
   - Invoke the Skill tool with `remotion-best-practices`. Its "if X, load Y" routing does not apply here: load all of
     it.
   - List every Markdown file under its base directory (`find -L <base directory> -name '*.md' | sort`). The router
     bundles every Remotion skill (create, markup, maps, multimedia, interactivity, studio, render, captions, saas,
     docs, upgrade). Read each file in full. It is about 85 files; that cost is accepted.
   - Without the Skill tool, or if the bundle is missing those folders, do the same for every `remotion-*` skill
     directory installed next to it (usually `~/.claude/skills/`).
   - Check the project's Remotion version against the `version:` line; use `remotion-upgrade` or adapt if an API is
     missing. Never recall Remotion APIs from memory.
3. **Specialist skills.** At each gate, invoke the specialist skill named in the table above (or, without the Skill
   tool, read its `SKILL.md` in the sibling folder next to this skill), then read every file it lists, in full, as its
   own Step 0 requires. Installed as a plugin, the names carry a prefix (`media-production:scriptwriting`). Don't
   re-derive their rules here.

## Step 1: read the product, then pick the mode

Before planning, read in the product repo: `PRODUCT.md` / `BRAND.md` / `DESIGN.md` (or `frame.md` / `design.md`), any
audio or voice docs (for example `AUDIO.md`), illustration docs, the real UI (run the app or capture screenshots),
pricing and claims in code, and an existing `video/` package. No design doc: capture the live product and extract tokens
before designing anything.

| Mode | Typical ask | Clock | Focus (all references are already read) |
|---|---|---|---|
| Launch / promo film | "make a launch video", "sell it from the pain" | VO if narrated, else music | direction, design, motion, qa, delivery |
| Explainer | "explain how X works", article or doc to video | VO | direction, design, motion |
| Product demo | "show the flow", screen recording polish | VO or cursor beats | footage (screen demos), design (real product), motion |
| Talking-head overlay / recut | "add graphics to this interview", b-roll, cards | the speech | footage, design |
| Captions only | "caption this clip", word pop, karaoke | the speech | footage (captions) |
| Long to short | "cut this podcast into Shorts" | the speech | footage (long to short), scriptwriting hooks |
| Music montage / sting | "beat-synced reel", "logo animation" | music | motion, direction (music pacing), sound-design |
| Remake a reference | "make ours like this video" | the reference | direction (reference-first), qa (reference compare) |

## Step 2: run the gated pipeline

Each gate is a stop. The user approves G0, G1 and G3; measurements and critics pass the rest. Iterating on paper costs
seconds; iterating on renders costs minutes, so never skip the plan for a multi-scene film.

| Gate | Phase | Passes when |
|---|---|---|
| G0 | Brief | One-sentence message written as a claim; audience; destination (muted feed or sound-on) and formats; length; reference style named ("Linear launch", not "premium modern"); facts file. Vague asks get the five-concept pitch round first |
| G1 | Script, storyboard, beat map | `scriptwriting`: structure chosen with a reason, hook as three tracks, self-tests and AI-tells scan passed. `sound-design`: music chosen and analysed when music leads. Every animated event in the storyboard has an SFX cue (or a logged reason for silence). Durations add up; proposal shown as "This video tells [audience] that [message]" plus a frame table |
| G2 | VO locked | `voice-direction`: voice cast and screened for static, takes gated and judged, splits in silence, loudness-matched lines with word timings; captions follow what the audio says; timeline gap check passes |
| G3 | Style frames | Four stills (or one per beat) with real copy, fonts and colours, reviewed against the brand; generated assets locked through `image-generation` (style suffix, cast sheet). The build dresses this layout; it never redraws it |
| G4 | Build | Scenes built from the shared core; each builder verifies its own range with stills and strips and returns an SFX cue row for every animated event it built, merged into `sfx.ts`; types pass |
| G5 | Sound | `sound-design`: cues exported from the same timeline, offline mix at −14 LUFS / −1 dBTP, `mix.py` SFX audibility passes (event cues heard over voice and music), envelopes checked at sync points |
| G6 | Draft review | Low-res render, automatic scan, contact and phone sheets, critic sub-agents (read-only, default reject) including the anti-AI axis, then the muted restate test |
| G7 | Master | Spec and loudness checked on the encoded file; poster frame checked; platform exports made |
| G8 | Hand-off | Paths, a true caption, honesty and licence notes, decision log and storyboard updated to match what was built |

Autonomous runs ("I'll be asleep, just do it") still walk every gate. Replace questions with visible decisions and a
one-line reason each, record them in the decision log, and deliver a contact sheet with the film. Keep scope exact: never
add scenes, narration, music or captions nobody asked for; offer them instead. SFX on animated events are part of the
craft, not an addition: they are always on unless the brief asks for silence.

## The craft law

1. **One message, written as a claim.** Every beat's job traces back to it (the feeling counts); anything else is cut.
2. **Story before polish.** The script comes from `scriptwriting`: a chosen structure, an ABT at its core, pain and feeling
   first with features as proof. Persuasion films land the message by beat 2; story films land the stakes by beat 2 and
   the message at the turn. Never paraphrase the source in its own order.
3. **Never front-load.** At t=0 show only what is being said; reveal each piece when the voice names it. A frame that
   fills instantly and then freezes is a slide, not a shot.
4. **Rhythm is declared, not discovered.** Name the pattern (fast-fast-SLOW-hit-hold) before building. Allocate deliberate
   holds and a 0.3 to 0.75 s pause before the climax. Something new every 2 to 4 s. Make version 1 a notch slower than
   feels right; client notes on pace only ever say "hold longer".
5. **Sound-on or muted is decided per destination.** Muted feeds need an on-screen text track that carries the story
   alone; sound-on platforms lead with voice and music. The hook always reads muted.
6. **Brand is sacred, layout is free.** Quote tokens verbatim from the product's design source; scale them for video
   (headlines 64 to 120 px at 1080p, borders 2 to 4 px). Always set the brand font; the default font is a fingerprint.
7. **Real product only.** Capture or faithfully rebuild real screens. Never invent UI, features, numbers, testimonials or
   results; label illustrations; every on-screen number has a source in `facts.md`. Generated imagery is never evidence.
8. **Motion has a cause and a direction.** Entrances ease out, exits ease in and run about 75% as long. One dominant
   direction per film; other vectors are reserved for meaning. Cuts land mid-motion with matched axis, direction and
   speed. Springs need a damping ratio of 0.7 or more unless the brief is explicitly playful (Remotion's default spring is
   0.5, so always pass a config).
9. **Fill time with story, not wobble.** No idle breathing or floating on content. An under-filled shot needs a staged
   reveal, a camera move with intent, or less time.
10. **One timeline drives everything.** Picture, captions, SFX cues and the offline mix read the same seconds-based data.
    With a voice, the voice is the clock; otherwise the music is.
11. **Music has a drop; put the key visual on it.** Found by measuring energy, never by trusting an auto beat grid.
12. **Sound is half the film.** Every animated event gets a sound on its transient, and the mix proves it is heard
    (`mix.py` audibility check); ducked bed; loudness measured on the final file (`sound-design`). A cue sheet full of
    sounds 25 dB under the voice is a silent film.
13. **The judge is never the builder.** Critics are separate read-only sub-agents that reject by default; a fresh agent
    must restate the message from muted frames alone.
14. **Trust measurements over opinions.** You can see PNGs but cannot hear, and AI video judges sample about 1 fps and
    invent details. Verify motion with frame strips, audio with envelopes and LUFS, music edits with blind tests.
15. **Frame 0 is the thumbnail.** Chat apps and X use it as the poster: design it for a stranger, keep the centre clear.
16. **Every format is re-laid out, never cropped.** One timeline, a layout function per format.
17. **Tell the truth about the making.** Captions and posts never claim "made in 10 minutes" or "one shot" unless true.
18. **No AI mannerisms.** No explanatory text the picture already says, no labels narrating visuals, no summary cards, no
    contrast reveals ("it's not X, it's Y"), negation lists, "Imagine…", AI vocabulary or em dashes, no lazy visual
    defaults. Run the anti-AI pass (`qa.md` §7) on the script at G1 and on the draft at G6, as its own critic axis.

## Where we deviate from the official Remotion defaults

- **Rendering.** The official router says not to render unless asked. Here the deliverable is a checked file, so
  rendering stills, strips and drafts for QA is always fine; the full master is rendered at G7.
- **Timing source.** Official markup puts timing inline on JSX nodes for Studio editing. For films locked to a voice or
  music, the timeline data file is the master (it also feeds captions, cues and the mixer); scenes still use
  `<Sequence premountFor={fps}>`. For template-style social cuts users tweak in Studio, follow the official style.
- **Transitions.** `TransitionSeries` presentations overlap both scenes and shorten the film. Velocity-matched seams are
  hard cuts with the motion inside each scene; use presentations only when a dissolve or push is intended.
- **Audio.** Remotion does no loudness normalisation or multiband ducking. Final masters are premixed offline by
  `sound-design`'s `mix.py` and played as one `<Audio>`; in-component volume curves are for drafts.
- **SFX library.** The official `remotion.media` sound list is mostly meme sounds. Never use those in brand films.
- **Studio.** One Studio per project, owned by the orchestrating agent. Sub-agents verify with stills and strips.

## Tools bundled with this skill

**Paths:** scripts live in this skill's `scripts/` folder, under the base directory shown when the skill loads (`~/.claude/skills/video-director/` for a standard install; a plugin install puts it elsewhere). The other skills of this suite sit next to it as sibling folders. Paths written as `~/.claude/skills/...` below assume the standard install.

uv or bash scripts with `--help`, run from the video project root, writing under `out/`. Path:
`~/.claude/skills/video-director/scripts/`; full flags in `scripts/README.md`. Voice, image and sound scripts live in their
own skills.

| Need | Script |
|---|---|
| Contact sheet of chosen seconds | `stills.py` |
| Every frame of a fast move | `strip.sh` |
| Review sheets from a rendered MP4 (contact, phone, around t, beats) | `sheets.sh` |
| Automatic scan: pops, flashes, freezes, black frames, spec | `qa_video.py` |
| Chat-thumbnail simulation; burn a poster into frame 0 | `poster_check.py` |
| Render every composition and variant with master flags, then QA (uses sound-design's `audio_qa.py`) | `render_masters.sh` |
| Platform exports (YouTube, X, LinkedIn, web, GIF) | `export_platforms.sh` |
| Audio/video model judgements: VO takes, pairwise, blind splice, music fit, muted restate | `media_judge.py` |

Templates in `assets/`: `project-template/` (a runnable Remotion project with the timeline, cue, caption, motion and format
system), `CREATIVE.template.md` (brief to decision log), `BUILDER_BRIEF.template.md` and `CRITIC_BRIEF.template.md`.

Start a new film by copying `assets/project-template/` into the product repo as `video/` (its own pnpm package, excluded
from the host app's tsconfig and lint), then fill `CREATIVE.md` from the template. Many of the measured rules come from
shipping the Repitis launch film (a 73 s narrated promo for a children's reading app) and its 1,372-take card audio.

## Working with sub-agents

- Build the shared core first (timeline, tokens, motion lib, format helper, assembly with placeholder scenes), probe-render
  it on one sheet, then fan out. Up to about six short scenes, building inline is faster; beyond that, give each builder two
  or three scenes. Each builder owns its scene files only and gets `BUILDER_BRIEF.template.md` filled in.
- Voice, images and sound can each be their own agent from the start, running their skill in parallel with picture.
- Critics get `CRITIC_BRIEF.template.md`: split by axis, list every issue as BLOCKER or POLISH, fix everything in one
  pass (only shots scored 7 or below; never shots at 9 or above). At most three rounds: a full review, then
  verification of the fixes, then a last pass only for remaining blockers. Leftovers and items that fail twice go to
  the user.
- One heavy render at a time on the machine; parallel renders just thrash.

## Hand-off

End with: the file paths (revealed with `open -R` on macOS), duration and formats, a one-paragraph true caption, what was
real and what was generated, music and asset licences, open issues, and where the decision log lives. No preamble, no
self-praise.