video-scriptwriting
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.
video scriptwritingvideo-scriptstoryboardyamlcontent-planningpacingWhat is video-scriptwriting?
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.
video-scriptwriting
video-scriptwriting is a production-ready AI agent skill for claude-code, gemini-cli, openai-codex. 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.
Quick Facts
| Field | Value |
|---|---|
| Category | video |
| Version | 0.1.0 |
| Platforms | claude-code, gemini-cli, openai-codex |
| License | MIT |
How to Install
- Make sure you have Node.js installed on your machine.
- Run the following command in your terminal:
npx skills add AbsolutelySkilled/AbsolutelySkilled --skill video-scriptwriting- The video-scriptwriting skill is now available in your AI coding agent (Claude Code, Gemini CLI, OpenAI Codex, etc.).
Overview
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.
Tags
scriptwriting video-script storyboard yaml content-planning pacing
Platforms
- claude-code
- gemini-cli
- openai-codex
Related Skills
Pair video-scriptwriting with these complementary skills:
Frequently Asked Questions
What is video-scriptwriting?
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.
How do I install video-scriptwriting?
Run npx skills add AbsolutelySkilled/AbsolutelySkilled --skill video-scriptwriting in your terminal. The skill will be immediately available in your AI coding agent.
What AI agents support video-scriptwriting?
This skill works with claude-code, gemini-cli, openai-codex. Install it once and use it across any supported AI coding agent.
Maintainers
Generated from AbsolutelySkilled
SKILL.md
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
Interview-driven - Run a structured interview (up to 30 questions across 7 categories) before generating a single scene. Never script from assumptions.
Structured output - Every script is valid YAML with a
metablock and ascenesarray. Each scene hasid,duration,frames,narration,visual,animation,music,sfx, andtransition_to_nextfields.Visual-first - Write the
visualfield beforenarration. Narration should complement visuals, never redundantly describe what is on screen.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.
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
- Identify the feedback type: pacing, narration, visuals, structure, or tone
- Locate affected scenes by
idin the YAML - Apply changes to only the affected fields, preserve frame math
- Revalidate: scene durations must still sum to total duration
- Recalculate frames if any duration changed
- Document what changed:
# Revision: shortened intro from 6s to 4s per feedback (v2)
- id: intro
duration: "4s" # was 6s
frames: 120 # was 180Anti-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
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.
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.
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.
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 haveduck: false.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 briefsreferences/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.
References
interview-questions.md
Interview Questions Framework
Complete 30-question interview framework for gathering video requirements before writing a programmatic video script. Questions are organized by category with follow-up trees and interpretation guidance.
How to run the interview
- Ask one category at a time, in order
- Wait for answers before proceeding to the next category
- Summarize each category's answers before moving on
- Skip categories that are irrelevant (e.g., Assets for concept-only scripts)
- Total interview should take 10-15 minutes
- After all categories, produce a structured brief for confirmation
Category 1: Product/Subject (5-7 questions)
Core questions
What is the product, tool, or subject of this video?
- Follow-up if vague: "Can you give me a one-sentence elevator pitch?"
- Interpretation: Extract the product name and core category
What are the 3 most important features or aspects to highlight?
- Follow-up: "Which of these is the single most differentiating?"
- Interpretation: Rank features by priority for scene allocation
What problem does this product solve for its users?
- Follow-up: "How were users solving this problem before?"
- Interpretation: This becomes the "pain point" scene content
What makes this product different from alternatives?
- Follow-up: "Is there a specific competitor you want to contrast against?"
- Interpretation: Differentiators become emphasis moments in the script
Is there a tagline, slogan, or key phrase you use?
- Follow-up: "Should this appear as on-screen text or narration?"
- Interpretation: May become the hook or CTA text
What is the current stage? (launched, beta, pre-launch, major update)
- Interpretation: Affects tone - launched products can show real UI; pre-launch needs mockups
Are there any technical details the audience needs to understand?
- Follow-up: "Should we simplify these or keep them technical?"
- Interpretation: Determines technical depth of narration
Summary template
Product: [name]. Solves [problem] for [who]. Key features: [1], [2], [3]. Differentiator: [what]. Stage: [stage]. Tagline: [if any].
Category 2: Audience (3-5 questions)
Core questions
Who is the primary target viewer?
- Follow-up: "Job title, role, or persona name?"
- Interpretation: Drives tone, vocabulary level, and examples
What is their technical level?
- Options: Non-technical / Semi-technical / Developer / Expert
- Interpretation: Non-technical = benefit-focused, no jargon. Developer = can show code.
What pain points or frustrations do they experience?
- Follow-up: "Which pain point is the most emotionally charged?"
- Interpretation: The strongest pain point often becomes the hook
What would make them share this video?
- Interpretation: Identifies the "aha moment" that should be most prominently featured
Are there secondary audiences to consider?
- Interpretation: Secondary audience may need a brief nod but should not dilute the primary message
Summary template
Primary audience: [role/persona]. Technical level: [level]. Key pain point: [pain]. Shareability hook: [what].
Category 3: Video Goals (3-4 questions)
Core questions
What type of video is this?
- Options: Product demo / Explainer / Social clip / Announcement / Tutorial
- Interpretation: Directly sets pacing template and scene count
What is the target duration?
- Follow-up if unsure: suggest based on type (demo: 30-120s, social: 15-60s)
- Interpretation: Sets total_frames and constrains scene count
Where will this video be distributed?
- Options: Website hero / YouTube / LinkedIn / Twitter/X / TikTok / Instagram / Internal / Email
- Interpretation: Determines resolution (vertical vs horizontal) and pacing expectations
What should the viewer do after watching?
- Follow-up: "Is there a specific URL, signup, or action?"
- Interpretation: Becomes the CTA scene content
Summary template
Type: [type]. Duration: [Xs]. Channel: [where]. CTA: [action + URL].
Category 4: Tone & Style (3-5 questions)
Core questions
What tone should the video have?
- Spectrum: Formal <-> Casual, Energetic <-> Calm, Playful <-> Serious
- Interpretation: Affects narration word choice, music selection, animation speed
Are there reference videos you like the style of?
- Follow-up: "What specifically did you like about them?"
- Interpretation: Extract concrete style elements (pacing, color, animation)
Should there be a human narrator voice or text-only?
- Follow-up if narrator: "Male, female, or neutral? Any accent preference?"
- Interpretation: Text-only scripts need more on-screen text; narrated scripts need pacing for speech
How fast should the pacing feel?
- Options: Relaxed / Medium / Fast / Frenetic
- Interpretation: Maps to per-scene duration choices within the type's range
Any styles or trends to avoid?
- Interpretation: Adds to the anti-pattern list for this specific project
Summary template
Tone: [descriptors]. Pacing: [speed]. Voice: [narrator/text]. Reference: [if any].
Category 5: Assets (3-5 questions)
Core questions
Do you have a logo in SVG or PNG format?
- Follow-up: "Any usage rules (minimum size, clear space)?"
- Interpretation: Logo appears in intro and outro scenes
Are there screenshots, screen recordings, or mockups available?
- Follow-up: "Are these current or do they need updating?"
- Interpretation: Real screenshots make demos more credible than illustrations
What are the brand colors? (hex codes preferred)
- Follow-up: "Primary, secondary, and accent colors?"
- Interpretation: Sets the color palette for backgrounds, text, and accents
What fonts does the brand use?
- Follow-up: "Web-safe alternatives if custom fonts are unavailable?"
- Interpretation: Typography choices for all on-screen text
Any existing brand motion guidelines or animation library?
- Interpretation: Constrains animation choices to match existing brand motion
Summary template
Logo: [yes/no, format]. Screenshots: [yes/no]. Colors: [hex codes]. Fonts: [names]. Motion guidelines: [yes/no].
Category 6: Content (4-6 questions)
Core questions
What is the single most important message the viewer should take away?
- Interpretation: This message appears in at least 2 scenes (hook + CTA)
Which features or aspects must be shown, no matter what?
- Follow-up: "In what order of importance?"
- Interpretation: Each must-show feature gets its own scene
What is the call to action?
- Follow-up: "Exact URL, button text, or next step?"
- Interpretation: Final or penultimate scene content
Do you have an idea for the opening hook?
- Follow-up if no: suggest 3 hook options based on gathered info
- Interpretation: First 3 seconds of the video
Additional questions (if time allows)
- "Are there any claims that need disclaimers or caveats?"
- "Should we mention pricing or keep it out?"
- "Any seasonal or time-sensitive elements?"
Summary template
Key message: [message]. Must-show: [features]. CTA: [action + URL]. Hook idea: [hook]. Disclaimers: [if any].
Category 7: Visual Preferences (3-5 questions)
These questions are asked last because earlier answers inform better defaults.
- Animation style preference? (Smooth/eased, Snappy/spring, Minimal/subtle)
- Color palette beyond brand colors? (Dark mode, light mode, gradients, flat)
- Layout preference? (Centered, split-screen, full-bleed, asymmetric)
- Any specific visual elements to include? (Icons, illustrations, 3D, photos)
- Screen recording style? (Full browser, app window only, cropped to feature)
Generating the brief
After completing all categories, compile answers into a structured brief:
brief:
product:
name: "Acme Dashboard"
problem: "Building dashboards takes weeks of developer time"
differentiator: "AI-generated layouts from natural language prompts"
tagline: "Dashboards that build themselves"
stage: "launched"
audience:
primary: "SaaS founders and product managers"
technical_level: "semi-technical"
key_pain: "Wasting engineering time on internal tools"
goals:
type: "demo"
duration: "60s"
channel: "website-hero"
cta: "Try free at acme.dev"
tone:
descriptors: "professional, confident, minimal"
pacing: "medium"
voice: "male narrator, neutral accent"
assets:
logo: true
screenshots: true
colors: ["#1a1a2e", "#16213e", "#0f3460", "#e94560"]
fonts: ["Inter", "JetBrains Mono"]
content:
key_message: "Build production dashboards in minutes, not weeks"
must_show: ["AI prompt input", "drag-and-drop editor", "real-time data"]
hook: "What if your dashboard could build itself?"
visual:
animation_style: "smooth"
palette: "dark mode with accent pops"
layout: "centered with browser mockups"Present this brief to the user for confirmation before generating the script. Any changes at this stage are much cheaper than revising a completed script.
Adapting the interview
- Repeat clients: Skip Asset and Visual Preference categories; reuse from last project
- Tight timelines: Compress to 10 essential questions (1, 2, 3, 8, 9, 13, 14, 15, 27, 29)
- Multiple stakeholders: Run the interview with the primary decision maker, then share the brief with others for feedback before scripting
- Vague answers: Offer 2-3 concrete options rather than asking open-ended follow-ups
pacing-guide.md
Pacing Guide
Deep-dive into pacing strategies for programmatic video scripts. Covers scene duration distributions, hook techniques, CTA placement, rhythm patterns, and type-specific guidance for maintaining viewer attention.
The attention curve
Viewer attention follows a predictable pattern:
Attention
^
| * *
| * * * *
|* * * *
| * * * *
| * * * * * *
| * * * * * *
| * * * * *
| * *
+---------------------------------> Time
Hook Body CTA Outro- Seconds 0-3: Peak attention - the hook must land here
- Seconds 3-15: Gradual decline - establish credibility quickly
- Mid-video: Lowest attention - use visual variety to re-engage
- Pre-CTA: Attention rises if content earned it - deliver the payoff
- CTA: Brief spike - viewer decides to act or leave
- Outro: Rapid drop - keep it short
Design your scene pacing to match this curve.
Pacing by video type
Product demo (30-120s)
Goal: Show the product doing its thing. Let the UI speak.
| Section | % of Duration | Purpose |
|---|---|---|
| Hook | 5-8% | Bold claim or question |
| Problem | 8-12% | Pain point the audience feels |
| Feature showcase | 50-60% | 3-5 features, each in its own scene |
| Social proof | 8-10% | Logos, numbers, testimonial |
| CTA | 8-12% | Clear action with URL |
| Outro | 5-8% | Logo and tagline |
Scene duration range: 5-10 seconds per scene
Pacing rhythm: Medium. Let each feature breathe but do not linger. Cut to the next feature the moment the current one is understood.
Example scene distribution for 60s demo:
intro: 4s (7%)
problem: 6s (10%)
feature-1: 8s (13%)
feature-2: 8s (13%)
feature-3: 8s (13%)
proof: 6s (10%)
pricing: 8s (13%)
cta: 6s (10%)
outro: 6s (10%)Explainer (60-180s)
Goal: Teach a concept. Move from problem to solution to benefit.
| Section | % of Duration | Purpose |
|---|---|---|
| Hook | 4-6% | Provocative question or surprising fact |
| Pain/Problem | 10-15% | Build empathy for the viewer's situation |
| Solution intro | 8-10% | Name the solution and its core promise |
| How it works | 30-40% | 3-5 steps, each clearly illustrated |
| Benefits | 10-15% | Concrete outcomes and improvements |
| Social proof | 5-10% | Credibility markers |
| CTA | 5-8% | Specific next step |
| Outro | 4-6% | Brand close |
Scene duration range: 5-12 seconds per scene
Pacing rhythm: Slower than demo. Give concepts time to land. Use visual metaphors and animations to make abstract ideas concrete.
Example scene distribution for 90s explainer:
hook: 5s (6%)
pain-point: 10s (11%)
intro-solution: 8s (9%)
how-1: 10s (11%)
how-2: 10s (11%)
how-3: 10s (11%)
benefit-1: 7s (8%)
benefit-2: 7s (8%)
proof: 8s (9%)
cta: 8s (9%)
outro: 7s (8%)Social clip (15-60s)
Goal: Stop the scroll. Deliver one idea fast. Drive action.
| Section | % of Duration | Purpose |
|---|---|---|
| Hook | 10-15% | Must grab in under 3 seconds |
| Core demo/message | 40-55% | Single feature or concept |
| Result/payoff | 20-25% | Show the outcome |
| CTA | 15-20% | Action with urgency |
Scene duration range: 3-8 seconds per scene
Pacing rhythm: Fast. Every frame earns its place. No filler, no breathing room. Cut the moment understanding lands.
Example scene distribution for 30s social clip:
hook: 3s (10%)
demo: 12s (40%)
result: 8s (27%)
cta: 7s (23%)Announcement (15-45s)
Goal: Deliver news. Build excitement. Drive to learn more.
| Section | % of Duration | Purpose |
|---|---|---|
| Teaser | 10-15% | Build intrigue before the reveal |
| Reveal | 30-40% | The news itself with visual impact |
| Key detail | 20-25% | One supporting point |
| CTA | 15-20% | Where to learn more |
Scene duration range: 4-8 seconds per scene
Pacing rhythm: Build tension then release. The reveal scene should feel like a moment - slightly longer than expected, with impactful animation.
Hook techniques
The first 3 seconds determine whether a viewer stays. Use one of these proven hook patterns:
1. The bold question
Open with a question the viewer wants answered.
- id: hook
duration: "3s"
narration: "What if your code reviewed itself?"
visual: "Question text animates word by word on dark background"2. The surprising statistic
Lead with a number that challenges assumptions.
- id: hook
duration: "3s"
narration: "Teams waste 12 hours a week on manual reports."
visual: "Large number '12h' with clock animation draining"3. The pain statement
Name the pain the viewer feels right now.
- id: hook
duration: "3s"
narration: "Stop building dashboards from scratch."
visual: "Bold text slams onto screen with impact animation"4. The before/after flash
Show the transformation in a single shot.
- id: hook
duration: "4s"
narration: ""
visual: "Split screen: messy spreadsheet morphs into polished dashboard"5. The demo tease
Show the product doing something impressive without explanation.
- id: hook
duration: "4s"
narration: ""
visual: "Quick montage of the product in action, 1-second cuts"Rule: Text-heavy hooks work for social (viewers have sound off). Narration hooks work for website embeds and presentations (sound on expected).
CTA placement and design
Placement rules
- Always second-to-last or last scene - never bury a CTA in the middle
- Duration: 5-8 seconds for demos/explainers, 3-5 seconds for social clips
- Repeat the URL or action twice: once in narration, once as on-screen text
Effective CTA patterns
| Pattern | Example | Best for |
|---|---|---|
| Direct URL | "Try free at acme.dev" | Website-distributed videos |
| Action + benefit | "Sign up and build your first dashboard in 5 minutes" | Demos and explainers |
| Urgency | "Early access closes Friday" | Announcements |
| Social action | "Follow for more tips" | Social clips with series |
CTA scene template
- id: cta
duration: "6s"
frames: 180
narration: "Start free at acme.dev. Your first dashboard takes five minutes."
visual: "CTA text centered, URL prominent below, subtle animated background"
animation: "text fades in over 20 frames, URL underline draws in at frame 40"
music:
track: "main-track"
volume: 0.4
duck: false
sfx: []
transition_to_next: "fade-to-black"Rhythm and scene variation
The 3-beat pattern
Group scenes into sets of 3 with consistent internal rhythm:
Beat 1: Setup (shorter scene, introduces the topic)
Beat 2: Develop (longer scene, shows the detail)
Beat 3: Resolve (medium scene, delivers the payoff)Example for a feature showcase:
feature-intro: 4s (setup: "Three ways Acme saves you time")
feature-1: 8s (develop: first feature in detail)
feature-1-result: 5s (resolve: the outcome of using that feature)Visual variety checklist
Avoid visual monotony by varying these elements across scenes:
- Layout: Alternate between centered, left-aligned, and split-screen
- Scale: Mix wide shots (full UI) with close-ups (specific button or element)
- Motion direction: Alternate slide-from-left with slide-from-right
- Color intensity: Use accent colors sparingly - not every scene needs a pop
Pacing variation
Do not make every scene the same length. Vary scene durations to create rhythm:
Good: 4s - 8s - 6s - 10s - 5s - 8s - 6s
Bad: 7s - 7s - 7s - 7s - 7s - 7s - 7sMonotonous pacing feels like a slideshow. Variable pacing feels like a story.
Scene duration calculations
Words-to-duration formula
comfortable_duration = word_count / 2.5
maximum_duration = word_count / 3.0
minimum_duration = word_count / 2.0| Words | Min Duration | Comfortable | Max Speed |
|---|---|---|---|
| 5 | 2.5s | 2.0s | 1.7s |
| 10 | 5.0s | 4.0s | 3.3s |
| 15 | 7.5s | 6.0s | 5.0s |
| 20 | 10.0s | 8.0s | 6.7s |
| 25 | 12.5s | 10.0s | 8.3s |
If a scene needs more words than its duration allows, split into two scenes.
Transition time budget
Transitions consume real frames. Account for them:
| Transition | Typical Duration | Frames at 30fps |
|---|---|---|
| hard-cut | 0 frames | 0 |
| cross-dissolve | 15-30 frames | 15-30 |
| fade-to-black | 20-40 frames | 20-40 |
| wipe-left/right | 15-25 frames | 15-25 |
During a cross-dissolve, both scenes are partially visible. Plan visual content so neither scene's key elements overlap with the other's during the transition window.
Common pacing mistakes
| Mistake | Impact | Fix |
|---|---|---|
| Every scene is 5 seconds | Feels mechanical, no rhythm | Vary between 3-10s based on content weight |
| 15-second scenes | Viewer disengages, feels like a lecture | Break into 2-3 shorter scenes |
| No pause after hook | Hook's impact is diluted immediately | Add 1-2 beat pause or visual-only scene |
| CTA shorter than 4 seconds | Viewer cannot read the URL or action | Give CTAs 5-8 seconds minimum |
| Outro longer than 7 seconds | Viewer has already left | Keep outro to 4-7 seconds |
| Front-loading all features | Mid-video sag with no content | Distribute features evenly with benefits between them |
Frequently Asked Questions
What is video-scriptwriting?
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.
How do I install video-scriptwriting?
Run npx skills add AbsolutelySkilled/AbsolutelySkilled --skill video-scriptwriting in your terminal. The skill will be immediately available in your AI coding agent.
What AI agents support video-scriptwriting?
video-scriptwriting works with claude-code, gemini-cli, openai-codex. Install it once and use it across any supported AI coding agent.