motion-designer skill

---
name: motion-designer
description: Make short videos from code: launch films of apps (the real UI in an iPhone or a laptop window, or a story in panels), and any other short video: titles and stings, kinetic type, explainers, data videos, music videos, photo montages, and lower thirds or captions over footage, with a library of effects and transitions. Cut on the beat to an original track made for it or the user's, with an optional local voiceover (Chatterbox or Kokoro), checked frame by frame and rendered to MP4, a muted loop, a poster and one self-contained HTML. Also makes or cuts a track to the bar, writes and mixes a voiceover, and installs the tools it needs after asking. Use when the user wants a launch video, promo, teaser or product film of an app, or any short motion video, title, explainer, animated chart or captioned clip, wants to change such a video's story, style, pacing, music or voiceover, wants a track made or cut to a video, or asks what the tool needs to run.
argument-hint: "[app project dir] [mobile | desktop] [square | vertical | landscape] [length, e.g. 45s]"
---

# motion-designer: films from code

You direct and build short videos: most often a film of an app in use, and any other short motion video on the same engine ([types](reference/types.md#beyond-app-films)). The app's own interface, rebuilt from its code and screenshots or captured from its web frontend, lives inside a device that one camera films, and every move lands on the music's beat. The film is a page whose every frame is a pure function of time, `seek(t)`, so it renders frame-exactly, loops without a seam, and can be checked frame by frame.

- **Blank**: full-frame shots on a canvas of any size, for titles, kinetic type, explainers, data, music videos and montages (`templates/blank`). **Overlay**: a clear background drawn over the user's footage, for lower thirds, captions and callouts (`templates/overlay`). Both lean on [effects](reference/effects.md).
- **Mobile**: an iPhone (`templates/mobile`). **Desktop**: the app's window on a laptop display with menu bar, dock, pointer and a lid that closes (`templates/desktop`); web apps in the same window with `browserBar(url)`. **Story**: a hook, the product's arrival, features as panels, the brand's character, and an end card (`templates/story`, [types](reference/types.md)).
- `SKILL_DIR` in every command is `${CLAUDE_SKILL_DIR}`, the folder holding this file, with `scripts/`, `templates/` and `reference/`. Write it out as that absolute path in each command.
- Any agent can run this skill. Where a step says **Plan**, **Ask**, **Look**, **Delegate**, **Background** or **Send**, [harness](reference/harness.md) maps it to your tools (Claude Code, Codex, others).

## 1. Start from the project's state

Take the first row that matches and do only what it says; the rows below it do not apply.

| State | Do |
|---|---|
| A question about the skill, or what it needs to run | Answer it. For setup, run `bash SKILL_DIR/scripts/doctor.sh` and follow [setup](reference/setup.md). |
| Music only: make a track, or cut one to a film | [music](reference/music.md), nothing else. |
| Voiceover only, over a film that exists | [voiceover](reference/voiceover.md), nothing else. |
| A film folder exists and the user names a change | Make that change. Read only the reference for it (§ 5), find the code with `grep -n`, then run the checks and review only the changed stretch. No new brief. |
| A film folder exists and the user says go on | Read `brief.md` (its `## Status` says where it stopped) and the beat map in `README.md`, then continue from that step. |
| A new video that is not about an app | As a new film, with the brief built around what the video says, `blank` or `overlay` as the template, and [effects](reference/effects.md) read at step 3. |
| A new film | `bash SKILL_DIR/scripts/doctor.sh`; if something is missing, follow [setup](reference/setup.md) (say what and why, install only after a yes). Then § 2 from step 0. |

## 2. Workflow

Stop for the user's go-ahead after step 0 and again after step 2 unless they asked you to go straight through; after that, work without asking except where [rights](reference/rights.md) says to. At the end of every step, rewrite the `## Status` section at the bottom of `brief.md`: the step reached, what is done, what is next, what is open. With it and the files on disk, a fresh session continues where this one stopped.

0. **Brief, as a plan** (**Plan**: in Claude Code `EnterPlanMode`, then `ExitPlanMode` with the brief; unless the user asked to go straight to building or gave you a complete brief). Find the product's name, read what it does and which flows are worth filming, write a brief for this product alone ([brief](reference/brief.md)), with the film's type ([types](reference/types.md)).
1. **Materials.** Find what you can: the app's code (screens, tokens, fonts, icons, copy), a Simulator or desktop build, brand assets, screenshots or recordings. Ask only for what you can't find: the music (the user's track; without one, make an original with [music](reference/music.md#make-one) or, with their go-ahead, search [music sources](reference/music-sources.md)), format and length, features that must appear, claims to avoid. Confirm every feature you plan to show exists and works that way: read its code and try it.
2. **Concept.** Offer two or three [styles](reference/styles.md) that suit the app. Write the story in beats (one visual change per beat, a hold after each result, the biggest reveal on the drop), a beat-map table (beat, time, what happens), the screens and assets needed, and four stills from the template in the chosen style: the opening, the key product moment, the drop, the final frame. List your assumptions. A social cut (15 to 25 s) shows the app's strongest action in the first two seconds. For an App Store app preview, explain guideline 2.3.4 first ([rights](reference/rights.md)).
3. **Build.**
   - `bash SKILL_DIR/scripts/new_film.sh <film-dir> mobile|desktop|story|blank|overlay`; open `src/index.html` in Chrome to preview and scrub.
   - Set the clock on the first line of `scenes.js`: `film({ BPM, BEATS, holds })`.
   - Pack the app's look: `swift SKILL_DIR/scripts/symbols.swift <film-dir>/assets/sym plus@semibold …` for SF Symbols, then `python3 SKILL_DIR/scripts/assets.py <film-dir>/src/assets.js --font "Family=font.ttf" --img icon=AppIcon.png --sym <film-dir>/assets/sym`. The app's family goes first in `film.css`, the style's tokens in its `:root`.
   - Rebuild each screen in `scenes.js` from the real app, in app or window points; write every time as a story beat `B(n)`. For web-tech desktop apps, capture the real UI instead ([capture](reference/capture.md)). Read [motion](reference/motion.md) and [phone](reference/phone.md) or [desktop](reference/desktop.md) first.
4. **Sound** ([music](reference/music.md)): follow the sound brief. Make the track if there is none, listen with `beats.py`, pick bars so its lifts and breaks land on the film's, cut it to `<film-dir>/audio/edit.m4a`, put its `BPM` and `BEATS` in `film({...})`. In a story, feature cards or type-led film, give the actions their sounds (`cues()`, `sfx.py`).
5. **QA loop** ([qa](reference/qa.md)):
   - `node SKILL_DIR/scripts/check.mjs <film-dir>/src/index.html`: no clocks, timers, randomness or CSS animation, no page errors, the loop closes, frames identical in any seek order.
   - **Delegate** the looking to [reviewers](reference/reviewer.md), one per stretch of about 12 s and per kind (overview, transitions, text), plus one at phone size for the whole film, all at once. Each scores its stretch from 1 to 10. Fix what they report, then send them back to what changed. Repeat until every report reads `clean` with every score at 8 or more.