video-script

Write the script for any video before anything is generated: what is said, shown and heard in every beat, sized to the clock and the video model. A brief and a facts file in; one script table out (time, spoken line, on-screen text, visual, sound), three hooks, and a check that measures pace, hook timing, shot length, unsourced numbers and AI-sounding lines. Six structures with one example script each, plus variations for demo and launch videos, product reviews, ads and UGC, social shorts and short-form drama, and a loop for testing and improving the skill. Use for "write a script", "video script", "ad script", "UGC script", "TikTok, Reels or Shorts script", "YouTube script", "voiceover script", "demo or launch video script", "product review script", "short drama episode", "skit", "hooks", "how many words for 30 seconds", or any video that has no script yet. Not for the look (find-references) or the shot prompts (varg-video-prompting).

Step 3 of 10 in How to make a video with an AI agent in ten steps. The full guide, with every test and source: https://varg.ai/how-to/write-a-video-script-with-an-agent (as Markdown: add .md).

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.

text

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

#	time	spoken	on screen	visual	sound
1	0:00-0:03	the line as it is said	the words shown	what the camera sees: one shot, or a cut list	music, effects, silence

• 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

You will drift to	Write instead
"Have you ever wondered…", "In this video…", "Hey guys"	the result, the conflict or the strangest true detail, shown
three adjectives ("fast, simple, powerful")	one fact you can show or measure
"It's not just X, it's Y"; "No X. No Y. Just Z."	say Y
"Great question!", "You're absolutely right!"	the answer itself, or the disagreement
a narrator describing the shot	the shot alone, or a line that adds what it can't show
a vague hopeful ending ("the future is bright")	the payoff, then cut; or one action
speakers who all sound formal and alike	a want and a way of talking for each person
Sarah, Emily, Elara Voss, Elias Vance	names from the brief, or plain specific ones
the first twist that comes to mind	the third idea; drop what two drafts share
clipped fragments everywhere ("Simple. Fast. Done.")	mixed sentence lengths, as people talk
"a testament to", "seamless", "game-changer", "unlock", "elevate", "delve"	the concrete thing
invented stats, "experts say", "studies show"	a fact from facts.md with its source, or nothing

Fit the clock

Length	Spoken words, max at 150 wpm	Beats
15 s	37	3–4
30 s	75 (60–70 reads better)	5–7
45 s	112	6–9
60 s	150 (90–120 when the product must be watched)	7–12
3 min	450	chapters of 3–5 beats

• 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

Strategy	Use for	Beats
But / therefore	true stories, founder stories, history, anything with a plot	situation → BUT → THEREFORE → BUT → THEREFORE → payoff
Question ladder	social shorts, mysteries, lists, skits	hook + what's coming → question → bigger question → twist → cut
Problem, agitate, solve	ads to people who know the problem	problem → why it's worse → product as the fix → proof shown → one action
Result first	demos, tutorials, app ads	finished result → how, in the fewest steps → payoff moment → one action
Misconception first	explainers, science, how it works	question → the common wrong answer → why it seems right → evidence that breaks it → the right model
What is / what could be	launches, pitches, brand films	today's pain → the possible → today → the possible, made real → one action

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)

text

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

#	time	spoken	on screen	visual	sound
1	0:00-0:03	"This glue failed at its job."	THE GLUE THAT FAILED	a yellow square peels off a page, leaves no mark	soft peel
2	0:03-0:09	"Spencer Silver at Three M made it: sticky, but useless for tape."	SPENCER SILVER · 3M	lab bench, a tape strip lifts away clean	lab hum
3	0:09-0:16	"But in nineteen seventy-four, Art Fry's bookmark kept falling out of his hymnal."	1974	church choir; a paper slip slides out and drifts down	choir humming
4	0:16-0:21	"So he made bookmarks with a thin coat of Silver's glue."		brush on paper; the slip holds to a page, lifts clean
5	0:21-0:26	"So Three M tried them in four cities, in nineteen seventy-seven."	PRESS 'N PEEL · 1977	a 1970s shop shelf, small pads	register ding
6	0:26-0:30	"Renamed, they went national in nineteen eighty. Post-it Notes."	POST-IT · 1980	a wall of yellow notes	pop

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

text

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

#	time	spoken	on screen	visual	sound
1	0:00-0:03	"Grandma crossed out one line here."	ONE LINE CROSSED OUT	old recipe card, one line inked over	pen scratch
2	0:03-0:07	"So I baked her cake both ways."		two bowls, two tins, oven door shuts	timer ticking
3	0:07-0:11	"Without the line: dry and flat."	WITHOUT IT	cake A sliced, crumbling	knife
4	0:11-0:16	"With it, perfect. So why cross out the best part?"	WITH IT	cake B, tall and glossy; cut back to the card
5	0:16-0:22	"Under the ink, against the light: a cup of coffee. Don't tell Harold."	DON'T TELL HAROLD	card held to the window, the words show through
6	0:22-0:28	"Harold, my grandpa, hated coffee. He ate this cake every Sunday for forty years."	40 YEARS	old photo of grandpa holding a slice	soft piano
7	0:28-0:30	"I'm keeping it crossed out."		the card goes back in the tin, lid shuts	click, cut

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

