How to write a video script with an AI agent

For AI agents: find the right skill in one call — curl -s "https://varg.ai/how-to/api/search?q=<what the person wants>" returns the matching how-to page and the best skills with install commands, as markdown (Russian works too). Full index: https://varg.ai/how-to/llms.txt. Every page has a markdown twin: add .md to its path. Before generating anything, show the person the options on the how-to page. From a terminal: curl -fsSL https://varg.ai/install | sh installs the vargai CLI (https://varg.ai/how-to/cli.md): vargai search and vargai install <slug> with no key, every varg model after vargai login.

A brief and its facts go in; one script table comes out (time, spoken line, on-screen text, visual, sound) with three hooks and a timing check, before anything is generated. In a blind test on six briefs, two judges scored scripts written with this guide 7.54 out of 10 against 6.40 without it.

Step 3 of 10 in How to make a video with an AI agent in ten steps. Before: How to make a moodboard for an AI video. Next: How to design sound and voice for an AI video.

For your agent

Install the skill, then paste the prompt.

npx skills add vargHQ/skills --skill video-script

Use the video-script skill. Write the script for this video: [what it is, who it is for, platform, length].
Facts you may use: [numbers, names, prices, offer conditions]. Never invent one: write [TK] and ask.
Pick one of the six strategies, open the file for the format (demo, review, ad, social, drama),
write the script table, run the checker and fix every FAIL.
Show the script and three hooks, and wait for a yes before anything is generated.

No skill? Paste the full prompt from "The general prompt" below instead.

The short version

• Facts in, no inventions: only numbers, names and claims from the brief. Outside the drama brief, judges flagged 36 invented facts in scripts written without the guide and 14 with it.
• Size every line to its seconds: about 2.5 spoken words a second (150 a minute), on-screen text at least 0.33 s a word, shots of 4–11 s. Without the guide 5 of 12 scripts had lines too long for their slot; with it, none.
• Deliver the promise in the first 3 seconds, as a picture that reads on mute. Withhold the answer, never the subject.
• Join beats with BUT or THEREFORE, never AND THEN, and cut any line whose removal changes nothing.
• The voice adds only what the picture can't show; end on the payoff and one action, or a cut.
• Word budgets at 150 wpm: 37 words for 15 s, 75 for 30 s (60–70 reads better), 150 for 60 s.
• Show the script and three hooks and wait for a yes before anything is generated.
• Do not pick a winner with 1–10 scores: reversing the reading order changed the winner in 2 of 3 briefs. Measure with code, gate with yes/no checks, rank pairwise in both orders.

Guide for AI agents · November 3, 2026. Research, rules and a tested skill. Agents write the script before anything is generated, from real facts, and then measure it against the clock instead of grading their own taste. Get the skill on varg how to; source on GitHub.

Short answer

An agent writes a great script when it writes the script first, from real facts, and then measures it against the clock instead of grading its own taste. In a blind test on six briefs, two judges scored scripts written with this guide 7.5 out of 10 against 6.4 without it, and preferred them in 10 of 12 comparisons.

Example output: a 30-second explainer from the skill, with BUT/SO joins between beats and the checker's verdict.

Five rules carry most of the difference:

1. Facts in, no inventions. Only numbers, names and claims from the brief; never a made-up customer, review or experience. Outside the drama brief, judges flagged 36 invented facts in scripts written without the guide and 14 with it.
2. Size every line to its seconds. About 2.5 spoken words a second (150 a minute), captions on screen at least 0.33 s a word, shots of 4–11 s. Without the guide, 5 of 12 scripts had lines too long to say in their slot; with it, none.
3. Deliver the promise in the first 3 seconds, as a picture that reads on mute, and name the topic: withhold the answer, never the subject.
4. Every beat turns the next: join beats with BUT or THEREFORE, never AND THEN, and cut any line whose removal changes nothing.
5. Show it, then end on the payoff: the voice adds only what the picture can't show, and the video ends on one action or a cut.

How to use it: install the video-script skill (or paste the general prompt below). The agent picks one of six strategies, opens the file for its format (demo, review, ad, social, drama), writes the script table, runs the checker and shows the script for approval before anything is generated.

