video-scriptwriting

---
name: video-scriptwriting
version: 0.1.0
description: >
  Use this skill when writing scripts for programmatic videos, planning scene
  structure and timing, creating storyboards in YAML format, calculating frame
  counts from duration, or interviewing users about video requirements. Triggers
  on video script, storyboard, scene planning, narration writing, video pacing,
  and structured video content planning.
tags: [scriptwriting, video-script, storyboard, yaml, content-planning, pacing, strategy, writing]
category: video
recommended_skills: [video-creator, remotion-video, video-audio-design, copywriting]
platforms:
  - claude-code
  - gemini-cli
  - openai-codex
license: MIT
maintainers:
  - github: maddhruv
---

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

2. **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.

3. **Visual-first** - Write the `visual` field before `narration`. Narration
   should complement visuals, never redundantly describe what is on screen.

4. **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.

5. **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

```yaml
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

```yaml
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

```yaml
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 building dashboards from scratch."
    visual: "Bold text on vibrant gradient background"
    animation: "text slams in from top over 8 frames, screen shakes for 4 frames"
    music:
      track: "electronic-pulse"
      volume: 0.5
      duck: true
    sfx:
      - type: "impact-hit"
        at: "0.2s"
        duration: "0.3s"
    transition_to_next: "hard-cut"

  - id: demo
    duration: "12s"
    frames: 360
    narration: "Type what you need. Acme builds it live."
    visual: "Screen recording: typing a prompt, dashboard generating in real time"
    animation: "typing for 120 frames, dashboard builds over remaining 240 frames"
    music:
      track: "electronic-pulse"
      volume: 0.3
      duck: true
    sfx:
      - type: "keyboard-typing"
        at: "0.5s"
        duration: "4s"
    transition_to_next: "hard-cut"

  - id: result
    duration: "8s"
    frames: 240
    narration: "Fully interactive. Real-time data. Ready to share."
    visual: "Finished dashboard with hover interactions, data updating live"
    animation: "cursor hovers triggering tooltips, data refreshes at frame 120"
    music:
      track: "electronic-pulse"
      volume: 0.3
      duck: true
    sfx: []
    transition_to_next: "hard-cut"

  - id: cta
    duration: "7s"
    frames: 210
    narration: "Try free at acme.dev."
    visual: "CTA text large and centered, URL below, brand gradient background"
    animation: "text scales up from 0 to full size over 15 frames, holds"
    music:
      track: "electronic-pulse"
      volume: 0.5
      duck: false
    sfx: []
    transition_to_next: "none"
```

### 4. Calculate frame counts from duration

```
Input:  duration = 60s, fps = 30
Output: total_frames = 1800

Scene breakdown:
  intro:     4s * 30 = 120 frames
  feature-1: 8s * 30 = 240 frames
  feature-2: 8s * 30 = 240 frames
  proof:     6s * 30 = 180 frames
  cta:       6s * 30 = 180 frames
  ---
  Sum: 32s = 960 frames (remaining 840 frames need more scenes)
```

Always verify the sum. If scenes do not add up, adjust or add scenes.

### 5. Write effective narration text

Rules:
- **Max 15 words per sentence** - longer cannot be read in time
- **Active voice, present tense** - "Acme builds your dashboard" not "will be built"
- **Match narration to visuals** - talk about what is on screen
- **One idea per scene** - do not cram two concepts into one line
- **Lead with benefit** - "Save 10 hours a week" not "Our time-tracking feature"
- **Include pauses** - empty narration (`""`) for breathing room
- **Reading speed** - roughly 2.5 words per second

| Bad | Good | Why |
|---|---|---|
| "Our product has been designed to help teams build dashboards faster" | "Build dashboards in minutes, not weeks." | Too long, passive |
| "Click on the plus button in the top right corner" | "Add a widget with one click." | Let the visual show location |
| "As you can see, the data updates in real time" | "Real-time data. Always current." | "As you can see" is filler |

### 6. Plan scene transitions

| Transition | When to use |
|---|---|
| `hard-cut` | Same topic, fast pacing, or jarring contrast |
| `cross-dissolve` | Smooth topic change, related content flowing |
| `fade-to-black` | End of section, dramatic pause, final scene |
| `wipe-left` / `wipe-right` | Before/after comparisons, timeline progression |
| `none` | Final scene of the video |

Rule: use at most 2 different transition types per video for consistency.

### 7. Revise a script based on feedback

1. Identify the feedback type: pacing, narration, visuals, structure, or tone
2. Locate affected scenes by `id` in the YAML
3. Apply changes to only the affected fields, preserve frame math
4. Revalidate: scene durations must still sum to total duration
5. Recalculate frames if any duration changed
6. Document what changed:

```yaml
# Revision: shortened intro from 6s to 4s per feedback (v2)
- id: intro
  duration: "4s"     # was 6s
  frames: 120        # was 180
```

---

## Anti-patterns / common mistakes

| Mistake | Why it is wrong | What to do instead |
|---|---|---|
| Writing narration before visuals | Drives video into talking-head territory | Write `visual` first, then narration to complement |
| Scenes longer than 12 seconds | Viewers lose attention, pacing feels sluggish | Break into two shorter scenes |
| Mismatched frame counts | Rendering engine produces wrong timing or crashes | Always compute `frames = duration * fps` and verify sums |
| Narration over 15 words/sentence | Cannot be read within scene duration | Split into shorter sentences |
| No hook in first 3 seconds | Social viewers scroll past, embedded viewers disengage | Open with bold statement, question, or visual surprise |
| Inconsistent transitions | Video feels choppy and amateurish | Use at most 2 transition types per video |
| Skipping the interview | Produces generic scripts that miss the mark | Always gather requirements first |
| Empty visual descriptions | Rendering engineer cannot build the scene | Be specific about layout, colors, motion, elements |

---

## Gotchas

1. **Frame count rounding** - When duration does not divide evenly (e.g., 3.5s
   at 24fps = 84 frames), round to nearest integer and adjust the last scene.
   Never leave fractional frames - rendering engines truncate or error.

2. **Narration timing overflow** - At 2.5 words/second, a 4s scene holds about
   10 words. Writing 20 words for a 4s scene means rushed narration or clipping.
   Always check word count against scene duration.

3. **Vertical vs horizontal resolution** - Social clips (TikTok, Reels, Shorts)
   use 1080x1920 (vertical). YouTube/website embeds use 1920x1080 or 3840x2160.
   Confirm distribution channel before setting resolution.

4. **Music ducking conflicts** - If every scene has `duck: true`, music volume
   constantly yo-yos. Use ducking only when narration is present. Scenes with
   empty narration should have `duck: false`.

5. **Total duration drift** - After revisions, scene durations often drift from
   target. Always re-sum all durations after any edit and compare against
   `meta.duration`.

---

## References

For detailed guidance on specific sub-topics, read the relevant file from the
`references/` folder:

- `references/interview-questions.md` - complete 30-question interview framework
  with follow-up trees, answer interpretation, and example briefs
- `references/pacing-guide.md` - deep-dive into pacing strategies per video type,
  hook techniques, CTA placement, and rhythm patterns

Only load a references file if the current task requires it - they are long and
will consume context.

---

## Companion check

> On first activation of this skill in a conversation: check which companion skills are installed by running `ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null`. Compare the results against the `recommended_skills` field in this file's frontmatter. For any that are missing, mention them once and offer to install:
> ```
> npx skills add AbsolutelySkilled/AbsolutelySkilled --skill <name>
> ```
> Skip entirely if `recommended_skills` is empty or all companions are already installed.