video-gen

Video generation and multi-scene production via fal.ai. Two modes: light (fire-and-forget) and project (interactive pipeline with gates).

Scripts: ./scripts/generate.py, ./scripts/preview.py, ./scripts/project_init.py, ./scripts/project_state.py, ./scripts/decompose.py, ./scripts/keyframe.py, ./scripts/clip.py, ./scripts/assemble.py, ./scripts/character_sheet.py Output dir: ./output/

Setup

export FAL_KEY="your-fal-ai-key"

• Claude Code: copy this skill folder into .claude/skills/video-gen/
• Codex CLI: append this SKILL.md content to your project's root AGENTS.md

For the full installation walkthrough (prerequisites, API keys, verification, troubleshooting), see references/installation-guide.md.

Credential management

Three tiers for managing the FAL_KEY environment variable:

1. Vault skill (recommended): If you have a vault or secret-management skill, store the key there and export it before running scripts. Example: export FAL_KEY=$(vault get FAL_KEY)
2. Custom secret manager: Use your team's preferred secret manager (1Password CLI, AWS Secrets Manager, etc.)
3. Plain export: export FAL_KEY='your-fal-ai-key' in your shell profile

For project mode (keyframes + character sheets): also need image-gen peer skill.

Staying Updated

This skill ships with an UPDATES.md changelog and UPDATE-GUIDE.md for your AI agent.

After installing, tell your agent: "Check UPDATES.md in the video-gen skill for any new features or changes."

When updating, tell your agent: "Read UPDATE-GUIDE.md and apply the latest changes from UPDATES.md."

Follow UPDATE-GUIDE.md so customized local files are diffed before any overwrite.

Decision Tree

Need video?
├── Quick one-off clip? ─────────── Light Mode (generate.py)
│   Single prompt, single output, no state
│
└── Multi-scene story/production? ── Project Mode
    ├── New project? ─────────────── project_init.py → G0
    ├── Existing project? ────────── project_state.py --status
    └── Resume at gate? ──────────── Check state, pick up where left off

Quick Reference

Light Mode

# Generate with default model (ltx-2.3)
python ./scripts/generate.py \
  --prompt "A red fox running through snow" \
  --output ./output/

# Generate with specific model and settings
python ./scripts/generate.py \
  --prompt "Tokyo skyline at sunset with dramatic clouds" \
  --model kling-v3 \
  --mode t2v \
  --duration 10 \
  --resolution 1080p \
  --aspect 16:9

# Image-to-video generation
python ./scripts/generate.py \
  --prompt "The character starts walking forward" \
  --mode i2v \
  --image ./path/to/keyframe.png \
  --model veo-3

# Quick preview (uses LTX fast, cheapest)
python ./scripts/preview.py \
  --prompt "Test scene" \
  --mode t2v

Project Mode

# Initialize new project
python ./scripts/project_init.py \
  --name noir-detective \
  --scenes 5 \
  --output-dir ./projects \
  --style "cinematic, moody, film noir" \
  --tier standard \
  --logline "A detective investigates in a cyberpunk city"

# Check project status
python ./scripts/project_state.py --project ./projects/noir-detective

# Generate keyframe for scene
python ./scripts/keyframe.py \
  --project ./projects/noir-detective \
  --scene 1 \
  --style-keywords "cinematic, moody"

# Generate video clip for scene
python ./scripts/clip.py \
  --project ./projects/noir-detective \
  --scene 1 \
  --model kling-v3 \
  --duration 8

# Assemble final video
python ./scripts/assemble.py \
  --clips-dir ./projects/noir-detective/scenes \
  --output ./projects/noir-detective/output/final.mp4

Light Mode

Model Selection

What do you need?
├── Fast drafts + budget? ──────────── ltx-2.3 (fast) $0.04/s
├── Cinematic quality? ─────────────── kling-v3 $0.168/s
├── Dialogue/lip sync? ─────────────── veo-3 $0.20-0.40/s
├── Long clips (>10s)? ─────────────── sora-2 (up to 25s)
├── Budget with audio? ─────────────── wan $0.05-0.10/s
├── Anime/stylized? ────────────────── hailuo $0.045-0.08/s
└── Physics accuracy? ──────────────── cosmos $0.20/video

Script Reference: generate.py

Script Reference: preview.py

# Preview existing video file
python ./scripts/preview.py /path/to/video.mp4

# Generate and preview (uses LTX fast, $0.04/s)
python ./scripts/preview.py \
  --prompt "Quick test scene" \
  --mode t2v \
  [--image path] \
  [--output path]

Output JSON Contract

{
  "success": true,
  "file": "/abs/path/to/20260308-143052-t2v-red-fox-snow.mp4",
  "model": "ltx-2.3",
  "mode": "t2v",
  "duration_sec": 8,
  "resolution": "1080p",
  "cost_usd": 0.32,
  "seed": 42,
  "fal_request_id": "abc123"
}

