hub-ki/video-generation / skills/video-plan
video-plan
VerifiedWrite the concept for a demo, guide, walkthrough or site-tour video of an app or any public website — the two documents that get approved BEFORE anything is recorded: PLAN.md (the shape: purpose, audience, beat list, spotlight targets, privacy flags, what is out of scope) and SCRIPT.md (every word in playing order: card copy, everything typed into the app, what the AI must answer, and the spoken track). Settles what is expensive to change later — what the video is FOR, demo vs guide, the language, the arc — and carries the copy rules that stop a video being re-shot over one sentence. Use this WHENEVER someone wants a video of an app or website planned, scripted, storyboarded or conceived — a "video concept", "script", "storyboard", "beat plan", "video outline", "Drehbuch", "Konzept" — and as the first step of building one. The companion `demo-video` skill turns the approved documents into the finished video; this skill never records or renders anything.
video-plan
You are writing the two documents a video gets approved on, and nothing else. No capture,
no cutting, no rendering — that is the demo-video skill, and it refuses to start without
these.
PLAN.md the SHAPE — purpose, audience, beats, targets, spotlights, privacy, out of scope
SCRIPT.md the WORDS — card copy, typed strings, required AI answers, the spoken track
Why they are separate documents: a plan can be right while the copy is wrong, and copy is the thing reviewers actually react to. A stakeholder can approve words; they cannot approve a beat table.
Why they come first: the arc is what changes under review, and every beat captured against an unagreed arc gets re-captured. A sentence that changes after the shoot can cost the whole flow, because patching one beat into an existing cut is usually not available.
Usually, not always — and the condition is worth knowing, because it decides how expensive a late change is:
A single beat can be re-shot only when the scene shares no state with its neighbours, and the source renders stably between runs, and no audio anchor crosses the scene boundary.
On a demo of your own app the first two are typically violated: time-of-day greetings and relative timestamps drift between runs, so a patched beat is visibly discontinuous with the ones around it. On a self-contained section of a third-party website they typically hold. The third condition is the one that comes back later — the moment narration is added, a re-shot beat of a different length moves every following audio anchor, and a pipeline that could re-shoot freely while it was silent can no longer do it.
Reading the app in order to write the plan is fine and expected. Recording it is not. The same holds for a website you do not own — read it, do not film it yet, and do not click anything that writes.
| Need | Read |
|---|---|
| the standard two-part feature-guide format (the default ask — read FIRST if it's a guide) | references/guide-format.md |
| the subject is a WEBSITE, not an app you sign into (the tour arc, and the permission questions that belong in the plan) | references/site-tour-format.md |
| is there a concept of the application? (the reusable half — what the product is for, its flows, the words on screen) | references/application-concept.md |
| the exact shape of both documents, with a fill-in template | references/plan-and-script.md |
| caption card copy — what a headline may and may not do | references/copy-rules.md |
| the spoken track — grammar traps, audience fit, tone | references/spoken-track.md |
Step 0 — Ask before you start, then look for a concept
Two questions, in your first message, before any analysis. Both are cheap to ask and expensive to get wrong:
- "Shall I look at the application first and we agree what it does, or do you already know what the video should show?" Reading a product properly takes real time, and the caller may have a different starting screen, a different account, or a finished idea in their head. Starting the analysis unasked spends their minutes on your assumption.
- "What is this video for?" — Step 1 below, and it decides how strict everything else is.
Ask the second one even when the answer seems obvious from the situation. A request that arrives with the skill package attached, or without a brief, or as somebody's first message, is still a request for the video they described — not evidence that they wanted a throwaway. Inferring a lighter mode from circumstances delivers less than was asked for, and the parts skipped to save time are the ones that cannot be added afterwards.
Then look for an application concept: a document describing what the product does and why,
independent of any one video (references/application-concept.md). If one exists, the plan is a
projection of it rather than an invention — purpose and narration come from its prose, the beats
from its flow, the spotlight targets from its verbatim on-screen words.
If none exists, carry on without it. Do the direct thing, and offer at the end to leave a first concept behind, because you will have worked most of it out anyway. Never make someone write a concept before you will help them — an optional practice that blocks the first request is not optional.
Step 1 — Ask what the video is FOR
Ask this in your first message, as a question. Do not infer it. It sets the shape, the tone, and how strict everything below is. One question, four options:
| purpose | what it means | how strict |
|---|---|---|
| Marketing / promo | a cold audience, outside the product | ⛔ stop — a different video, differently captured. Confirm before doing anything else |
| Tutorial / guide | users learning the product; ships next to the feature | strictest. Full PLAN.md + verbatim SCRIPT.md, both approved. A wrong guide teaches wrong |
| Internal presentation | the team, a stakeholder demo, a feature share — the viewer already has the context | light. A short plan and an abstract script are enough; skip the verbatim gate |
| Other | ask what, then place it | — |
Do not apply guide-grade ceremony to an internal feature clip. Somebody wanting to show their team what they built on Friday does not need approved verbatim copy — that ceremony costs more than the video is worth and reads as obstruction. Scale down: agree the arc in a sentence or two, hand it over, done.
🚨 An ad / promo for a cold audience is out of scope, and it is not a faster demo. It is captured differently — the app's own responsive layout rather than a cropped desktop one, live interaction rather than stills, full-bleed framing. Getting that wrong is a re-capture, not a re-edit. Say so rather than adapting this into one.
Step 2 — Settle demo vs guide, in one line
They are different videos, not tone variants, and picking wrong means a rebuild. Confirm it explicitly even when the user said "just build it" — an autonomous signal licenses you to skip approval, not to guess a fork this big. One real build read "otherwise, do as you please" as license and produced a 7-beat promo; the ask was a guide covering the full feature range, and the whole thing was rebuilt.
| tell-tale | shape |
|---|---|
| "how-to", "guide", "show what you can do with it", onboarding | guide — capability-complete, numbered steps, slower, holds, narrated |
| "show them what it does", a single feature, a release note | demo — one narrative spine, fast, benefit-led, usually silent |
If it is a guide and the product ships a series of them, you are not designing a video from
scratch — you are filling in an established format. Read references/guide-format.md now.
Step 3 — Settle the language, and everything it touches
Ask which language the video is in, and write it into PLAN.md. Then hold it across every
surface in the frame — this is the rule that catches people, because getting the card copy right
and leaving anything else in the wrong language reads as a mistake, arguably a worse one,
because it looks like nobody watched it.
| what | how it goes wrong |
|---|---|
| 1. Card copy — headlines, title cards, outro | the easy one; never the whole job |
| 2. The app's own UI | it must be switched before capture, and it is usually a server-side user preference, not localStorage. Flag it in the plan; the capture skill has to act on it |
| 3. Everything you TYPE — test samples, chat prompts, search terms, file names | a localised UI with send the contract to anna@acme.com typed into it is not a localised video |
| 4. Everything the AI WRITES BACK | the money shot is usually a model reply. The script must say what language the answer must come back in — prompting in a language does not guarantee it |
| 5. Data you CREATE for the shoot — rule names, workspace/document titles, personas | these persist into later beats; one wrong-language rule name resurfaces three beats later |
Seeded fixtures count too: if the demo org is called "Seed Org" and it is on screen, that is English in your non-English video. Decide it here, not in review.
6. What the voice SAYS is a sixth surface, and it may be spelled differently. TTS engines
mangle short brand names and acronyms, especially a foreign word inside a sentence. The script
carries the readable spelling plus a note that the TTS input differs; the respelling itself
lives only in the production skill's narration.mjs. See references/spoken-track.md.
Step 4 — Agree the ARC before writing a single polished sentence
The abstract script is one line per beat: what that beat says, in order. Nothing verbatim,
no headlines. Get that agreed, then write the verbatim SCRIPT.md.
The order matters because the arc is what changes: reorder two beats or drop one and every carefully-worded card downstream is wasted. Writing 500 words of finished copy against an unagreed arc is the most common way to do this job twice. For an internal video the abstract script is usually where it ends.
Structure a demo as: Intro → (one section per task) → Outro, where each task is a few beats: set up / ask → it works (sped up) → the result. A guide is the same shape with more explicit step framing.
Order the sections causally, and end on closure. Each step should follow from the one before (create → browse → add a file → ask about that file → share the finished thing), and the last step before the outro must read as an ending — a closing action like share/done, never a new capability appearing from nowhere. A remake inherited the original's Share→Ask order; the AI answer landed after the workspace was already "finished" and the user called the ending "out of nowhere". On a remake, re-derive the order from the story — "faithful" covers the content, not the original's dramaturgy mistakes.
Step 5 — Decide, per beat
- Keep / cut / speed. Omit dead time (typing pauses, loading, mouse-hunting). Type-the-prompt ≈ 1.6×; reasoning/tool-call montages ≈ 6-10×; results hold on a still. Cap any un-spotlit static hold at ~4s — and count the total time the content is on screen across beats: a 4.6s result still directly after the same image in the previous clip's tail summed to ~8s and drew "it stays on the image for too long".
- Spotlight, or deliberately none. Only the key element per beat (a modal, a table, a "sent
✅" line), and be consistent — e.g. every result beat gets one. Two rules that cost rounds:
- Name the control being acted on, not the result it produces. A step whose card reads "Click Skills…" must light up the Skills button, not the panel that opens afterwards — the button is the thing the viewer has to find.
- If a beat has no single control worth pointing at, write "no spotlight". An opening beat that is simply "a question and its answer" got a box covering 60% of the window whose edges sliced through a line of text. That directs nothing.
- Never write a spotlight as a percentage or an estimate. Name the element; the production skill measures its rect.
- Copy. One short headline per beat. The full rules are in
references/copy-rules.md, and they are not stylistic preferences — every one of them is a revision round that happened. - Privacy. Flag names, emails and tokens that will be visible. Plan from the beat list, but say explicitly that the decision (blur / leave / crop) gets re-made from rendered frames — a plan-time answer is a memory of the UI, and one was wrong: the plan said the address appeared only in a menu nobody opens, and the share drawer then listed the owner with their full email, in shot, for seven seconds. Name the surfaces that carry identity: share and permission dialogs, member pickers, avatars and their tooltips, sidebars, "added by" lines, anything showing an owner.
- Writes. Driving a real app mutates it. List what the shoot will create, change and delete, so one approval covers the whole flow instead of one round per permission prompt.
Step 6 — Guides teach, so they have extra rules
A guide teaches; a wrong guide teaches wrong.
- The step structure must match the product's real model. If two paths are alternatives,
never number them
1then2— that teaches a required sequence. Same number, and let the headline carry the fork. This is a correctness bug, not a style nit. - Only claim what the footage will show. Word the copy to what will be on screen; if the product can do more than the video demonstrates, say so to the user rather than narrating the unshown thing.
- The viewer must never need to pause. If a step has several distinct actions (open → choose → confirm), the plan must say so — the production skill slows it or freezes on the key moment. Ask: could someone follow this at full speed, once?
Step 7 — Write the documents, then send ONE check
Write PLAN.md and SCRIPT.md to the project folder and send a single message: shape, who it's
for, the beat list, rough copy, privacy flags, and the writes the shoot needs.
SCRIPT.md is the complete on-screen text, in playing order, as continuous prose you can read
start to finish without watching anything. Per beat: the headline verbatim (including the
<br/> break), every string typed into the app, what the AI must answer and in which language,
any data created for the shoot, the title card and outro verbatim, and — for a narrated guide —
the spoken line.
Read every spoken line back as a sentence, out loud, as you write it — not after.
references/spoken-track.md has the twelve failure patterns this catches, each one a real defect
that only reading aloud found.
Then stop. Do not capture, cut, or render. Hand the approved documents to the demo-video
skill.
When the input is a feature brief
Treat a brief (the planning doc handed over once a feature ships) as the source of intent —
the team's vocabulary, the benefit, the audience, the out-of-scope list — and draft PLAN.md
from it. It is never the spec: a brief records what was planned, not what shipped. Every
claim gets verified against the running app, and the cards get worded to what the footage
actually shows. A video narrating the plan teaches wrong.
Briefs also carry internal framing (roadmap, pricing, competitor notes) that must not surface in on-screen copy. The plan approval is where that gets filtered out.
What "done" looks like
PLAN.md— no timestamps anywhere in it (target durations only; exact cut points come from the capture's own log, and a number written here before capture is fiction someone will later read as a spec).SCRIPT.md— every word, in playing order, readable end to end.- One message to the user carrying both, and an explicit "approve this before anything is shot".
- Both files kept after the build. Six weeks later, "Out of scope" answers "why isn't X covered?" in one line.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |