Communitygithub.com

video-brief-and-story

Start of any video job. Turn a request ("make a promo for my site", "a product video", "a pitch film like this one") into a brief, a studied reference, a story shape, a script and a shot plan. Use before sourcing footage or building anything, and again when feedback changes the story.

What is video-brief-and-story?

video-brief-and-story is a Claude Code agent skill that start of any video job. Turn a request ("make a promo for my site", "a product video", "a pitch film like this one") into a brief, a studied reference, a story shape, a script and a shot plan. Use before sourcing footage or building anything, and again when feedback changes the story.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shubhamnshukla/video-agent-kit/tree/main/skills/video-brief-and-story

Ask in your favorite AI

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

Documentation

Brief and story

1. The brief: what you must know

Find these out before anything else. Read what you were given first (the site, the app, a deck, a reference film); ask only for what is still missing, in one message.

QuestionWhy it changes the film
Who watches, and where?Investors in a room, visitors on a landing page and a muted social feed need different openings, lengths and text sizes
What should they do afterwards?It becomes the last frame: an address, a QR code, a button
How long?Sets the word count: about 2.5 spoken words a second, less for a film with pauses
What is the product, really?You need to use it, or see it used, to show it truthfully
Is there a film they like?A reference settles pace and look faster than any description
What must be in, what must not?Features not yet live, competitors, claims legal has not cleared

Defaults when they do not say: 16:9 at 1920 × 1080 authoring, 30 fps, 60 to 100 seconds, one narrator, the brand's own fonts and colours, light ground if the product is light.

2. Study the reference

If they give a reference film, take it apart before you write.

  • Cuts: npx hyperframes measure cuts ref.mp4 or ffmpeg scene detection. Make a contact sheet with one tile per shot (scripts/sheet.sh).
  • Words: npx hyperframes transcribe ref.wav --json.
  • Write a shot sheet: time, length, what is on screen, what is said. Then the proportions: how many seconds of problem, product, ending. Note shot length, where text appears, when music changes.

What you take from a reference is its structure and pace, never its footage, music, wording or characters.

3. Story shapes

Pick one and say which. They work for any product; what changes is who the people are and what the product screens look like (section 4 and video-footage-and-screens).

Story film (pitch, launch, brand). Hook → meet the people → the problem lands on all of them → each one's worry → what they tried → one line that sums it up → the product answers → the people again, better off → end card. The problem is 45 to 55 percent of the length. This is the shape to use when the audience must first care.

Website promo (30 to 60 s). Hook stating the outcome → the product doing its one main thing, large → three proof beats (a feature each, on screen two to four seconds) → one human moment → end card. Value is stated by the second beat; everything after it is evidence.

Product walkthrough (60 to 120 s). One person with one task, start to finish in the real product. Each step is a screen plus the one piece of it that matters, pulled out large. Say what the person gets at each step, not what the button is called.

Social cut (10 to 30 s). One idea. Text carries it without sound. The first frame already says something.

Adapting to the product.

ProductWho the people areWhat "the product, large" means
Consumer apppeople in their own lives, at home, on the movethe phone, with one piece of a screen pulled out beside it
SaaS or B2B toolpeople in roles: an ops lead, a founder, a support agent, each with a deadlinea browser window, with the one panel or number that matters enlarged
Website or marketplacea visitor with a needthe site itself: the hero, a search, a result, a checkout, as scrolling captures
Online shop or physical productthe buyer and the moment of usethe company's own product photos and footage, plus the page where you buy it
Servicethe customer before and afterthe booking or sign-up flow, and the result the service delivers

4. People

When the film has people, make them particular. For each: a name, an age, a job, a city, and the one thing they want from the kind of problem this product solves. Give different people different wants: an audience of strangers finds itself in at least one. In a film for a personal-finance app that was a bike, a home, a wedding and a trip; for a hiring tool it might be four managers with four different roles to fill. Show the want as a picture, and show every want the same way.

Names must suit the footage you can actually get, so cast and name together (see video-footage-and-screens). Keep one person's numbers the same as the account shown in the product, so story and screens agree.

These people are invented examples played by stock-footage models. Say so in SCRIPT.md and never present them as customers.

5. Writing the script

Write lines to be said aloud, in short hits. The examples below are from one film, for a personal-finance app; write the equivalent for the product in front of you. What works:

  • A hook that is a contrast or a small joke with truth in it: "Payday. The best day of the month. For about four hours."
  • A callback: set up "four hours", pay it off with "Nine a.m. ... By lunch, it's spoken for."
  • Fragments for introductions: "Kabir. Designer. He's wanted one bike for three years."
  • The person's own question in their own words, one each: "Can I buy the bike, and still sleep at night?"
  • One line that names the problem so well it could be the film's title: "They're not bad with money. They're alone with it."
  • A line that hands over to the product: "Everyone has advice. Nobody has their numbers." then "Give it your real numbers."

Rules:

  • One idea a line. Lines of two to five seconds. An id for every line (n-01, p-01, e-01): the id names the audio file and the clip.
  • Write numbers and dates as they are said: "twenty twenty-eight", "nineteen ninety-nine a month".
  • Use the audience's own currency, units and place names, and the words they use for the problem.
  • Take product claims from the product's own words. Keep a table in SCRIPT.md: line, where it comes from.
  • Leave words out where the picture says it. A name tag on screen does not need "meet Kabir".
  • After the first full pass, cut a tenth. It is always too long.

Words the company itself avoids, avoid too. If its own copy never says "loan", neither does the narrator.

6. The shot plan

For every line, decide what is on screen and what changes on which word. Write it as the table in SCRIPT.md (time, picture, voice) and, once timings exist, as the frame-numbered shot list in SPEC.md.

Check the plan against these before building:

  • Does frame 0 already show a person or a title? It is the thumbnail.
  • Is every important line also on screen as text? Rooms are noisy and feeds are muted.
  • Does anything hold longer than three seconds with nothing changing?
  • Is each kind of thing (name tags, wants, plans, advice) done one way throughout?
  • Does the ending bring back what the opening set up?
  • Does the last frame say where to go, and hold at least six seconds if it carries a QR code?

templates/SCRIPT.md has this form ready to fill in.

Individual skills in this repo

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

Related Skills