| name | video-storyboard |
| description | Use when designing, scripting, or storyboarding a short demo, launch, explainer, or marketing video (especially for a developer tool, app, or SaaS), OR when auditing, critiquing, or improving an existing video's narrative, hook, pacing, or storyboard. Runs a verified 6-stage process — positioning, message spine, beat sheet, script, storyboard, review — embedding StoryBrand, Before-After-Bridge / PAS / AIDA, the Pixar Story Spine, and the But/Therefore rule. Invoke whenever the work is about the STORY of a video rather than its rendering, including phrasings like "storyboard this", "what's the hook", "make the video more compelling", "the video falls flat", "script a launch video", or "audit this video". After an approved render, hand off publishing to video-assets so MP4 and AVIF release assets stay in sync. Do not use this skill for the encoding/rendering pipeline itself. |
Video Storyboard
A repeatable process for the part of a video that decides whether it works: the narrative. Rendering executes the story; this skill designs it.
For cctop launch videos, this is the first half of the workflow:
- Use this skill for story/script/storyboard/audit decisions.
- Render through the repo video pipeline (
cd video && ./build.sh launch for the launch cut).
- After the user approves the rendered video, switch to
$video-assets and publish with its confirmation gate. That workflow uploads cctop-launch.mp4, cctop-launch-720p.mp4, and a freshly generated cctop-launch-preview.avif together to the non-latest media-assets release.
For cctop product facts, audience, feature-fit judgment, and language choices,
read PRODUCT.md before writing positioning or scripts. Use README.md for
current public-facing claims and supported-tool lists.
It has two modes:
- DESIGN — build a video's story from scratch (product facts → approved storyboard).
- AUDIT — run the same lenses over a finished or draft video to find what's weak and how to fix it.
Pick the mode from the request. "Storyboard a video for X" → DESIGN. "Why does this video feel flat / make it better / review this cut" → AUDIT.
Everything here is built from frameworks that survived adversarial fact-checking. The frameworks are solid; many of the numbers floating around the industry are blog-grade rules of thumb. Where a guideline is directional rather than proven, it is marked [directional]. See references/frameworks.md for provenance, citations, and the specifics that were refuted (so you don't codify folklore).
The core idea
Most product videos fail the same way: they are a feature montage from the product's point of view ("here's the panel, here are the tabs, here are the themes"). They list capabilities instead of telling the story of a person whose problem gets solved.
The fix is one reframe and four moves:
- The viewer is the hero; the product is the guide. (StoryBrand) The story is about them and their struggle, not about your UI.
- Pick one spine and fill it — don't free-associate beats.
- Connect beats by cause-and-effect (but/therefore), never by chronology (and then).
- Engineer the opening for a muted, scrolling viewer — the first frame must earn the next two seconds.
Common failure modes (the floor-raisers)
These are the specific ways videos break, distilled from real reviews. They generalize — check for them in DESIGN (avoid) and AUDIT (catch). Pre-empting these is most of what makes a first draft good instead of a third.
- The hook shows one thing and says another. The opening line promises tension ("which one needs you?") while the visuals say "all fine" (e.g. every status indicator green). The first ~1.5s of picture must depict the problem, not just the text — a muted scroller reads the image, not the words. Fix: put the problem-state on screen in frame one, with motion (the thing going wrong), before or under the line.
- Action without payoff. You show the click / keypress / command, but never the result. The viewer feels the setup and never the relief. Fix: every action beat needs an after-beat — show the win (the session opened, the thing unblocked, the status flipping to good). This is the Story-Spine "until finally" / BAB "After," and it's the single most common missing beat.
- Wrong-altitude reveal. You open on the product's fully-bloomed internal UI and point at an interior detail, instead of how the user first encounters it. Fix: start at the real moment of discovery (the menubar glance, the CLI prompt, the notification) and expand from there.
- The "and then" tail. The back third decays into a feature montage — capability slide, and then another, and then another — with the hero gone. It's where momentum should peak before the CTA, and it sags. Fix: tie every late beat to the hero with "therefore (so you can trust it / use it with what you have)," compress, and cut vanity beats (theme galleries, spec lists) to a flash or nothing.
- Product-as-hero in the belly. The bookends are viewer-centered but the middle becomes a spec sheet — the person disappears. Fix: keep a problem/person present even in capability beats.
What this skill is — and what it can't be
This skill raises the floor of the first draft and shortens each review loop — it guarantees the lenses get applied and the known failure modes get pre-empted, every time, even by a cheaper or distracted agent. That is its value, not out-reasoning a strong model on a single careful pass (it won't; a good model already knows this craft).
It deliberately does not encode per-video creative specifics — the exact pacing of a transition, which element pulses, what a mock screen shows. Those are taste, discovered by rendering a concrete draft and reacting to it; hard-coding them would overfit the skill and make it brittle. Capture patterns here; leave the particulars to iteration on the actual cut.
DESIGN mode — the 6-stage pipeline
Each stage takes one artifact and produces the next. Don't skip ahead; a weak positioning statement poisons every downstream stage. Keep each artifact short — a video is 20–40 seconds, not a feature doc.
Stage 1 — Position · in: product facts + audience · out: one-paragraph positioning
Write the story's frame before any script, using StoryBrand: the viewer is the hero, the product is the guide that helps them win. Name three things:
- Who the hero is (be specific: "a dev running several AI coding agents at once", not "developers").
- What they want and what's in the way (the external problem and the internal feeling — frustration, loss of control, wasted time).
- The transformation: the before-state → the after-state the product enables.
If you catch yourself describing the product's features here, stop — you've made the product the hero. Rewrite from the viewer's chair.
Stage 2 — Message spine · in: positioning · out: a chosen structure, each step filled
Choose ONE spine and write a sentence for each step:
- Before-After-Bridge (default for 20–40s) — Before (the painful current state) → After (the desirable future) → Bridge (the product as the thing that gets you there). Best for "storytelling in tight spaces."
- PAS — Problem → Agitate (make the cost of inaction felt) → Solution. Use when the pain is sharp and relatable.
- AIDA — Attention → Interest → Desire → Action. Use when a hard CTA/conversion is the goal. (AIDA is a conversion spine, not a story arc — don't force it into acts.)
Stage 3 — Beat sheet · in: spine · out: 4–7 ordered beats
Generate beats with the Pixar Story Spine as a prompt ("…every day… until one day… because of that… until finally…"), then run the But/Therefore test on every seam: each beat must follow from the last with a "but" (tension) or "therefore" (consequence). If the only word that fits between two beats is "and then", you have a list, not a story — cut or reorder until causation holds. This single test is the fastest way to find a flat middle.
Stage 4 — Script · in: beat sheet · out: on-screen-text / VO script with timecodes
Write the words and the timing. Hard requirements, because the median viewer is scrolling with the sound off:
- The first frame must work muted and lead with motion, not setup. No cold logo, no slow fade-up on an empty stage. Open in the hero's problem.
- Answer "what is this / why do I care" by ~second 3–5.
[directional] Slow build is the #1 retention killer.
- End on a clear payoff and one CTA (where to go / what to do).
- Track the opening with hook rate = 3-sec views ÷ impressions once it ships.
[directional]
Stage 5 — Storyboard / shot list · in: script · out: per-beat frames
Turn each beat into a frame: what's on screen, the motion, the on-screen copy, and the duration. Two rules:
- Tight body cuts (~2s), no dwelling.
[directional] Momentum sustains retention; static holds bleed it.
- Pick the shortest length that carries the message. Retention scales inversely with length, so a tight 22s beats a baggy 35s.
[directional]
- Introduce the product the way the hero first encounters it. If they'd meet it as a menubar glance, a CLI prompt, or a notification — start there and expand, rather than opening on its fully-bloomed internal UI. The reveal should mirror the real moment of discovery.
Stage 6 — Review · in: storyboard / animatic · out: approved board
Before building, check the board against the Audit checklist below. Anything that fails goes back a stage. Treat the checklist as the definition of done.
AUDIT mode — score an existing video
Given a finished or draft video (a description, a storyboard, or the actual frames — Read them if available), walk the checklist and produce: a per-lens verdict (✅ / ⚠️ / ❌ with one line of why) and a prioritized fix list (highest narrative impact first). Be specific and reference the moment/timecode.
Two review disciplines (both learned from this skill underperforming a sharp human reviewer):
- Don't soften. A missing payoff (lens 7), a hook whose visuals contradict its words (lens 4), and a wrong-altitude reveal (lens 6) break the beat — rate them ❌, not ⚠️. A "warn" on a broken beat reads as "it's fine," and it won't get fixed.
- Name the single highest-impact fix. After the per-lens pass, don't end on a flat list of 2–3 "top" changes — pick the one change that most improves the video and say so. Ranking is the value; a tie is a dodge.
Run every lens — they catch different failure modes:
- Hero & guide (positioning). Is the viewer the hero and the product the guide? Or is it a product-centric feature tour? ❌ if it mostly shows the UI doing things with no person/problem at the center.
- Spine. Is there a discernible Before→After→Bridge (or PAS/AIDA) arc, or is it a montage of capabilities? Name the spine you can detect; if you can't, that's the finding.
- Causation (but/therefore). Do the beats connect by cause-and-effect, or is it "feature, and then feature, and then feature"? Find the seams that are only "and then."
- Hook. Does the first frame work muted and grab in ~2s? Is it a felt problem or a title card / logo / slow fade? Do the first ~1.5s of visuals match the words — if the line poses a problem, the picture must show it (don't let the text say "trouble" while the image says "all fine")? On social the first 2s decide everything.
- Value clarity. Is "what is this and why care" obvious by ~sec 5?
[directional]
- Discovery-true reveal. Is the product introduced the way the hero would actually first encounter it, then expanded — or does it open on the fully-formed internal UI and point at interior details before establishing the whole? A reveal that starts at the wrong altitude is a common, easy-to-miss miss.
- Payoff. Is there a clear after state — the moment of relief/win? A video that shows the action (the click, the keypress) but never shows the result has no payoff; the viewer feels the setup but not the resolution. (This is the Story-Spine "until finally" and the BAB "After.")
- Pacing & length. ~2s cuts, no slow build, shortest viable length?
[directional]
- CTA. Is there a clear next step at the end?
For each ❌/⚠️, give the concrete narrative fix (what to add/cut/reorder), not a production note. End by naming the single highest-impact change (then any runners-up), per the discipline above.
Honest caveats (read before quoting numbers)
- Frameworks: solid. Numbers: directional. StoryBrand (hero/guide), BAB, PAS, AIDA, the Pixar Story Spine, and the But/Therefore rule are well-established and primary-sourced. Every retention/timing figure (the "muted majority", "value by sec 3–5", "~2s cuts", length↔retention curve) is a vendor-blog rule of thumb — use as direction, re-check per platform, never present as proven.
- Do not codify the folklore. Verification refuted the exact SB7 7-step list, the exact Story-Spine prompt wording, AIDA-as-a-four-act-story, fixed "hook formula types", and specific impression multipliers. Use the framework principles at the altitude above; don't invent precise step lists.
- Two known gaps: there is no verified public playbook for how named companies (Linear, Vercel, Stripe, Apple…) structure videos, and no verified LLM storyboard-prompt framework. Don't assert specifics there.
Full provenance, citations, and the refuted list: references/frameworks.md.
