mcpField
V
video-storyboard

video-storyboard

github.com/thatjuanCreative & media158 installsUpdated 3w ago
Repository

About video-storyboard

Video Storyboard is a text-based storyboard-writing skill for marketing and advertising teams. It turns a creative brief into a strategic narrative and production-ready frame descriptions, including visual and audio direction.

Key features

  1. 01Extract creative brief and audience details
  2. 02Choose a narrative frame and story spine
  3. 03Map beats and frames to runtime
  4. 04Write shot and visual descriptions per frame
  5. 05Plan music, voiceover, dialogue, and sound effects
  6. 06Deliver and critique in Markdown

Use cases

  1. 01Turn an advertising brief into a storyboard
  2. 02Plan story beats for different video lengths
  3. 03Communicate shot details to directors and crews
  4. 04Review brand presence and narrative clarity

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/thatjuan/agent-skills --skill video-storyboard

After installing, type/video-storyboardin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

README.md
references/
ad-formats.md
shot-language.md
storyboard-format.md
storytelling-canon.md
visual-description-craft.md

Details

From the project README

Video Storyboard

A world-class storyboard writer for marketing and advertising video. Produces an all-text markdown storyboard — frames are described in rich, specific prose (cast, wardrobe, location, lighting, lens, motion, color, props, on-screen graphics) instead of drawn. Every storyboard pairs a strategically grounded narrative with frame-level production-ready detail.

The skill is grounded in the canonical literature of marketing storytelling and ad video production. See Storytelling Canon for distilled frameworks and the books they come from.

Storyboard Generation Workflow

Phase 1 — Brief Intake

Extract the creative brief. Every frame later traces back to it. If input is sparse, ask focused discovery questions before generating.

Brief ElementWhat to Extract
Product / ServiceWhat is being sold, what it does, what makes it different
Single-Minded PropositionThe one idea the audience must walk away with — the SMP
AudienceWho, their world, their tension, the moment they hear this ad
Strategic GoalAwareness, consideration, conversion, loyalty, repositioning, launch
ToneEmotional register — heartfelt, deadpan, absurd, cinematic, gritty, dreamlike, premium, irreverent
Format & Duration6s bumper, 15s, 30s, 60s, 2-min hero film, vertical social, UGC, demo, episodic
Channel & ContextWhere it plays — TV, YouTube pre-roll, IG/TikTok feed, OOH digital, cinema, in-store
MandatoriesLogo placement, legal supers, brand safety zones, pack shot, end frame, music ownership, dialogue language(s)
Brand VoiceExisting brand world, prior campaigns, things to avoid
Budget SignalsProduction scope clues — single location vs. multi-city, talent scale, VFX appetite

For platform-specific durations and beat cadences, see Ad Formats.

Phase 2 — Strategic Story Setup

Before any shot thinking, lock the story spine.

  1. Cast the Hero — In marketing storytelling the customer is the hero, the brand is the guide (StoryBrand). Name the hero in human terms: who they are, what they want, what blocks them.

  2. Define the Conflict — Internal (how they feel about their problem), external (the practical obstacle), and philosophical (the larger "why this is wrong"). All three sharpen the spot.

  3. State the Premise — One line: "[Hero] wants [desire]. But [obstacle]. So [brand action]. Now [transformation]."

  4. Pick the Story Frame — Choose the narrative skeleton that fits the duration, format, and tension. Frames available:

FrameBest ForSource
StoryBrand 7-Part (Character / Problem / Guide / Plan / Call to Action / Failure / Success)Brand films, explainers, DTCDonald Miller
Hero's Journey (compressed)60s+ brand epics, transformation storiesCampbell / Vogler
Save the Cat beat compressionNarrative spots with character arcBlake Snyder
Pixar Story Spine ("Once upon a time… Every day… One day… Because of that… Until finally…")15–30s spots, social, simple emotional arcEmma Coats / Pixar
Problem → Agitation → Solution (PAS)Direct-response, performance, demosClassic copywriting
Vignette / AnthemBrand films, manifesto, recruitmentOgilvy / Hey Whipple
Demo-AnchoredProduct-feature spots — show, don't tellOgilvy
Two-World (Before/After, Them/Us, World-A/World-B)Comparison, repositioning, category disruptionHey Whipple

See Storytelling Canon for the full beat sheet of each frame.

  1. Apply Stickiness Filters — Run the premise through Made to Stick's SUCCESs (Simple, Unexpected, Concrete, Credible, Emotional, Stories). Strengthen any weak axis before proceeding.

  2. Find the Conflict / Twist — Hey Whipple: "conflict is always more interesting." Identify the unexpected reversal, the visual joke, the emotional gut-punch, or the demonstration moment that earns the viewer's attention. No twist = no spot.

Phase 3 — Treatment

Write a one-paragraph treatment before going to frames. A treatment is the spot in prose: tone, world, who we meet, what happens, what we feel, how it ends. This is the document the director would shoot from. Length: 120–250 words.

Phase 4 — Beat Map

Translate the treatment into beats sized to the duration. A beat is a story unit — usually 2–6 seconds. See Ad Formats for typical beat counts per duration.

DurationTypical BeatsTypical Frame Count
6s bumper2–32–3
15s4–64–6
30s7–107–10
60s12–1812–18
2:00 hero film20–3520–35

Each beat carries one job: hook, setup, escalation, turn, payoff, brand reveal, CTA.

Phase 5 — Frame Generation

Expand each beat into a fully described frame. Frames are the heart of the deliverable. Every frame contains:

