video-scriptwriting

When this skill is activated, always start your first response with the :pencil: emoji.

Video Scriptwriting

Video scriptwriting for programmatic video is the practice of planning, structuring, and writing scripts that translate directly into code-driven video production. Unlike traditional screenwriting, programmatic video scripts are structured data - every scene has an explicit duration, frame count, animation description, and narration text that a rendering engine can consume. This skill covers interviewing stakeholders, generating structured YAML scripts, calculating pacing and frame counts, writing narration, and revising scripts.

When to use this skill

Trigger this skill when the user:

• Wants to write a script for a programmatic or code-generated video
• Needs to plan scene structure, timing, or transitions for a video
• Asks about storyboard creation in a structured format (YAML, JSON)
• Wants to calculate frame counts from duration and FPS
• Needs help writing narration text for video scenes
• Asks about video pacing for different content types (demo, explainer, social)
• Wants to run an interview workflow to gather video requirements
• Needs to revise or restructure an existing video script

Do NOT trigger this skill for:

• Live-action filmmaking or traditional screenwriting
• Video editing software tutorials (Premiere, Final Cut, DaVinci Resolve)
• Audio-only content like podcasts or music production
• Still image design or static presentation slides

Key principles

1. Interview-driven - Run a structured interview (up to 30 questions across

7 categories) before generating a single scene. Never script from assumptions.

1. Structured output - Every script is valid YAML with a meta block and a

scenes array. Each scene has id, duration, frames, narration, visual, animation, music, sfx, and transition_to_next fields.

1. Visual-first - Write the visual field before narration. Narration

should complement visuals, never redundantly describe what is on screen.

1. Pacing awareness - Match scene count and per-scene duration to the video

type: social clips need 3-8s scenes; explainers can breathe with 5-12s scenes.

1. Narration-visual sync - Every narration line must match what is visible at

that moment. One idea per scene. Narration timing must fit the scene duration.

Core concepts

Interview framework

Gather requirements through 7 categories before writing:

| Category | Questions | Examples | |---|---|---| | Product/Subject | 5-7 | What is the product? Key features? Problem solved? Differentiator? | | Audience | 3-5 | Target viewer? Technical level? Pain points? | | Video Goals | 3-4 | Type (demo/explainer/social/announcement)? Duration? Channel? | | Tone & Style | 3-5 | Formal or casual? Energetic or calm? Reference videos? | | Assets | 3-5 | Logo? Screenshots? Brand colors? Fonts? | | Content | 4-6 | Key messages? Must-include features? CTA? Opening hook? | | Visual Preferences | 3-5 | Animation style? Color palette? Layout preferences? |

YAML script format

meta:
  title: "string - descriptive title"
  duration: "string - total duration (e.g. 60s)"
  type: "enum - demo | explainer | social | announcement"
  resolution: "string - e.g. 3840x2160, 1920x1080"
  fps: "number - 24, 30, or 60"
  audience: "string - who is watching"
  tone: "string - comma-separated descriptors"
  total_frames: "number - duration_seconds * fps"

scenes:
  - id: "string - unique kebab-case identifier"
    duration: "string - e.g. 4s, 8s"
    frames: "number - scene_duration_seconds * fps"
    narration: "string - max 15 words per sentence"
    visual: "string - what the viewer sees on screen"
    animation: "string - how elements move, with frame references"
    music:
      track: "string - music track name"
      volume: "number - 0.0 to 1.0"
      duck: "boolean - lower music during narration"
    sfx:
      - type: "string - sound effect name"
        at: "string - timestamp within scene"
        duration: "string - how long it plays"
    transition_to_next: "enum - hard-cut | cross-dissolve | fade-to-black | wipe-left | wipe-right | none"

Scene pacing by video type

| Video Type | Duration | Scenes | Per Scene | Notes | |---|---|---|---|---| | Product demo | 30-120s | 6-15 | 5-10s | Feature-focused, clear CTAs | | Explainer | 60-180s | 8-20 | 5-12s | Concept-heavy, more breathing room | | Social clip | 15-60s | 3-8 | 3-8s | Hook in first 3s, fast pacing | | Announcement | 15-45s | 3-6 | 4-8s | Punchy, single message focus |

Frame calculation

total_frames = duration_seconds * fps
scene_frames = scene_duration_seconds * fps
Example: 60s video at 30fps = 1800 total frames

| Duration | 24 fps | 30 fps | 60 fps | |---|---|---|---| | 4s | 96 | 120 | 240 | | 8s | 192 | 240 | 480 | | 30s | 720 | 900 | 1800 | | 60s | 1440 | 1800 | 3600 | | 90s | 2160 | 2700 | 5400 |

Always validate that scene frame counts sum to total_frames in meta.

Common tasks

1. Run the interview workflow

Walk through all 7 categories in sequence. Ask one at a time, summarize answers, then proceed. See references/interview-questions.md for the full 30-question framework. Compressed version for tight timelines uses 10 essential questions: Product name, key features, problem solved, target viewer, technical level, video type, duration, channel, key message, and CTA.

2. Generate a product demo script

meta:
  title: "Product Demo - Acme Dashboard"
  duration: "60s"
  type: demo
  resolution: 3840x2160
  fps: 30
  audience: "SaaS founders and product managers"
  tone: "professional, confident, minimal"
  total_frames: 1800

scenes:
  - id: intro
    duration: "4s"
    frames: 120
    narration: "Meet Acme - the dashboard that builds itself."
    visual: "Logo centered on warm off-white background, fades in from transparent"
    animation: "fade-in over 30 frames, hold for 90 frames"
    music:
      track: "upbeat-corporate"
      volume: 0.4
      duck: false
    sfx: []
    transition_to_next: "hard-cut"

  - id: feature-1
    duration: "8s"
    frames: 240
    narration: "Just describe what you need. Acme handles the rest."
    visual: "Browser mockup showing prompt input, text being typed"
    animation: "browser slides up from bottom over 20 frames, typing starts at frame 40"
    music:
      track: "upbeat-corporate"
      volume: 0.2
      duck: true
    sfx:
      - type: "keyboard-typing"
        at: "1.3s"
        duration: "3s"
    transition_to_next: "cross-dissolve"

  - id: feature-2
    duration: "8s"
    frames: 240
    narration: "Drag, drop, resize. Your layout, your rules."
    visual: "Dashboard editor with widgets being rearranged by cursor"
    animation: "cursor moves to widget at frame 30, drags to new position over 60 frames"
    music:
      track: "upbeat-corporate"
      volume: 0.2
      duck: true
    sfx:
      - type: "soft-click"
        at: "1.0s"
        duration: "0.2s"
    transition_to_next: "cross-dissolve"

  - id: cta
    duration: "6s"
    frames: 180
    narration: "Try Acme free at acme.dev. Build your first dashboard in minutes."
    visual: "CTA text centered with URL, subtle animated background gradient"
    animation: "text fades in over 20 frames, background gradient shifts slowly"
    music:
      track: "upbeat-corporate"
      volume: 0.4
      duck: false
    sfx: []
    transition_to_next: "fade-to-black"

Full demo scripts typically have 6-15 scenes. Expand by adding problem, social proof, pricing, and outro scenes following the same YAML structure.

3. Generate a social clip script

meta:
  title: "Acme in 30 Seconds"
  duration: "30s"
  type: social
  resolution: 1080x1920
  fps: 30
  audience: "Developers scrolling social feeds"
  tone: "energetic, punchy, modern"
  total_frames: 900

scenes:
  - id: hook
    duration: "3s"
    frames: 90
    narration: "Stop bu