Reel Builder

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

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

1. 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)

1. Resolve video style — see references/style-resolution.md:

• --style : load common/style-library/video/.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.

1. Resolve music style — see references/music-pairing.md:

• --music-style : load common/style-library/music/.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.

1. 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.

1. 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 SYSTEMPROMPT 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 SYSTEMPROMPT wins — that doc is the rationale, not the authority.

1. Build music prompt based on music-style library entry:

• Suno: Style of Music box + Lyrics box (instrumental: empty/structured-tags-only)
• Lyria: prompt + key + BPM + (optional lyrics)
• Eleven: single prompt with bracketed cues + duration
• Stable Audio: free-text instrumental composition

1. Estimate cost — sum video shots + music. Confirm batch if >$0.10 and not --yes.

1. Execute in parallel:

• Video shots: parallelism N (default 2 — video calls are 30-90s each, more concurrency stresses rate limits)
• Music: 1 call running concurrently
• All async via JobHandle + poll-with-timeout
• Manifest updated after each completion

1. ffmpeg stitch (only if all shots succeeded; partial failures stop here for safety):

• Concat N shots in order: ffmpeg -f concat -c copy → shots-concat.mp4
• Mix music: replace audio track with music.mp3, fade-out 0.5s at end → with-music.mp4
• (If --captions on) Burn captions via drawtext filter per timed entry → final.mp4

1. Output:

`` ./generated/reel// final.mp4 # the finished reel (15s typically) shots/ shot-1.mp4 shot-2.mp4 shot-3.mp4 music.mp3 script.md # screenplay + captions + shot prompts manifest.json # for --resume style-used.md # video style + music style snapshot ``

stdout last lines: `` Reel: ./generated/reel//final.mp4 Components: ./generated/reel//{shots/, music.mp3, script.md} ``

MODES

Input

• reel-builder --topic "" — draft script then generate
• reel-builder --research — ingest research brief, derive script
• reel-builder --script-file — use pre-written screenplay (see references/shot-planning.md for format)

Structure

• --shots N — 1-5, default 3
• --shot-duration S — seconds per shot, default 5 (cap per-provider varies: Veo 8s, Sora 10s, Kling 8s)
• --aspect vertical|square|horizontal — 9:16 / 1:1 / 16:9, default vertical
• --captions on|off — burn timed captions via ffmpeg drawtext, default on

Style

• --style auto| — video directorial style (see common/style-library/video/_index.md)
• --music-style auto| — music genre preset (see common/style-library/music/_index.md)
• --style-mod "" — append tweak to video anchor

Providers

• --video-provider auto|veo-3-1|veo-3-1-fast|veo-3-1-lite|kling-3|runway-gen-4-5|fal-video — video API
• --music-provider auto|suno-v5-5|stable-audio-2-5|eleven-music|lyria-3-pro — music API
• --video-instrumental on|off — for music: pure instrumental (default on for reels — voiceover is out of scope v1)

Execution

• --execute — actually generate (else returns plan + prompts)
• --output — custom output path
• --parallelism N — concurrent shot calls (default 2, max 4)
• --yes — skip cost confirmation
• --resume — pick up from manifest

Inspection

• --prompts-only — assemble script + per-shot prompts + music prompt, save to script.md, exit
• --cost-only — print total estimated cost, exit
• --check — validate env vars + library files + ffmpeg available

ffmpeg gating

• If ffmpeg is not detected on PATH:
• With --execute: still generates shots + music, then prints the ffmpeg concat command for the user to run manually.
• --check: reports the missing binary and the manual install command (brew install ffmpeg / apt-get install ffmpeg).
• SKILLS_SKIP_FFMPEG=1: don't attempt ffmpeg even if installed. Outputs stay separate.

REFERENCES (load on demand)