text

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

#	time	spoken	on screen	visual	sound
1	0:00-0:03	"Fourth flat loaf this month."	#ad · MY 4TH FLAT LOAF	a hand presses a dense loaf; it doesn't spring back	thud
2	0:03-0:08	"Same starter, same recipe. My kitchen is just cold."	17 °C	thermometer on the counter, breath-cold window	fridge hum
3	0:08-0:13	"I tried the oven with the light on. It melted my bowl."		warped plastic bowl held up to camera
4	0:13-0:19	"So now the dough goes in this. Ferm holds it at twenty-six degrees all night."	FERM · 26 °C	box unfolds, dial clicks to 26, bowl goes in	dial click
5	0:19-0:24	"Eight hours later."		lid lifts: domed dough full of bubbles	soft gasp, music in
6	0:24-0:26	"It folds flat after."		box folds into a slim panel beside the fridge
7	0:26-0:30	"Eighty-nine dollars, thirty days to send it back. Link below."	$89 · 30-DAY RETURNS	loaf with a tall ear; finger taps the link

Result first: Sift (25 s, fictional app)

text

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

#	time	spoken	on screen	visual	sound
1	0:00-0:03	"An hour-long sales call, in five lines."	58:12 → 5 LINES	a long waveform collapses into five bullet lines	whoosh
2	0:03-0:08	"Who decided what, who owns it, by when."	DECISION · OWNER · DATE	the summary on a phone, three lines highlight in turn	ticks
3	0:08-0:14	"Drop in the recording. Thirty seconds later, this."	0:30	screen recording: drag file, progress bar, summary appears	click
4	0:14-0:20	"Tap any line to hear the moment it was said."		finger taps a line; the clip plays, waveform lit	"...ship it Friday."
5	0:20-0:25	"Sift. Try your longest call free."	sift.app	logo and URL	music out

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

text

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

#	time	spoken	on screen	visual	sound
1	0:00-0:03	"Hammer or feather: which lands first?"	WHICH LANDS FIRST?	a hand holds a hammer and a feather side by side	wind
2	0:03-0:08	"Most people say the hammer. Heavy things fall faster."	HEAVIER = FASTER?	on grass: the hammer thuds, the feather drifts	thud
3	0:08-0:14	"On Earth the hammer wins, but not because it's heavier. Air holds the feather back."	AIR	slow motion: air currents lift the feather
4	0:14-0:23	"So Apollo 15's David Scott tried it on the Moon, where there is no air. A hammer and a falcon feather."	1.32 KG · 0.03 KG	an astronaut on grey dust holds both out at shoulder height	radio static
5	0:23-0:28	"He let go."		both start to fall	silence
6	0:28-0:33	"They hit the dust together."	SAME TIME	both land at once, a small puff of dust
7	0:33-0:40	"With no air, everything falls at the same rate. Galileo said it. Scott showed it."	ALL FALL AT ONE RATE	Earth over the lunar horizon	music

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

text

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

#	time	spoken	on screen	visual	sound
1	0:00-0:03	"This patient is calling. Nobody will answer."		a phone rings on an empty front desk, full waiting room	ringing
2	0:03-0:11	"The front desk is checking someone in. The call goes to voicemail. The patient books somewhere else."	MISSED CALL	receptionist with a patient; phone shows missed call; the caller dials another clinic
3	0:11-0:16	"Now picture every call answered on the first ring, at any hour."	FIRST RING. ANY HOUR.	same desk; the phone lights once and a calm voice answers	one ring, "Lakeside Clinic, good morning"
4	0:16-0:22	"Today your staff choose between the person in front of them and the phone."		receptionist's eyes flick from the patient to the ringing phone	ringing
5	0:22-0:32	"With Relay they don't have to. It answers, books the visit in your calendar and texts the patient."	BOOKED · TEXTED	call transcript, a calendar slot fills, a text lands on a patient's phone	ding
6	0:32-0:40	"Your team stays with the patient in the room. The one on the phone is booked too."		receptionist laughing with a patient; the day's calendar full	music lifts
7	0:40-0:45	"Relay. Book a fifteen-minute demo at relay dot health."	relay.health	logo and URL	music out

Variations

Making	Read	What changes
a demo or launch video	references/demo.md	result first, villain, headline, value moments, real UI
a product review	references/review.md	disclosure, frame of reference, own test, the flaw, verdict for whom
an ad or UGC ad	references/ad.md	opener by awareness level, brand by 5 s, proof, one CTA, compliance
a social short or YouTube intro	references/social.md	hook formats, foreshadow, rehooks, platform versions
a short-form drama or skit	references/drama.md	cold open, a cliffhanger per episode, dialogue for lip-sync, series bible
better scripts over time	references/improve.md	log, read the numbers, test one thing, promote lessons
the best of several scripts	references/judge.md	code checks, yes/no gates from the brief, pairwise in both orders, calibration

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?