Skip to content

hub-ki/video-generation / skills/video-plan

video-plan

Verified

Write 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.

references/plan-and-script.md

View on GitHub
# PLAN.md and SCRIPT.md

> **Three documents, three authorities — don't merge them.**
> `PLAN.md` is the *shape*, authored and approved before the shoot. `SCRIPT.md` is *every word*
> in playing order, also approved before the shoot, and the source of truth for copy.
> `TIMELINE.md` is *generated* from the composition after the build and is the only place exact
> timestamps exist. Copy changes go into `SCRIPT.md` first, then into the composition; timing
> changes go into the composition and regenerate.

|  | `PLAN.md` | `SCRIPT.md` | `TIMELINE.md` |
|---|---|---|---|
| what it is | **intent** — what the video should contain | **the words** — everything that will be read or typed | **fact** — what the composition actually does |
| who writes it | you, before any capture | you, before any capture | generated by the production skill |
| exact times? | **no** — target durations only | no | yes, frame-exact |
| edit by hand? | yes, that's the point | yes | **never** |

## PLAN.md

```markdown
# <video> — plan

**Shape:** guide (capability-complete, numbered steps, slower) | demo (one narrative spine)
**Purpose:** tutorial/guide | internal presentation        <- from the purpose question
**For:** embedded in the product next to <feature> | shown to <customer> in <context>
**Captured from:** <the exact origin URL — no default exists; say it in chat too>
**Language:** <language, and the address form if the language has one>
**Brand:** <given by the user | extracted from <url> | neutral default>
**Target length:** ~55s

## Beats
1. `menu` — the user menu open, avatar top-right. ~4.5s
   card: "Your account, always within reach."
   spotlight: "Alex Fischer"            <- verbatim, read off the page
2. `settings` — the settings panel it opens. ~6s
   card: "Everything about you lives here."
   spotlight: none — no single control worth pointing at
3. ...

## Writes this shoot needs
- creates: two documents, one workspace named <...>
- changes: the account's display language
- deletes: everything created above, at sign-off

## Privacy
- the share drawer shows the owner's full email — decide from rendered frames

## Out of scope
- billing screens (not shipped yet)
```

### A spotlight target is EVIDENCE, not a description

Write the words that are **actually on the screen**, in quotes, copied from the page you looked
at. Not `the avatar button`, not `the pricing section` — those describe a thing you have in mind,
and nothing later in the pipeline can check them against reality.

This is not pedantry about notation. A team building the same kind of tool shipped a model that
filled every scene's spotlight hint with the site's own domain name — a string that marks nothing
anywhere on the page. The target lookup fell back to the whole content column every time, the
spotlight was invisible, **and every step reported success.** The cause was structural: going
straight from looking at a page to composing a storyboard obliges you to nothing, so the plan gets
written before anything has been observed.

Quoted page text inverts that. It is the one field a later step can verify — `findByText` either
matches it or fails loudly — and writing it forces the plan's author to have actually read the
screen. If you cannot quote it, you have not looked, and the beat is not ready.

Two rules follow:

- **If a target has no words** (an icon-only button, a chart, an avatar), say so and give the
  nearest labelled anchor plus the relationship: `spotlight: the icon left of "Einstellungen"`.
  That is still checkable; "the settings icon" is not.
- **Never a coordinate or a CSS class.** A class read off the page today does not survive the next
  deploy, and a coordinate does not survive a different viewport.

**No timestamps.** Exact cut points come from the capture's own beat log, and any number written
here before capturing is fiction that someone will later read as a spec. Target durations are
fine — they are explicitly targets.

**Name the capture origin, every time.** Which environment gets recorded — and therefore which
version of the product — is the user's call, and the target moves. State it in the plan and in
the message that carries the plan; never silently reuse a previous session's origin.

**"Out of scope" is the section that pays off.** Six weeks later it answers "why isn't X covered?"
in one line.

## SCRIPT.md

Continuous prose in **playing order**, readable start to finish without watching anything. Per
beat:

```markdown
## 1 · `menu` — the user menu

**Card:** Your account,<br/>always within reach.

**Typed:** —

**Spoken:** Top right you'll find your account. Everything about you lives behind it.

---

## 4 · `ask` — asking about the document

**Card:** Ask about<br/>what's in it.

**Typed:** Summarise the contract in three bullet points.

**The answer must:** come back in <language>, name the three parties, and stay under six lines.

**Created for the shoot:** a document titled "<...>"

**Spoken:** …
```

Include, without exception:

- the **headline** verbatim as it will render, including the `<br/>` break
- **every string typed into the app** — chat prompts, search terms, sample text, file names
- **what the AI must answer** — the substance you require, plus the language it must answer in.
  Prompting in a language does not guarantee the reply comes back in it; the script is where that
  requirement is written down so the shoot can be re-run when it doesn't
- **any data created for the shoot** — rule names, document titles, personas. These persist into
  later beats
- **title card and outro**, verbatim
- **the spoken line**, for a narrated guide (`spoken-track.md`)

## The one-message check

Send both documents together, once, after the arc is already agreed — so the check is on wording,
not on structure. Say plainly that nothing gets recorded until it comes back approved.

For an **internal** video, this is where it stops being formal: an abstract script and a two-line
plan, agreed in chat, is the whole gate.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall