> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes.heygen.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Anatomy of a one-shot prompt
> The six-part skeleton — route, spec, beats, copy, technique, negatives — that removes the decisions agents most often get wrong.
Your Level 1 prompts worked because the workflow filled the gaps for you — the palette, the pacing, the structure. This is Level 2: the skeleton is how you take that control yourself.
The [copy-paste examples](/prompting/examples) share one skeleton. Each part removes a decision agents most often get wrong on a first try:
```text theme={null}
[route] /motion-graphics
[spec] 8-second 1920x1080 video.
[beats] Beat 1 (0-4s): ... Beat 2 (4-5s): ... Beat 3 (5-8s): ...
[copy] the exact on-screen text, quoted
[technique] Adapt the `code-typing` and `vfx-shatter` registry blocks.
[negatives] No narration, no image or media files.
```
* **Route** with a slash command — it loads the right workflow and the framework rules.
* **Spec** duration and resolution up front. Defaults are 1920x1080 at 30fps.
* **Beats** get timestamps. Include pacing instructions ("then hold on the blinking cursor") — agents skip breathing room unless told.
* **Copy** is quoted exactly, with `/` for line breaks. Unquoted copy gets paraphrased.
* **Technique**: name registry blocks exactly as they appear in the [catalog](/catalog/blocks/data-chart) — they're adapted starting points, not drop-ins (blocks ship with demo content the agent rewrites to your beat, so naming one pins the *technique*). Pin a technique wherever the default choice can fail (see [the specification dial](/prompting/specification-dial)).
* **Negatives** close the gaps: "no narration" is not "silent" — if you want no sound at all, say "no audio". Avoid ambiguous phrases like "no external assets" (CDN-loaded runtimes are normal; say "no image or media files" if that's what you mean).
Assembled:
> /motion-graphics Make an 8-second 1920x1080 video. Beat 1 (0-4s): dark macOS terminal types "npx skills add heygen-com/hyperframes" character by character, then hold on the blinking cursor. Beat 2 (4-5s): the terminal shatters into fragments. Beat 3 (5-8s): bold white kinetic text on black slams in word by word, snappy: "YOU JUST MADE THIS / WITH HYPERFRAMES." Adapt the `code-typing` and `vfx-shatter` registry blocks; hand-author the kinetic text. No narration, no image or media files.
*Rendered from the prompt above, unedited.*
The skeleton isn't just prompting style — the framework enforces a version of it on itself. Since the composition-structure mandate (`0aaac7aa3`, PR #2599), a `hyperframes feedback` report on a visual defect requires a `COMPOSITION_STRUCTURE:` block — element census, attribute presence, timeline shape — auto-filled from the composition's own HTML; the CLI soft-warns (never blocks) when it's missing. Same idea as the six parts above: name the shape explicitly, and both you and the framework reason about it faster.
## The beat formula
The skeleton above structures the *ask*. Inside each beat, describe the *content* with the same five slots every time:
```text theme={null}
[element] what's on screen a giant number · the tweet card · "SHOWREEL"
[motion] what it does counts up with an odometer roll · slides up · fades in per letter
[layout] where it sits top-center · filling the lower half · bottom-right
[style] how it looks dark navy, green accent · 8-bit pixel · thin geometric sans
[timing] when, inside the beat at 1s · over 3s, easing out as it lands · staggered 0.1s apart
```
One sentence per element, slots in any order: *"a giant number **(element)** counts up to \$4.2M with an odometer roll **(motion)**, easing out as it lands **(timing)**, centered **(layout)** in green on dark navy **(style)**."* Elements you don't describe, the agent designs — which is fine when you trust its taste and a drift risk when you don't (see [the specification dial](/prompting/specification-dial)).
Beat-timestamped prompting — `Beat 2 (4-5s): ...` — is HyperFrames' native language. Diffusion video models bolt time segmentation on top of a single clip; here every beat maps directly to a timed clip in the composition, so per-beat descriptions translate losslessly. Use timestamps liberally.
## Common rewrites
The fixes that come up most, as before/after pairs — each exists because of how the engine actually behaves:
**Freezing the hold.** Compositions hold their final state, so a literal "hold" renders a frozen frame — the single biggest cheap-motion tell.
* ❌ `then everything holds motionless to the end`
* ✅ `then everything settles into a gentle ambient idle (breathing scale, slow drift)`
**A duration with no tail.** The subtler version of the same mistake: state a runtime longer than the beats you describe and the leftover seconds become a dead hold by default. Validating this guide's chart example turned up a 12-second ask carrying about five seconds of described content — the builder had to invent the remaining seven. Either shorten the ask to the content, or say what the tail does.
* ❌ `12-second video. [five seconds of beats]`
* ✅ `12-second video. [beats] … then hold ~5s on the finished chart with the leader pulsing once and a slow ambient drift`
**Simultaneity collisions.** Two things "at 4s" overlap for a few frames; the renderer does exactly what you wrote.
* ❌ `at 4s the counter fades out and READY stamps in`
* ✅ `the counter fades out fully by 4.2s; at 4.2s READY stamps in`
**Vague negatives.** "No external assets" is ambiguous — CDN-loaded runtimes are normal infrastructure.
* ❌ `no external assets`
* ✅ `no image or media files`
**Prose where copy belongs.** Unquoted text gets paraphrased; quoted text renders verbatim.
* ❌ `show a tagline about shipping faster`
* ✅ `tagline: "Ship faster."`
**Format-blind numbers.** An odometer needs fixed digit columns — "counts $0 → $4.2M" forces an awkward "\$0.0M" start.
* ❌ `counts from $0 to $4.2M`
* ✅ `counts up to $4.2M`
## The framework's own vocabulary
The skeleton above is how you ask. This is what the agent writes, and it's worth recognizing on sight — when you read a composition, review a diff, or get a lint error, these four are the load-bearing pieces:
| In the file | What it means |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `class="clip"` | Marks a timed section. The framework owns its visibility — never animate a clip's own opacity or `display` to hide it. |
| `data-start` / `data-duration` / `data-track-index` | When the clip begins, how long it runs, and which track it sits on. Two clips on the same track index must not overlap in time. |
| `window.__timelines[""]` | Every GSAP-driven composition registers exactly one paused timeline here, built synchronously at load. The renderer seeks that timeline frame by frame — which is why nothing may depend on wall-clock time or unseeded randomness. Other adapters, including Lottie, CSS animations, and WAAPI, register through their own seekable runtime contracts. |
| `