/video-prompt

name: video-prompt
description: "Write prompts for 20+ frontier AI video generators (Veo 3.1 + audio, Sora 2 + cameos, Kling 3.0, Runway Gen-4 / Aleph / Act-One, Luma Ray 3, Pika 2.2, Hailuo 02, LTX-2, Wan 2.2, Seedance). Modes: T2V / I2V / V2V / extend / multi-shot / dialogue+audio. Use when: 'video prompt', 'animate this image', 'Kling/Veo/Sora/Runway prompt', 'dialogue scene'."

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

<objective> Write a tight, model-aware motion prompt for AI video generation. Output: one structured prompt string (beat-structured, with optional Dialogue / SFX / Ambient blocks, multi-shot blocks, or V2V single-verb instruction). This skill does NOT call the video model — it produces the text you paste into Veo / Sora / Kling / Runway / Luma / Pika / Hailuo / LTX / Hunyuan / Wan / Seedance / Higgsfield.

Use when the user wants a 4-15s clip from a still image (I2V), from text (T2V), as an edit of existing footage (V2V), as an extension of an existing clip, or as a multi-shot scene in one generation. Apply the **CHARACTER FIRST, CAMERA SECOND** law, beat-structure the motion, pick vocabulary the target model parses cleanly, add dialogue / SFX / ambient blocks for native-audio models, lock identity via reference labels for cameo / element / Soul ID models.

This skill does NOT:

• generate the video itself (that's the model)
• generate the still image (use `image-prompt`)
• write a full multi-scene storyboard (use a storyboarding tool / separate skill)
• write traditional film screenplays (use `essay-write` or `prose-edit`)

</objective>

ROLE

Read request → identify subject + action + emotional beat → pick mode (T2V / I2V / V2V / extend / multi-shot) → pick target model from `references/models/_index.md` → apply CHARACTER FIRST law → beat-structure the motion → add camera move from exact vocabulary → add audio block if model supports it → return motion prompt + optional endFrame / reference list.

PIPELINE

1. **Clarify the shot.** Need to know:

• Mode: T2V (text-only) / I2V (from a still) / V2V (edit existing footage) / extend (continue a clip) / multi-shot (several shots in one prompt).
• What action happens in the 4-15 seconds? (the model can't extrapolate offscreen).
• Emotional beat: `hook` / `tension` / `climax` / `breathing` / `resolution` / `setup`.
• Target model (default by mode — see `references/models/_index.md`).
• Dialogue or sound design? (only if model supports native audio: Veo 3.1, Sora 2, LTX-2).
• POV or third-person?
• Identity references attached? (cameos / elements / Soul ID).

2. **Apply CHARACTER FIRST.** For ANY shot with character action — start motion prompt with what the character does (body parts, frequency, timing), NOT with a camera move. See `references/beat-structure.md`.

3. **Beat-structure the motion** (mandatory for action shots):

• Beat 1 (0% → 30%): initiating action / setup
• Beat 2 (30% → 70%): escalation / dialogue delivery
• Beat 3 (70% → 100%): resolution / reaction / final pose

See `references/beat-structure.md` for templates per emotional beat AND per dialogue-bearing model.

4. **Pick camera move from exact vocabulary.** Use named terms (`slow dolly push-in`, `orbit 180`, `whip pan`, or named Higgsfield preset like `Crash Zoom`) — NOT vague "camera moves forward". See `references/camera-vocabulary.md`.

5. **Mode-specific rules.**

• **T2V**: 6-part build with full scene description.
• **I2V**: motion-over-still — don't re-describe the source frame; see `references/i2v-prompting.md`.
• **V2V**: single action verb (Add / Remove / Replace / Relight / Re-angle / Restyle / Extend); see `references/v2v-editing.md`.
• **extend**: Veo scene-extend / Kling Elements chain — see `references/multi-shot.md`.
• **multi-shot**: Sora 2 / Seedance — Shot 1/2/3 blocks with shared style anchor — see `references/multi-shot.md`.

6. **Add audio block** if model supports native audio (Veo 3.1, Sora 2, LTX-2) — Dialogue / SFX / Ambient layers, prosody adverbs, lip-sync rules. See `references/audio-prompting.md`. ≤5 total audio elements per 8s clip.

7. **Add per-model rules** from `references/models/<tier>.md`:

• Kling 3.0 / Elements: temporal flow required, 4 refs for Elements
• Veo 3.1: more flexible structure; audio + lip-sync triggered by `Character: "line"` syntax
• Sora 2: NL paragraph + audio + multi-shot transitions (`new shot:`, `cut to:`, `match cut on`)
• Runway Gen-4 / Aleph: short clips; Aleph = single-verb V2V edit, 5s cap
• Higgsfield: named camera presets, max 3 stacked; Soul ID for character lock

8. **Identity references** (if cameos / elements / Soul ID / HunyuanCustom):

• Name the reference: `[ref:Sarah]`, `[ref:Marcus]`
• Do NOT re-describe locked physical traits (hair, face, body)
• See `references/identity-references.md`.

9. **Apply pacing mode** — narrative / action / comedy / documentary / timelapse / dialogue-scene / music-video. See `references/pacing-modes.md`.

10. **Strip forbidden phrases** that cause frozen-pose output. Replace with body-part-specific, timed, repeated actions. See `references/beat-structure.md` § Forbidden phrases.

11. **Output.**

• The motion prompt as one fence-block (paste-ready), with Dialogue / SFX / Ambient blocks inline if audio mode
• `endFrameDescription` only if shot ends in a DIFFERENT composition from start
• For multi-shot: each shot block fenced separately or in one block
• For V2V: just the single-verb instruction
• 1-line note: model + mode + key conventions + pacing mode

12. **(Optional) Execute via API.** If `--execute` was passed AND the env var(s) for the chosen model are set, also run `python3 scripts/run.py --model <model> --prompt-file <generated.txt>`. Video gens are long-running — the runner polls and prints progress to stderr. ALWAYS confirms cost (any video is over the $0.10 threshold) unless `--yes`. Result lands in `./g