motion-graphics

What this skill does

# Motion Graphics

Produce silent MP4 motion-graphic clips from a markdown video script using Remotion. The clips are overlay B-roll the user drops onto a 4K 30fps voiceover timeline in their video editor.

## When to Use

Run this from a video folder — the folder holding source material for one YouTube video, e.g. `C:\videos\rls\`. Use when the user:

- says "build motion graphics for this video"
- pastes or points at a script and wants overlay clips made from it
- mid-edit, says "I want this part to be a motion graphic" — re-invoke and add one clip

Do not use this for full standalone explainer videos. The output is overlay content for an existing voice track.

## Output Spec

Every clip the skill produces is:

- 3840 x 2160 (4K), 30 fps, H.264
- silent — no audio track. The user has their own voice recording.
- duration matches the natural read time of the script section it covers (see Phase 5). Most clips end up 2-15 seconds; longer is allowed but consider splitting (see "Long clips" below).
- rendered to `motion-graphics/out/<clip-id>-{A,B,C}.mp4`

3 variants are rendered per clip. The user picks one. The other two MP4s move to `out/_rejected/` (do not delete — keep for recovery). All three `.tsx` files stay in `src/clips/`.

## Workflow

### Phase 1 — Locate the script (pre-flight gate)

Before scaffolding or any other work, confirm a script exists in the video folder.

1. List `.md` files in the video folder (top level only, not in subfolders).
2. If exactly one `.md` file is found, treat it as the script and confirm the filename with the user.
3. If multiple `.md` files are found, ask the user which one is the script.
4. If **none** is found, **stop immediately**. Tell the user verbatim:
   > I couldn't find a `.md` script in `<folder>`. Either drop the script there as a `.md` file, or paste the script content in chat now and I'll save it to `<folder>/script.md`.

   Then wait. If the user pastes the content, save it to `<folder>/script.md` first. Do not proceed past this phase until a script is on disk in the video folder.
5. Once located, never modify the source file — it's the source of truth. The skill will work against a copy inside the Remotion project (see Phase 2).

### Phase 2 — Set up the project (once per video)

Run from the video folder so the subfolder is created in place.

1. Create `motion-graphics/` subfolder.
2. Scaffold a blank Remotion project inside it:
   ```bash
   npx create-video@latest --yes --blank --no-tailwind motion-graphics
   ```
3. Copy the located script into the project as the canonical working copy. Use the right command for the shell:
   ```bash
   # bash / git-bash
   cp <located-script>.md motion-graphics/script.md
   ```
   ```powershell
   # PowerShell
   Copy-Item <located-script>.md motion-graphics/script.md
   ```
   The original file in the video folder remains untouched.
4. Install the official Remotion AI skill into the new project so its rules are available next time an agent works here:
   ```bash
   cd motion-graphics && npx skills add remotion-dev/skills
   ```
5. Install supporting Remotion packages:
   ```bash
   npm install @remotion/shapes @remotion/transitions @remotion/google-fonts @remotion/paths @remotion/animation-utils @remotion/layout-utils
   ```
6. Copy the skill's bundled assets into the new project:
   - `skills/motion-graphics/theme.ts` -> `motion-graphics/src/theme.ts`
   - `skills/motion-graphics/STYLE.md` -> `motion-graphics/STYLE.md`
7. Read `STYLE.md` and `src/theme.ts` before writing any clip code. Read the official Remotion skill's `SKILL.md` and any `rules/*.md` that match the clips you're about to build (e.g. `rules/text-animations.md`, `rules/transitions.md`, `rules/spring-physics.md`).

### Phase 3 — Gather external context

The script often references URLs (docs, blog posts, tldraw boards, GitHub repos, diagrams). Before proposing clips, try to fetch what's relevant so clip ideas can build on real reference material.

1. Scan `script.md` for URLs (markdown links, bare URLs, "see X" references). **Ignore URLs inside `<aside>` blocks** — those belong to the user's editor-side B-roll, not the clips this skill generates. Exception: if you've decided to propose a clip immediately adjacent to an aside and the URL inside the aside genuinely supports that clip's visual, treat it as load-bearing and fetch it.
2. For each URL that's plausibly visual or referential context (not just a citation), attempt `WebFetch`.
3. **If fetch returns meaningful content** (article text, README, diagram description), keep it as context for clip design.
4. **If fetch fails or returns nothing useful** (auth-walled, client-rendered SPA like tldraw/Figma/Excalidraw, 404), **stop and ask the user**:
   > I can't access `<url>` — it looks like a `<reason: client-rendered board / auth-walled / 404>`. Options:
   > - Export the content as a PNG/SVG and drop it in `<video-folder>/refs/`, then tell me the filename.
   > - Describe what's on it in chat.
   > - Skip it if it's not load-bearing for the clips.
5. Save any fetched text context to `motion-graphics/refs/<slug>.md` and any user-provided images to `motion-graphics/refs/`. Reference these in clip notes files.

If no URLs are present or none need fetching, skip this phase and move on.

### Phase 4 — Propose clips

Parse `script.md` and produce a candidate clip list. **The bar is illustrative value**: every clip you propose must answer "yes" to *"does a visual genuinely help the viewer understand what the voice is saying here?"*. If the answer is "not really, it would just be filler", do not propose a clip there.

**Selection rules** in priority order:

1. **Intro hook** — propose 1 clip for the opening 2-3 sentences. The intro is a special case: even if there's no concrete concept to illustrate, a punchy typographic title-card works because the goal is attention, not comprehension.
2. **Code blocks** — propose 1 clip per meaningful code block (3+ lines). Code reveals are pure illustration.
3. **Enumerated/sequential content** — lists of steps, recipes, ordered procedures. The "update schema -> migrate -> tighten schema" pattern is a perfect candidate.
4. **Concept comparisons** — "User A vs User B", before/after, "Firebase does X, Convex does Y", architecture diagrams.
5. **Concrete hypotheticals** — "imagine if...", "let's say we've got...", anything that sets up a scenario you can show.
6. **Outro/takeaway** — only if there's a concrete idea to visualise. *"We have zero downtime"* is sentiment, not concept — skip. *"Three rules to remember"* is concept — propose.

**Things to skip — do not propose clips for**:

- **`<aside>` blocks**. These are the user's editing notes to themselves about B-roll they will overlay manually in their editor (e.g. *"show sweaty balmer gif"*, *"point to the hat"*). They are **not** briefs for the motion-graphics skill. Treat them as comments — read them for context, do not generate clips from them.
- **Pure sentiment / opinion** — "this is really powerful", "I love this", "trust me".
- **Conversational filler** — "anyways", "let me explain", "okay so".
- **Sections where the spoken words are the whole point** — a personal story, a joke, a meta-comment about the video. Audio-only is correct here.

**Present the proposed list** to the user as a table. Each entry:

- clip id (`clip-01`, `clip-02`, ...) — these are also the Remotion composition IDs (see Phase 5 for naming rules).
- 1-2 lines of the script section it covers (quoted)
- one-line visual concept
- estimated duration in seconds (based on natural read time — see Phase 5 step 4)

Ask: anything to add, drop, or rephrase? Wait for explicit approval before generating.

### Phase 5 — Generate 3 variants per approved clip

For each approved clip:

1. Write a notes file at `motion-graphics/src/clips/notes/clip-NN.notes.md`:
   ```
   # Clip NN - <short slug>

   ## Script section
   <verbatim paste>

   ## Visual brief
   <one paragraph plain-English description