The writers were fresh Claude Sonnet agents; the judges were Claude Opus and Claude Sonnet, blind to which script was which (sign test p = 0.039, judges agree at r = 0.66). Judges from the same model family can favor its style, so treat this as triage until audience numbers come in. The guide lost one brief, a plane-windows short, where its hooks hid the topic. That note became a rule, and a second round lifted that brief from 5.75 to 7.0.

Shipped: the skill video-script (vargHQ/skills#77), the card varg.ai/how-to/skills/video-script, a web version in varg's look at https://varg.ai/how-to/write-a-video-script-with-an-agent, and the research data (kept in varg's private research repo).

The general prompt

Paste this into any agent before it writes a script. It is the short form of the video-script skill: seven steps, nine rules, the defaults to replace and the clock. The skill adds a checker script, six example scripts and the variation files.

You are writing the script for a video. Write it before any voice, image or clip is made: every later step is cut to it.
Left alone you drift to the most probable script: a "have you ever wondered" opener, three adjectives, a narrator
describing the picture, a vague happy ending. Replace each default with the specific thing.

1. Brief and facts. Get the viewer, the one promise, platform + length + ratio, the facts, the one action and the
   production limits (AI video or footage, voice, speakers, model). Ask once, only for what changes the script; assume
   the rest and say so. Write facts.md. Never invent a number, quote, review, customer or experience: write [TK] and ask.
2. Skeleton. Find what already works for this viewer: top videos in the niche from the last 30 days, ads that have run
   for months. Note the hook, the format, how the product appears, the ending. Copy the structure, never the words.
3. Promise, ending, ten hooks. Write the promise as one sentence. Write the last line. Write ten first lines of
   different kinds; cross out the first idea you had and anything two drafts share; keep the three most specific.
4. Beat sheet. One line per beat with its time. BUT or THEREFORE between beats, never AND THEN. Where people appear:
   who wants what, what happens if they don't get it, why now.
5. Table: | # | time | spoken | on screen | visual | sound |. One spoken line = one visual. Numbers as they are said.
6. Check. Spoken words <= seconds x 2.5 (150 wpm). On-screen text >= 0.33 s a word. Every shot fits the model
   (runs of 4-11 s). Hook lands by 3 s in feeds. Run the checker, fix every FAIL, read every line aloud.
7. Show the script and three hooks, and wait for a yes before anything is generated.

Rules: one viewer, one promise. The first frame and line pay off the packaging and read on mute. Open a loop;
withhold the answer, never the topic or the stakes. Every beat turns something; cut what changes nothing. Show it, and say
only what the picture can't. Write for the ear. Specific beats general. End on the payoff and one action.
Disclose paid deals at the start; never fake a customer; an AI presenter never claims to have used the product.
Offers keep their conditions exactly as given. Codes and reference numbers go on screen, not in the voice.

Pace comes from the National Center for Voice and Speech (about 150 wpm) and Brysbaert's review (audiobooks 140–180 wpm); caption speed from the BBC subtitle guidelines; shot length from varg's tested runs and each model's spec.

Strategies that work

Six structures cover most videos. Each has a credible origin and one full example script, and every example passes the checker with 0 fail and 0 warn. Pick by what the video must do, then use the format templates under Variations.

The Post-it facts come from the National Inventors Hall of Fame; the hammer and feather from NASA's NSSDC. Ferm, Sift and Relay are fictional products, and the recipe story is fiction.

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

The sticky note started as a glue nobody could use.

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

Why grandma crossed out the best line in her recipe.

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

A warm, steady place for dough in a cold kitchen. Facts: holds 24–28 °C, folds flat, $89, 30-day returns.

Result first: Sift (25 s app ad)

An hour-long call in five lines you can trust.

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

Why a hammer and a feather hit the Moon at the same time.

What is / what could be: Relay (45 s brand film)

No patient call goes unanswered while staff look after the patient in front of them.

Variations

Each format changes a few rules on top of the general prompt; each has its own reference file in the skill with one checked example script.

Pro demo and launch video

• Open on a change in the world, never on the company (Andy Raskin; Peter Cohan).
• Show the result first: "Start by presenting the highest impact, most compelling screen" (Cohan, Great Demo!).
• Name the villain and reject the obvious fix out loud: "Who wants a stylus?" (Jobs, 2007).
• Write the 140-character headline first and script exactly one showstopper (Carmine Gallo).
• Demo by value, not by menu; in longer demos set up the insight, the alternatives and a "perfect world" first (April Dunford).
• "Smth should be happening every 2-3 seconds", 45 s to 1:30 (Roy Lee, 2,808 bookmarks).

Example: Patchwork (fictional dev tool), 60 s, 86 words.

Product review

• A review is "a preview of what it will be like to own the product", pros, cons, worth it, and whether competitors are (Marques Brownlee).
• Give every verdict a frame of reference: what you used before (MKBHD).
• Prove it with your own test, and make "flaws but not dealbreakers" a beat (Wirecutter).
• Disclose a free product or paid deal at the start, spoken and on screen (FTC).
• No invented experience: AI presenters are endorsers and cannot claim use (FTC 2024 rule).

Example: Lumo H2 headlamp (fictional), 45 s, the reviewer's own test.

Ad and UGC ad

• Pick the opener by what the viewer already knows: the offer (wants it), proof (doubts it), a comparison (shops the category), the problem (feels it), a story (feels nothing yet). Eugene Schwartz's awareness levels via book notes, mapped by Dara Denney.
• Who it's for and what they get by 3 s, hook done by 6 s (TikTok Creative Codes); product shown by 5 s (Google ABCD), named about three times (P&G rule in Ogilvy on Advertising).
• Problem, solution, real proof; an honest demonstration beats a claim (Ogilvy).
• Native and a little ugly beats polished (Barry Hott); write 3–5 versions that differ in angle, since about 5% of Meta creatives win (Motion 2026).
• "Write it like something is happening, not like someone is explaining" (@AlessandroLavis).
• Truth checklist: real customers or labeled actors, typical results, no AI personas giving testimonials, disclosures early (16 CFR 255, 465).

Example: Fold&Go packing cubes (fictional), solution-aware side-by-side, 20 s, 37 words.

Social short and YouTube intro

• The opening pays off the title or thumbnail; on autoplay many never see the thumbnail (MrBeast production doc; Paddy Galloway).
• The hook is a picture that reads on mute in 3 s, then foreshadow the ending in the same 3 s (Jenny Hoyos).
• Rehook about 20–25 s in, at most twice in 60–90 s (Kallaway).
• End right after the payoff: Hoyos cut one second and retention rose from 83% to 88%.
• One version per platform; one recurring character and a series name turn views into follows (@laurgrowth).

Example: steak on a car engine (fictional experiment), YouTube Short, 34 s.

Short-form drama

• Open on the conflict: 3–5 seconds, about 2–3 lines (Asmaa Jamil, Casting Workbook).
• One beat per episode: hook, turn, cliffhanger; a "micro-closure" while the series question stays open (Safaricom brief; 28-writer study).
• End on a named button: revelation, reversal, deadline or intrusion (InkTip).
• "Every second has to deliver information or emotional engagement"; clarity over subtlety (Shicong Zhu, DramaBox, PGA).
• For AI video: talking heads and confessionals render well, fights don't (Neural Viz in WIRED); write action the model can render (MIT Technology Review); 4–8 s shots with a time per line.

Example: Wrong Number, episode 1 (fiction), 70 s, two locations, every shot 8 s or less.

How agents expand and improve the guide

The guide changes only on evidence, because most ideas that sound better lose: only a third of the ideas Microsoft tested improved the metric they were built for (Kohavi et al., 2013). The skill's references/improve.md is the full loop; this is the short form.

1. Keep a test set. Six briefs, one per format, ship with the skill. Before editing the skill, write all six with the current version and keep them as the baseline. "Create evaluations BEFORE writing extensive documentation" (Anthropic, skill best practices).
2. Log every script that ships: format, strategy, hook, length, words, checker result, who approved it, where it was posted, and the numbers when they come back. Log the losers too.
3. Read the number, fix only the part it grades (table below).
4. Test one thing at a time: the same body with a new hook, or the same script with a new ending, using the platform's own split test.
5. Judge drafts the way that works: YES/NO checks from the brief, pairwise in both orders, a judge from another model family, edits that quote the failing line, at most three rounds. Model judges agree with people only about 73% of the time on stories (LitBench), so the audience decides.
6. Promote a lesson into the skill only after a clean test win, the same note from the person twice, or two independent credible sources. Then re-run the six briefs with a fresh agent that has only the skill loaded ("Claude B") and keep the change only if it loses on no brief.
7. Add a format by copying the shape of ad.md: when to use it, beats in seconds, word budget, rules with sources, one checked example.
8. Refresh the evidence every few weeks: X posts from the last 7 days and 4 months sorted by bookmarks with bait accounts dropped, the Wikipedia AI-writing page for new tell-tale phrases, and the varg model specs for clip lengths.

Sources: YouTube Help, key moments; practitioners map it the same way on X: views grade the hook, downloads the CTA, revenue the funnel (@gregisenberg, 8,282 bookmarks), and Pocket FM rewrites only the hook or cliffhanger when a video misses 2.5% CTR or 55% 3-second through-play (@RohanNayak2, 12,697 bookmarks).

Ranking scripts with an LLM judge

A judge that rates scripts 1–10 is not stable enough to pick a winner. Reading the same 18 scripts in reverse order changed the winner in 2 of 3 briefs for both of our judges. What works is structural: measure what code can, gate with yes/no checks written from the brief, then rank the rest pairwise in both orders, with the judge counting and quoting failures, a different model family or a panel, and calibration on human picks. Telling the judge to be unbiased does not work: MT-Bench's default prompt already said to avoid position and length bias, and its judge still showed both (Zheng et al.).

What our own judges did

Stable is not the same as right. The counting judge decided half its comparisons on "invented facts", and in one brief it picked a different winner than the 1–10 judges. That order of criteria is a statement of values, and it has to be checked against what the person would pick.

The biases and their fixes

The protocol

1. Measure with code first. Pace, hook timing, shot length, numbers not in the facts and AI tells come from check_script.py. Code is "fastest and most reliable" (Anthropic).
2. Normalize. One plain template, neutral ids, no author or version, equal length within a pair.
3. Gate with yes/no checks written from each brief. About five per brief plus the house checks, one check per call, the judge quoting evidence before PASS, FAIL or UNKNOWN. Per-brief criteria reached 87% consistency with humans against 67% for one fixed rubric (WritingBench). Drop scripts that fail a blocking check, such as an invented claim or a missing disclosure.
4. Rank the survivors pairwise, on one to three taste criteria (hook, ending, voice), both orders, wins only when consistent, ranked by consistent wins or Bradley–Terry.
5. Use a judge from another model family than the writer, or a panel of three.
6. Send to a person: pairs that flip when swapped, emotion-led ads and drama, originality.
7. Validate the judge. Label 100–200 scripts per failure mode, pass or fail with a one-line critique. Split them 10–20% examples, 40–45% dev and 40–45% test, and report the share of failures caught (TPR), the share of good scripts passed (TNR) and Cohen's kappa, not raw agreement (Hamel Husain & Shreya Shankar). For ads, platform results and audience pretests are the stronger ground truth.

Writing criteria judges agree on

• Observable and one thing. Two people must reach the same answer without talking.
• Count, don't rate. "List every number or claim not in the brief, with the quote" beats "Is it accurate?"
• Define the edge cases. A paraphrase of a brief fact is not an invention; an inference the brief doesn't state is.
• Drop criteria every script passes. They raise agreement and add no ranking signal.
• Write the decision order down and agree it with the person who owns the brand.
• Allow UNKNOWN and TIE.

The example rows illustrate the sourced principles; they are not quotes.

The judge prompt (run twice, swapping the order)

Compare two video scripts written for the same brief. Do not reward length, confidence or formatting.
<brief>{brief}</brief>
<script id="K7">{script}</script>
<script id="Q2">{script}</script>
For EACH script, list with quotes or beat numbers:
- inventions: numbers, names, prices, offer conditions or claims not in the brief
  (a paraphrase of a brief fact is not an invention; drama may invent characters and plot)
- hook_miss: 1 if the first beat does not make clear what the video is about, as a picture that works on mute
- removable_beats: beats you could cut without changing what happens or what the viewer learns
- unsaid_lines: spoken lines a person would not say out loud like that
- unproducible_shots: shots AI video can't make in one clip of 10 s or less
Decide in this order: fewer inventions; fewer hook misses; fewer removable beats; fewer unsaid lines;
fewer unproducible shots. If all are equal, answer TIE.
<verdict>K7 | Q2 | TIE</verdict>

The skill ships this prompt, a one-check yes/no gate prompt and the protocol as references/judge.md.

What practitioners on X say

The X sample was 1,444 posts from 48 queries in three windows. A reader kept 80 advice items from 53 authors, all quotes checked word for word. It flagged a campaign of 18 posts pushing one judge model, so their numbers were not used. The expert side is 45 findings from 34 sources, every quote checked against the saved page.

What varg how-to already has

varg had no script skill of its own on 2026-11-03: "video script" and "write a video script" both return two unverified community skills first, and the varg fallback is a hooks-only card. The audit ran 41 searches on the how-to engine and read 26 cards and the skills repo at origin/main f7fdc2f.

The knowledge exists but is scattered over about 20 files in 15 skills, and they disagree:

• Speaking pace. Plans range from 2.0 to 3.5 words a second, so a 30-second slot gets 60 to 105 words depending on the file read.
• On-screen text. Some files allow 5–10 words a second, others about 3.
• Hook length. Definitions run from 2–3 s to 0–13 s, and spoken hook budgets from 9 to 25 words.
• Product entry. Checklists say "product by second 2" while the yapper, street-interview and drama-ad formats bring it in after 15–60 s.
• Beats. Three, four or five, depending on the skill.

Gaps no file covers: one script format, a word budget per delivery (narration, dialogue, lip-sync), a check before money is spent, chunking lines into generated shots, the body of the script (only the hook has a bank), and templates for demo voiceover, review, skit and micro-drama.

Changes made in vargHQ/skills#77, merged 2026-11-03:

• New skill video-script, with one script format, the checker, six strategies and five format files.
• One speaking pace across skills: ecommerce-video-ads (was 3.5 words a second), ai-ugc-ad-video, product-video-hooks (spoken hook now 6–8 words, so it fits 3 s), varg-podcast-video, tiktok-shop-video (captions at reading speed) and the varg-video-prompting templates now plan at about 2.5 words a second, or under 10 words per 5 s for lip-synced close-ups.
• Step 3 of how-to-make-ai-video and video-skills, the whole-video prompt and varg-previz step 2 now send the agent to video-script.
• The plugin's skill list now includes video-script and video-moodboard; the latter had been left out when it shipped.

Experts and sources

Every rule traces to a page that was opened and quoted on 2026-11-03: 269 expert findings, 265 of them verified on the page (verbatim quotes, credibility line and link for each) and 320 advice items from X, all 320 quotes checked word for word by script with 0 failures. X corpus: 5,531 unique posts from 124 queries in three windows (last 7 days, since July, since mid-2024), 2,359 of them from the last 7 days, plus 400 X Articles read in full.

Most-saved X posts behind the rules (numbers as of 2026-11-03):

Not used, because the source could not be opened or the attribution is wrong: Ira Glass's "anecdote, then reflection"; William Goldman's "enter late, leave early"; Facebook's "47% of value in the first 3 seconds"; "kill your darlings" as Faulkner's (it is Quiller-Couch's "murder your darlings", 1914). Schwartz's awareness levels come from book notes, not the original text. Suspect X accounts (bait, bookmarks far above likes, paid-promo networks) were dropped.

The research data (corpus, reader outputs, expert findings, test scripts and judge scores) is kept in varg's private research repo.

Go deeper

• The skill: video-script (npx skills add vargHQ/skills --skill video-script)
• The designed version of this guide, with every picture and clip: https://varg.ai/how-to/write-a-video-script-with-an-agent
• Every claim of the ten steps traced to its source: the evidence bank

All 10 steps

The route, with the one line that hands it to an agent: How to make a video with an AI agent in ten steps

1. How to find references for an AI video
2. How to make a moodboard for an AI video
3. How to write a video script with an AI agent (this page)
4. How to design sound and voice for an AI video
5. How to design characters and props for AI video
6. How to previz a video in Three.js or Blender
7. How to animate a previz with AI video models
8. How to edit a video with HyperFrames and AI agents
9. How to judge an AI video: measure, don't grade
10. How to keep an AI video project in GitHub