Video script

Write the script before any voice, image or clip is made: every later step is cut to it. Left alone you drift to the most probable script, which is the one everybody else gets: a "have you ever wondered" opener, three adjectives, a narrator describing the picture, a vague happy ending. This skill names those defaults, gives the alternative for each, and makes you measure the script instead of grading your own taste.

The output

One file, script.md: header lines, one table, ## Hooks, ## Sources. Keep this shape exactly; the checker and the production skills read it.

format: ad            ad | demo | review | social | drama | explainer | brand
length: 30s
ratio: 9:16
wpm: 150              narration pace; measure one take of the chosen voice and put its real pace here
max_shot: 10          longest clip the chosen model makes well (see Fit the clock)
facts: facts.md       the only place numbers, names and claims may come from
viewer: who, in their own words
promise: the one sentence the viewer gets from this video
strategy: problem-agitate-solve
cta: one action, or none

• spoken: voice-over in quotes; dialogue as MARA: "..."; delivery in brackets, [whispers].
• One spoken line, one visual. A line never runs across a cut it does not own; split it instead.
• Write numbers, prices, dates and URLs the way they are said: "forty-five dollars", "patchwork dot dev".
• ## Hooks: the three best first lines out of ten, the chosen one first. ## Sources: each fact and where it is from.

Steps

1. Brief and facts. You need: the viewer, the one promise, platform + length + ratio, the facts (product facts, data, the real story), the one action, and the production limits (AI video or footage, voice, speakers, model). Ask once, in one message, only for what would change the script; assume the rest and say what you assumed. Write facts.md. Never invent a number, a quote, a review, a customer or an experience; write [TK] and ask.
2. A proven skeleton. Find what already works for this viewer: top videos in the niche from the last 30 days, ads that have run for months. For each, note the hook, the format, how the product appears and the ending. Copy the structure, never the words. No time for that? Pick a strategy below.
3. Promise, ending, ten hooks. Write promise: as one sentence. Write the last line. Then write ten first lines of different kinds (formats in references/social.md). Cross out the first idea that came to you and anything two drafts share; keep the three most specific ones that are still true.
4. Beat sheet. One line per beat with its time, and BUT or THEREFORE between beats. Where people appear, answer for each beat: who wants what, what happens if they don't get it, why now.
5. Write the table by the rules below.
6. Check. Run python3 scripts/check_script.py script.md and fix every FAIL. AI tells are reported with their beat and speaker, so a character who talks in clichés on purpose shows up as exactly that. Read every spoken line aloud at speed. Answer the YES/NO list at the end. Change lines because a check or the person named a problem, not on taste.
7. Show it. Show the script and the three hooks and wait for a yes before any voice or video is generated.
8. After it ships, log it and read the numbers: references/improve.md.

Rules

1. One viewer, one promise. Every beat serves the sentence in promise:. An ad that does too much does nothing well (Google ABCD); write the headline first (Gallo).
2. The first frame and line pay off the packaging. Whatever made them stop (title, thumbnail, first image) is delivered at once, as a picture that reads on mute in 3 s or less; the shot, 3–5 words on screen and the spoken line say the same thing. A broken promise is the first drop-off (MrBeast doc, YouTube Help, Hoyos, Kallaway).
3. Open a loop, then pay it off. Right after the hook, say what is coming. Withhold the answer, never the topic or the stakes: the first line says what the video is about ("Plane windows are round because..."), not a riddle ("A corner."). Give two plus two, not four. Answer a question only with a bigger one (Stanton, Hoyos, Loewenstein).
4. But or therefore, never "and then". If "and then" fits between two beats, the story is boring (Parker & Stone; Aristotle called such plots "the worst").
5. Every beat turns something. A want meets an obstacle; a value flips (doubt to proof, safe to danger). Start as close to the end as possible and cut any line whose removal changes nothing, first and last lines included (McKee, Vonnegut, Mamet, Sorkin).
6. Show it; say only what the picture can't. Draft it as a silent film first. The voice adds what the picture cannot show and never describes it. In a feed, something new appears every 2–3 s (Mamet, Wilder, Roy Lee).
7. Write for the ear. One idea per sentence, words a twelve-year-old knows, lengths that vary the way speech does. Codes and reference numbers (flight numbers, model numbers, part numbers) go on screen, not in the voice. Read it aloud and cut what you would not say to a friend (NPR, Hoyos, Mañalac).
8. Specific beats general. A number, a name, a visible detail, the viewer's own words from reviews and comments. Replace every word of praise with the fact behind it (Wikipedia: Signs of AI writing; Heath brothers).
9. Fit the clock. Size every line to its seconds and every shot to its model (table below).
10. End on the payoff. No recap, no wind-down. Ads, demos and reviews end on one action, said and shown; shorts cut right after the payoff (Hoyos cut one second and retention went from 83% to 88%).
11. Tell the truth. Disclose paid deals at the start, spoken and on screen. An AI presenter never claims to have used the product. A shown result must be typical. Offers keep their conditions exactly as given ("20% off your first order"), and the product on screen does only what facts.md says it does. Label AI people where the platform asks (FTC, TikTok, Meta).

