CommunityWriting & Editinggithub.com

video-script

Write a video script from a brief in one of three modes: animation (motion graphics), live action (shootable, budget-aware) or documentary (story beats, interview guide, B-roll list). Outputs a formatted .xlsx plus a NEXT STEPS tab with a summary, treatment notes, AI image prompts, a legal first pass and feasibility notes. Use whenever someone shares a brief, deck, product notes or rough idea and wants a script, AV script, explainer, commercial script, testimonial outline, documentary outline or interview questions, even if they only say "write the 30s script."

What is video-script?

video-script is a Claude Code agent skill that write a video script from a brief in one of three modes: animation (motion graphics), live action (shootable, budget-aware) or documentary (story beats, interview guide, B-roll list). Outputs a formatted .xlsx plus a NEXT STEPS tab with a summary, treatment notes, AI image prompts, a legal first pass and feasibility notes. Use whenever someone shares a brief, deck, product notes or rough idea and wants a script, AV script, explainer, commercial script, testimonial outline, documentary outline or interview questions, even if they only say "write the 30s script.".

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/thinkalim/ai-video-preproduction-skills/tree/HEAD/skills/video-script

Installed? Explore more Writing & Editing skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Video Script

The script is the product. NEXT STEPS is a bonus that points to the next job.

1. Choose the mode first

Ask: animation, live action or documentary? If the brief makes it obvious, say which you picked and why in one line. Then read the matching guide before writing:

  • Animation or motion graphics: references/animation.md
  • Live action, commercial, scripted: references/live-action.md
  • Documentary, testimonial, interview-led, brand story with real people: references/documentary.md

A hybrid (live action with animated graphics, a doc with a scripted open) uses the main mode's guide and borrows rules from the other for those frames. Say so.

2. Intake (one short message, only what's missing)

  • Brand and product name, exactly as the client says it.
  • Runtime (15, 30, 60, 90s, or longer).
  • Audience and the one thing they should do or feel.
  • Brand profile. Accept a brand guide PDF, logos, screenshots, a website or typed notes. Pull palette, type, logo rules, tone, tagline, mandatory and banned words. Summarize in 5 to 8 lines and confirm. Offer to save it as references/brands/<brand>.md from _template.md. Never redraw a logo.
  • Mode-specific questions from the guide (shoot days and budget for live action; subjects and B-roll for documentary).
  • Legal notes the client already has. Don't wait on them. Step 5 runs a first pass.

Work from partial input. Flag gaps. Never fill them with invention.

3. Structure

Build the arc before writing lines: hook, problem, turn, proof, product, payoff, close. Short spots compress it. Use any section names in the brief as the spine.

4. Write

Follow the mode guide. Shared rules for every mode:

  • VO is final copy, written to be spoken: natural, complete sentences that carry a real thought and connect frame to frame. No strings of fragments, no stacked taglines. One fragment at the close, if it earns it.
  • VISUAL is written as direction: two to three full sentences on framing, movement, light and transition, in production or animation language as the mode calls for.
  • About 2 words of VO per second. Intro and close stay light. Trim the densest frames first.
  • Never invent stats, quotes, names or claims. Use the source as written.
  • TITLES: 2 to 6 words. Echo the beat, never repeat VO word for word. Legal lines marked LEGAL:.
  • No em dashes. No filler. No AI phrasing ("unlock," "seamless," "in today's world").

5. Legal first pass

A flag list, not legal advice. Say so once. Check every frame for:

  • Claims: numbers, superlatives ("best," "#1," "proven"). Each needs a source, date and scope.
  • Comparisons to competitors, named or implied.
  • Testimonials and quotes: written approval, typical results, paid disclosure.
  • Regulated categories: health, supplements, finance, insurance, kids, alcohol, environmental claims.
  • Pricing, offers, trials: terms on screen.
  • Trademarks, third-party brands and UIs. Rights: music, stock, likeness, fonts.
  • Releases for people and locations (live action and documentary).
  • Accessibility: supers held long enough to read, captions planned.

Each flag: frame, exact words, the risk in one line, a safer rewrite. Never change approved copy silently.

6. Next steps (bonus, keep it tight)

  • Summary: one sentence.
  • Treatment notes: a short paragraph of 3 to 5 sentences on look, pacing, music and VO tone, transitions.
  • Style anchor + frame prompts: one style line, then one AI image prompt per frame, for storyboards. No text in images except the logo frame. No real people or trademarked characters.
  • Feasibility (live action): days, locations, principals, flags.
  • Legal flags and open questions.
  • Next skill: live action goes to a pre-pro deck; documentary goes to an interview schedule and B-roll shot list.

7. Render

python scripts/build_script.py frames.json outputs/<name>.xlsx \
    --title "<Brand> - <Project>" --runtime "60-seconds" --type "Live Action" --notes notes.json

--type: Animation, Live Action or Documentary. Each frame: frame, time, visual, audio, title, prompt. For documentary, audio holds the SOURCE and TARGET SOUNDBITE, title the lower third or super. notes.json: summary, treatment, style_anchor, feasibility, legal_flags, open_questions (lists), plus for documentary interviews ([{"subject": "", "questions": [""]}]) and broll ([{"location": "", "shots": [""], "must": true}]). Examples: references/frames_example.json, references/notes_example.json, references/documentary_example.json.

Filename: project code if given, otherwise <Brand>_<Project>_Script_v1.xlsx.

Keep a copy of the script as one JSON file (title, runtime, type, frames, notes). The builder reads it directly, and the next stage (pre-pro deck) picks up the title from it.

Review pass (always, before presenting)

Every answer runs twice. The user never sees the first draft.

  1. Draft the full answer.
  2. Review it the way a demanding creative director and producer would, against the checklist below and every rule in this skill. Read the copy as if hearing it in a client meeting. Mark every miss.
  3. Fix every miss, then present only the revised version.
  4. End with one line: Review pass: <what changed>, or Review pass: no changes needed.

This applies to every step that produces something: research, options, copy, specs and files. For a file, build it, open or render it, check it, then fix and rebuild before handing it over.

Checklist

  • Timecodes run without gaps and end at the runtime. VO sits inside budget. Builder warnings at zero.
  • VO reads naturally aloud as complete thoughts that connect frame to frame, not stacked taglines.
  • Every VISUAL tells the director, DP or animator what to make: framing, movement, light, transition.
  • No invented stats, quotes, names or claims. Legal pass complete. No em dashes, no AI phrasing.

8. Check, then present

  • The builder checks timecodes (gapless, ending at runtime) and prints the VO count against a 2 words per second budget. Fix every warning.
  • No invented numbers, names or quotes. No em dashes. Legal pass done.
  • Present the file. Then 2 to 4 lines: mode, arc, frame count, VO words, top flags.
  • Make nothing extra unless asked.

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

Related Skills