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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.2 KB |
| references/application-concept.md | markdown | 4.3 KB |
| references/copy-rules.md | markdown | 3.9 KB |
| references/guide-format.md | markdown | 7.5 KB |
| references/plan-and-script.md | markdown | 5.9 KB |
| references/site-tour-format.md | markdown | 5.2 KB |
| references/spoken-track.md | markdown | 4.8 KB |
references/spoken-track.md
View on GitHub# The spoken track
For a narrated guide, `SCRIPT.md` carries the voiceover too — and it is drafted here, not fixed
later. The production skill's `narration.mjs` is a near-verbatim copy of this text, so a defect
written here ships straight through: the fit table checks durations, the level check checks
loudness, the transcript check checks words against *your own file*. None of them checks whether
the sentence is good.
**Cards and narration are different registers, and the defect is almost always the same one: a
card label pasted into the spoken track.** A fragment on a card reads as deliberate; the same
fragment spoken reads like a sentence that got cut off, and the listener waits for an ending that
never comes.
So: **read every line back as a sentence, out loud, as you write it** — not after.
## Twelve failure patterns
Each is a real defect caught only by reading a script aloud. They came out of German builds, but
none of them is German: they are what happens when written UI copy is spoken.
1. **Verb–object agreement in a lifted label.** A label like "Let work" becomes "You let *the
agent* work" — a transitive verb spoken without its object has nowhere to land.
2. **A verb that doesn't take the construction you gave it.** "In practice that means three
things" → "In practice there are three of them." Fix the verb, not the noun.
3. **Enumerations that change grammatical shape mid-list.** Two infinitives then a bare noun (or
the reverse). Make every item the same shape.
4. **Elided auxiliaries with no "and" before the last item.** "…what he asked, …wrote, …ran" is
grammatical and, spoken, leaves the first two hanging. Add the conjunction before the last
item.
5. **Collocations that are wrong even though the grammar is fine.** "Place a search" → "what he
searched for". A phrase can parse and still be something nobody says.
6. **A word doing two jobs in one sentence.** Name the control explicitly instead of reusing one
word for the button and for the thing it opens.
7. **A verb missing its complement.** "Set" needs an object of its own — say *what* is set.
8. **A personifying verb that overshoots what the subject can do.** "An agent sits here" → "An
agent works here for you."
9. **A noun paired with the wrong support verb.** "Make intermediate steps" → "Then come the
intermediate steps."
10. **An object turned into the sentence's subject.** "Files come in via the plus" → "You add
files via the plus."
11. **A bureaucratic verb where a plain one reads better.** "registers it as an artifact" →
"shows it as its own card".
12. **A word implying an accident where the action was deliberate.** "what has disappeared" →
"what you archived".
Deliberate fragments are fine when they are *obviously* a list hanging off a full sentence — "It
has tools for that. A sandbox. Your workspaces. Web search." reads as intended. The test is
whether a listener would wait for more.
## Audience fit
Write for a viewer who has never used the product. Every product noun (Sandbox, Workspace, Skill,
Connector, Artifact) is new to them.
- Don't stack more than ~2 unexplained terms per beat without a concrete anchor.
- Don't let a term silently change function between beats without an explicit bridge sentence.
- Spend the setup cost on **one** metaphor and reuse it for free.
- Check that the first hands-on example actually delivers on the promise made just before it.
## Tone
Read the way a good primary-school teacher explains something new: short, warm, direct sentences,
confident the listener can follow. Never talking down, never padding.
## Timing is a consequence of the copy
In a narrated guide, beat lengths are a function of the line, not the other way round. Write the
line; the production skill measures it and widens the beat. When a line does not fit, the default
fix is a **wider beat**, not shorter copy — reviewers ask for slower pacing, and a beat that is
too short is a worse problem than a video that is ten seconds longer. Only shorten copy when the
beat is footage-limited.
Practical consequence for you: **prefer several short lines over one long one**, and mark in the
script which line belongs to which beat. A single sentence stretched across three beats cannot be
re-timed without a rewrite.
## Proper nouns: note the split, don't write the respelling
TTS engines mispronounce short brand names, acronyms and foreign words. The fix is a phonetic
respelling **in the TTS input only** — and that belongs to the production skill's
`narration.mjs`, not here.
`SCRIPT.md` carries the **real spelling**, because a human reads it for approval, plus one note
where a word is known to need respelling ("brand name is respelled for the voice; on-screen
spelling unchanged"). Never put a phonetic spelling in the script, on a card, or in the plan — if
it reaches a rendered surface, a reviewer catches it immediately.
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: 472k | 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 |