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

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 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:

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