/reel-builder

name: reel-builder
description: "Turn a topic / research brief / script into a 9:16 vertical reel: 1-4 shots + matched music + ffmpeg-stitched final.mp4 with optional burned-in captions. Modes: --topic / --research / --script-file; --shots; --style; --music-style; --aspect; --captions. Use when: 'make a reel about X', 'short video on Y', 'TikTok / Reels / Shorts about Z'."

license: MIT
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob

<objective> End-to-end reel generator. Input: topic OR research brief OR pre-written script. Output: a single MP4 file with stitched video shots + background music + optional captions, plus the individual components (shots, music, script) for reuse.

This skill orchestrates: 1. `viral-text` (or user-supplied script) → 3-shot screenplay with timed captions 2. `video-prompt --execute` → N video shots via the chosen provider (Veo 3.1 / Sora 2 / Kling 3.0 / Runway Gen-4) 3. `music-prompt --execute` → 1 music track via Suno / Stable Audio / ElevenLabs Music / Lyria 3 Pro 4. `common/style-library/video/` (12 directorial styles) and `common/style-library/music/` (12 genre presets) 5. ffmpeg → concat shots, mix music, burn captions

Use when the user wants a finished reel, not just video prompts. Without `--execute`, returns assembled prompts; with `--execute`, generates the MP4.

This skill does NOT:

• Add a voiceover / TTS narrator (out of scope for v1 — would need ducking/mixing logic; planned v2.4.0)
• Composite multi-track edits beyond hard cuts (no dissolves, no transitions other than concat)
• Beat-sync shots to music BPM (would need BPM detection; planned later)
• Post to platforms — that is `post-publisher`, which takes this skill's output directory (the `final.mp4`) as its input
• Run editing software (Premiere / DaVinci / CapCut) — uses ffmpeg only

</objective>

ROLE

Topic / research / script → build 1-4 shot screenplay with timing → resolve video style (directorial anchor) + music style (genre preset) → generate shots in parallel (async polling) + music in parallel → ffmpeg concat → ffmpeg audio mix → optional caption burn-in → print final paths.

PIPELINE

1. **Resolve input source**:

• `--script-file <path>`: read pre-written script with shot timing markers and captions (skip step 2)
• `--research <path>`: read brief, extract key facts, condense into a 15-30 sec hook+payoff narrative
• `--topic "<text>"`: invoke `viral-text` to draft a hook+beats+payoff script (~80-150 words)

2. **Plan shots** — see `references/shot-planning.md`:

• Default: 3 shots × 5 sec = 15 sec total (TikTok / Reels sweet spot)
• Single-shot mode: 1 shot × 8 sec (Veo 3.1 max) — for atmospheric / one-take pieces
• Each shot has: index, screenplay line (action description), camera/composition note, dialogue or VO line (optional)
• Shot 1 always carries the hook (must land in first 1-2 sec)

3. **Resolve video style** — see `references/style-resolution.md`:

• `--style <id>`: load `common/style-library/video/<id>.md`. Use the `Shot anchor (per-shot prompt fragment)` block.
• `--style auto`: pick from library based on topic/tone + pacing requirements.
• Same anchor APPENDED to every shot's prompt. ONE style for the whole reel.

4. **Resolve music style** — see `references/music-pairing.md`:

• `--music-style <id>`: load `common/style-library/music/<id>.md`. Use the Suno Style box + meta-tag stacks if Suno selected; or the Lyria field-driven block if Lyria; or the ElevenLabs prompt if Eleven.
• `--music-style auto`: pick from library based on video style (each video style has a "Suggested music style" field — start there) + tempo requirement.
• One music track for the whole reel.

5. **Pick providers** — see `references/model-picker.md`:

• Video: `--video-provider auto|veo-3-1|veo-3-1-fast|veo-3-1-lite|kling-3|runway-gen-4-5|fal-video`. Auto-pick by style requirements.
• Music: `--music-provider auto|suno-v5-5|stable-audio-2-5|eleven-music|lyria-3-pro`. Auto by genre/instrumental.

6. **Build per-shot video prompts via the shared chain** — DO NOT hand-write prompts per shot. Instead, spawn ONE Agent with the canonical SYSTEM_PROMPT at [`../common/video-prompt-library/system-prompt.md`](../../common/video-prompt-library/system-prompt.md):

• Load the SYSTEM_PROMPT verbatim from that file.
• Fill `buildUserMessage(opts)` per the shape in the same file:
• Mode: `i2v` (default — when carousel slides / poster frames are present) or `t2v` (script-from-scratch).
• For i2v: pass each source frame's `image_url` + a one-line summary of the in-image overlay text per shot (the LLM uses it to choose which one motion fits the slide's rhetoric, then strips it from the output prompt).
• For t2v: pass the screenplay beats per shot.
• Always pass the character-identity marker (8-15 words) and the resolved video-style entry.
• The Agent returns ONE JSON object `{"shots":[{"index":N,"prompt":"...","kwargs":{...}}]}` — all N shots in a single call. Per-shot subagent calls break identity consistency, just like in the carousel chain.
• Append each `shots[i].prompt` + `shots[i].kwargs` to `plan.json` (single canonical path, overwrite — don't proliferate `plan-v1.json`).

The SYSTEM_PROMPT encodes the full discipline: i2v 11 rules (2-sentence cap, 80-word cap, single motion verb, identity front-loading, global lock sentence verbatim, no rhetorical adjectives, no punitive labels, contact-motion subject-anchored not target-anchored, etc.) and the t2v cinematic template. The human-readable rationale + worked before/after examples live in the sibling `video-prompt` skill's i2v-prompting reference document (at `../video-prompt/references/`). When the two files conflict, the SYSTEM_PROMPT wins — that doc is the rationale, not the authority.

7. **Build music prompt** based on music-style library entry:

• Suno: Style of Music box + Lyrics box (instrumental: empty/structured-tags-only)
• Lyria: pro