Full sources for every rule: references/sources.md.

Defaults to replace

Fit the clock

• Narration: 150 words a minute is 2.5 a second (audiobooks run 140–180). Go to 170–190 only for light, fast social voice-over. Lip-synced close-ups: under 10 words per 5 s shot. Measure one take of the real voice and set wpm:.
• On screen: at least 0.33 s per word; a 4-word caption stays 1.2 s or longer (BBC subtitle guidelines).
• Shots: each generated clip must fit the model's window (Veo 3.1: 4, 6 or 8 s; Seedance 2.5: 4–30 s; Kling 4: 3–30 s; check https://varg.ai/models/llms.txt), but runs of 4–11 s obey better and retake cheaper. Set max_shot:.
• Hook: lands by 3 s in feeds, 5 s on YouTube and in demos.

Strategies

Sources: Parker & Stone; Hoyos and Stanton; Ogilvy ("above average in sales results"); Peter Cohan's "Do the Last Thing First"; Derek Muller's PhD (refuting the misconception beat clean exposition); Nancy Duarte's sparkline. Story Spine, Harmon's circle and Save the Cat are in references/sources.md as audits, not molds.

But / therefore: the Post-it Note (30 s)

format: explainer
length: 30s
facts: National Inventors Hall of Fame, Art Fry and Post-it Notes
promise: the sticky note started as a glue nobody could use
strategy: but-therefore

Question ladder: the crossed-out line (30 s, fiction)

format: social
length: 30s
promise: why grandma crossed out the best line in her recipe
strategy: question-ladder
cta: none

Problem, agitate, solve: Ferm proofer (30 s ad, fictional product)

format: ad
length: 30s
facts: Ferm keeps dough at 24-28 °C, folds flat, $89, 30-day returns
viewer: home bakers whose sourdough comes out flat in a cold kitchen
promise: a warm, steady place for dough in a cold kitchen
strategy: problem-agitate-solve
cta: link below

Result first: Sift (25 s, fictional app)

format: demo
length: 25s
facts: Sift turns a call recording into decisions, owners and dates in about 30 seconds; tap a line to hear it
promise: an hour-long call in five lines you can trust
strategy: result-first
cta: try your longest call free

Misconception first: the hammer and the feather (40 s)

format: explainer
length: 40s
facts: NASA NSSDC, Apollo 15 hammer-feather drop
promise: why a hammer and a feather hit the Moon at the same time
strategy: misconception-first

What is / what could be: Relay (45 s, fictional product)

format: brand
length: 45s
facts: Relay answers clinic calls, books the visit in the clinic calendar, texts the patient a confirmation; demo is 15 min
viewer: owners of small clinics
promise: no patient call goes unanswered while staff look after the patient in front of them
strategy: is-could-be
cta: book a 15-minute demo

Variations

Test briefs for checking a change to this skill: references/test-briefs.md.

YES / NO before you show it

• Does the first frame and line deliver the promise by 3 s (feeds) or 5 s (YouTube, demos)?
• Could a stranger repeat the promise after one watch?
• Does every join between beats read BUT or THEREFORE?
• Does every beat have a visual that shows it, and does no line describe its own picture?
• Is every number, name and claim in facts.md?
• Is there one ending action (or none, on purpose)?
• Does check_script.py report 0 FAIL?
• Would you say every line out loud to a friend?