| File | When to load | |---|---| | [references/shot-planning.md](references/shot-planning.md) | Step 2 — shot count templates, timing, screenplay format, dialogue rules | | [references/style-resolution.md](references/style-resolution.md) | Step 3 — directorial style auto-pick, Inspired by vs anchor, override semantics | | [references/music-pairing.md](references/music-pairing.md) | Step 4-7 — music genre auto-pick from video style, BPM matching, instrumental rules, per-provider prompt mapping | | [references/model-picker.md](references/model-picker.md) | Step 5 — video + music provider decision trees, capability matrix, cost preview | | [references/ffmpeg-stitch.md](references/ffmpeg-stitch.md) | Step 10 — concat, audio mix, fade-out, burn-in caption filter syntax, ffmpeg gating | | [references/captions.md](references/captions.md) | Caption writing — placement, line length, timing, accessibility | | [references/troubleshoot.md](references/troubleshoot.md) | When shots fail, music doesn't match, ffmpeg errors, sync issues |

EXAMPLES

See [examples/before-after.md](examples/before-after.md) — 3 calibration runs: 3-shot vertical reel from a topic with Suno music (Veo 3.1 + Suno v5.5), 1-shot atmospheric reel with Stable Audio (Sora 2 + Stable Audio), 4-shot product reel from research brief with Kling 3.0 + Lyria 3 Pro.

CONSTRAINTS

• One video provider for all shots. Mixing Veo / Sora / Kling across shots breaks the look. Lock per-reel.

• One music track per reel. Not one per shot. The music plays under the whole sequence.

• Music duration ≥ total video duration. ffmpeg -shortest clips music to video length, so generate music a bit longer than reel. Default: reel_duration + 2s of music.

• No voiceover / TTS in v1. If the user asks "narrate this", suggest pasting voiceover separately via ElevenLabs TTS UI + manual mix. Voiceover orchestration with ducking is v2.4.0+.

• Hard cuts only. ffmpeg concat does straight cuts. No dissolves / wipes / fancy transitions.

• First 1-2 seconds carry the hook. Reel feeds scroll fast — if the opening doesn't land, audience leaves. The shot-planning reference enforces this in script structure.

• 9:16 vertical is the default. 95%+ of reels are vertical. Override with --aspect square|horizontal only when targeting non-vertical platforms.

• ffmpeg failure → graceful: if ffmpeg fails (codec mismatch, exotic edge case), save shots + music separately and print the manual ffmpeg command. Don't lose the work.

• Cost confirm ONCE per reel. Sum across shots + music. Total typically $2-5; default budget cap is $4.00.

• Captions stay under 8 words per line. Mobile reading speed = ~3 words/sec. Don't stuff a paragraph into 5 seconds.

• Never print API keys. Mask in errors.

• Output dir is ./generated/reel// by default. Slug from topic, max 40 chars, kebab-case.

• --prompts-only is the safety dry-run. Each reel is $2-5 — always run --prompts-only first if iterating on script/style.

• Manifest updates after every async completion. --resume picks up succeeded shots / music; only re-runs failed components.

• --resume cannot resume mid-ffmpeg. ffmpeg stitch is final step. If stitch fails, components are saved; user re-runs --resume which will re-do only the ffmpeg part.

• Style library is source of truth. Don't write free-form directorial descriptions in this skill. If --style auto and library is thin for the genre, suggest a closest fit + --style-mod "".

INVOCATION HINTS

When the user says any of:

• "reel about / on X", "Instagram reel", "TikTok video", "YouTube short"
• "short video on Y", "15-second video", "30-second video"
• "make a TikTok / reel / shorts about Z"
• "vertical video on Q"

RU triggers:

• «рил про X», «короткое видео про Y»
• «TikTok / Reels / Shorts про Z»
• «15-секундное видео», «30-секундный рил»
• «вертикальное видео про Q»

Defaults: --shots 3 --shot-duration 5 --aspect vertical --captions on --video-provider auto --music-provider auto --video-instrumental on. Without --execute, returns plan + prompts; with --execute, generates the MP4.

This skill is downstream of research-brief and is the most expensive in the collection — always recommend --prompts-only for first iteration. If the user only needs ONE shot (not a stitched reel), suggest video-prompt --execute instead — saves the orchestration overhead.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Mikefluff
• Source: Mikefluff/skills
• License: MIT
• Homepage: https://www.npmjs.com/package/@mikefluff/skills

Install and usage instructions live in the source repository linked above.