Duration Constraints

Cost Quick Reference

Project Mode

Gate Pipeline (G0-G5)

Detailed Gate Instructions

G0 - Project Setup: Use project_init.py to create project folder with scenes/, characters/, audio/, output/ subdirectories, manifest.md template, and state.json tracking file. Define style, tier, budget, aspect ratio.

G1 - Shot Prompts: Use decompose.py to generate LLM prompt for story decomposition. Coordinator runs this against LLM to get scene-by-scene breakdown. Update state.json with scene prompts.

G2 - Reference Images: Run keyframe.py for each scene to generate keyframe images. These anchor the visual style and serve as I2V inputs. Requires image-gen peer skill.

G3 - Sequence Review: Use project_state.py --lock-sequence to freeze the shot sequence. No more scene additions/deletions after this gate. Review keyframes before locking.

G4 - Video Generation: Run clip.py for each scene to generate video clips using keyframes as I2V input. Outputs shot_NN.mp4 files in scenes/NN-name/ directories.

G5 - Assembly: Use assemble.py to discover clips and combine them with ffmpeg. Supports crossfades, audio overlay, and story.json metadata for timing.

Script Reference: project_init.py

Script Reference: project_state.py

# Display status table
python ./scripts/project_state.py --project /path/to/project

# Update gate status
python ./scripts/project_state.py \
  --project /path \
  --scene 1 \
  --gate prompt \
  --status locked \
  --path scenes/01-intro/prompt.md

# Add new scene
python ./scripts/project_state.py \
  --project /path \
  --add-scene \
  --scene-name climax \
  --scene-number 6

# Lock sequence (G3)
python ./scripts/project_state.py --project /path --lock-sequence

# Invalidate downstream gates
python ./scripts/project_state.py \
  --project /path \
  --scene 1 \
  --invalidate prompt

Script Reference: decompose.py

Script Reference: keyframe.py

Script Reference: clip.py

Script Reference: assemble.py

Script Reference: character_sheet.py

File Structure

project-name/
├── manifest.md                    # Human-readable project summary
├── state.json                     # Machine state tracking (G0-G5)
├── story.json                     # Scene decomposition (G1 output)
├── characters.json                # Character definitions
├── scenes/
│   ├── 01-intro/
│   │   ├── prompt.md              # Scene description
│   │   ├── keyframe.png           # Reference image (G2)
│   │   └── shot_01.mp4           # Generated clip (G4)
│   ├── 02-conflict/
│   │   ├── prompt.md
│   │   ├── keyframe.png
│   │   └── shot_02.mp4
│   └── ...
├── characters/                    # Character reference sheets
│   ├── detective-front.png
│   ├── detective-profile.png
│   └── ...
├── audio/                         # Voiceover and music
└── output/                        # Final assembled videos
    └── final.mp4

Token Efficiency Rules

1. Coordinator context management: Load only current gate's requirements, not full project history
2. Scene isolation: Each scene script operates independently with minimal cross-references
3. State checkpoints: Use state.json as single source of truth, not file system scanning
4. Selective loading: Scripts load only required JSON sections, not entire project state

Going Back / Cascade Rules

• Upstream change: Invalidates all downstream gates automatically
• Prompt change (G1): Invalidates G2 (keyframes), G4 (clips), G5 (assembly)
• Keyframe change (G2): Invalidates G4 (clips), G5 (assembly)
• Sequence lock (G3): Prevents scene additions/deletions, allows content changes
• Clip regeneration (G4): Invalidates G5 (assembly) only

Style Control (3 Layers)

1. Project tier: Maps to default models (budget→ltx-2.3, standard→kling-v3, premium→kling-v3, ultra→veo-3)
2. Project style keywords: Applied to all keyframes and clips automatically
3. Per-scene overrides: --style-keywords flag on keyframe.py/clip.py for scene-specific variations

Dependencies

Required for Light Mode

• Python 3.10+
• requests library: pip install requests
• fal.ai API key (FAL_KEY environment variable)

Required for Project Mode (additional)

• ffmpeg + ffprobe (video assembly): install via system package manager
• image-gen peer skill (keyframes + character sheets)

Image-gen Peer Resolution

Scripts resolve image generation dependency in this order:

1. Environment override: IMAGE_GEN_SCRIPT=/path/to/generate.py (explicit path)
2. Auto-discovery: ../image-gen/scripts/generate.py (peer skill in fieldwork layout)
3. Actionable error: "Image generation requires the image-gen skill. Install it as a peer skill or set IMAGE_GEN_SCRIPT env var."

Anti-Patterns

Error Handling

Bundled Resources Index