FieldContent
Frame #Sequential number
Timecode00:00–00:03 style — start and end
ShotShot size + angle + lens + movement (e.g., "Slow push-in MCU, 50mm, eye-level") — see Shot Language
VisualRich prose describing what the camera sees: location, time of day, weather, light direction and quality, color palette, cast, casting notes, wardrobe, props, action, blocking, expressions, motion within frame, VFX or graphic treatment. Specific not generic. See Visual Description Craft
On-Screen Text / SuperAny title cards, lower-thirds, kinetic type, captions, legal supers
Voiceover (V/O)Narrator copy, in quotes, with read direction (warm / clipped / wry / urgent)
DialogueCharacter name + line + delivery direction
SFXDiegetic and designed sound effects
MusicTrack behavior — "swelling strings build", "track drops out", "needle-drop into [track / vibe reference]"
TransitionHow this frame moves to the next: hard cut, match cut, whip pan, dissolve, smash cut, J-cut, L-cut, graphic match
NoteOptional director's-eye intent — the why of the frame in one sentence

For detailed shot grammar, see Shot Language. For prose technique that makes visuals filmable without an image, see Visual Description Craft.

Phase 6 — Audio Architecture

Audio is half the spot. Plan it as an arc, not a per-frame afterthought.

LayerWhat to Define
MusicGenre, instrumentation, tempo, energy curve across the spot, drop/swell moments, mnemonic/sting placement, license posture (custom score, library, needle-drop reference, sonic-logo end)
V/OVoice profile (age, gender, accent, timbre, archetype reference — "wry late-30s woman, dry like Aubrey Plaza"), pace, total word count vs. duration (≈2.5 words/sec read)
DialogueCasting voice notes, language, regional notes
SFXDesigned vs. naturalistic, signature sounds, moments of silence
Sonic BrandingEnd-frame sonic logo, mnemonic motif placement

Ogilvy's principle applies: the spot should also work with the sound off — so visuals carry the SMP independently.

Phase 7 — Brand & Closer

Every spot ends with a closer. Define:

ElementSpec
Pack / Hero ShotThe product / logo moment — described in prose (lighting, surface, motion, hero pose)
End FrameFinal still composition — logo position, tagline, URL/handle, legal/CTA
CTAVerb-led action ("Switch today.", "Book at brand.com", "Tap to try")
Legal SupersRequired disclosures, asterisk copy, terms placement
Sonic LogoMnemonic landing on the end frame

Ogilvy: commercials that end on the package change brand preference more than commercials that don't. Earn the end frame.

Phase 8 — Self-Critique Pass

Before delivery, run the storyboard through these filters:

FilterCheck
Sound-off testDoes the SMP land with no audio?
Six-second testDoes the hook land in the first 2 seconds for social, first 5 for broadcast?
One-idea testCan the viewer summarize the spot in one sentence? If not, cut.
Conflict testIs there real tension, surprise, or stake — or is it just visual wallpaper?
Specificity testCould two different directors shoot wildly different films from this? Tighten until no.
Brand presence testIs the brand integrated into the story, or pasted on?
Cliché testHey Whipple's smoke-out — diverse hands stacking, sunsets, slow-mo high-fives, generic uplifting piano. Cut and replace.
Truth testOgilvy: "Never write an advertisement which you wouldn't want your own family to read."

Output Format

Final deliverable is a single markdown document with this structure:

# [Spot Title] — [Brand] | [Duration]

## Logline
[One sentence — the spot's premise]

## Strategic Setup
- **Audience:** [...]
- **Single-Minded Proposition:** [...]
- **Tone:** [...]
- **Format:** [Duration, channel, aspect ratio]
- **Story Frame:** [Chosen narrative skeleton]

## Treatment
[120–250 words of prose — the spot as a director would read it]

## Audio Architecture
- **Music:** [...]
- **V/O:** [Voice profile + total approx. word count]
- **SFX posture:** [...]
- **Sonic logo:** [...]

## Storyboard

### Frame 1 — `00:00–00:03`
**Shot:** [size + angle + lens + movement]
**Visual:** [Rich, specific prose. Multi-sentence if needed. Casting, wardrobe, location, light, color, action, blocking, expression, motion.]
**On-Screen:** [Any super / kinetic text]
**V/O:** "[Copy]" *(read direction)*
**Dialogue:** *[Character]* "[Line]" *(delivery)*
**SFX:** [...]
**Music:** [Behavior at this beat]
**Transition:** [Out of this frame]
**Note:** [Director's-eye intent]

### Frame 2 — `00:03–00:06`
[...]

[...continue for every frame...]

### Final Frame — End Card
**Visual:** [Pack shot / logo composition described]
**On-Screen:** [Tagline, URL, legal]
**V/O / Sonic:** [Closer audio]

## Production Notes
- **Locations:** [...]
- **Cast:** [Hero, supporting, extras — count and casting brief]
- **Wardrobe / Props:** [Critical items]
- **VFX / Graphics:** [If any]
- **Mandatories:** [Logo, legal, pack-shot]

For a complete worked example using this format, see Storyboard Format.

Reference Documents

ReferenceWhen to Consult
Storytelling CanonDuring Phase 2 — picking and applying a narrative frame; distilled beat sheets from StoryBrand, Hero's Journey, Save the Cat, Pixar 22, Made to Stick, Hey Whipple, Ogilvy
Ad FormatsDuring Phase 1 and Phase 4 — duration-specific beat cadences, platform conventions (TV, YouTube, IG/TikTok, OOH, cinema, UGC, demo, anthem, episodic)
Shot LanguageDuring Phase 5 — precise vocabulary for shot size, angle, lens, movement, framing, lighting, transitions
Visual Description CraftDuring Phase 5 — writing rich, specific, filmable prose that replaces a sketched frame
Storyboard FormatDuring Phase 5 and Phase 8 — exact markdown output spec with a full worked example

Comments

Markdown supported