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

# Prompt Guide

> How to prompt Claude Code, Cursor, Codex, Google Antigravity, GitHub Copilot CLI, and other AI agents to author Hyperframes compositions — with copy-pasteable examples and vocabulary tables.

Hyperframes is built for AI agents — compositions are plain HTML, the CLI is non-interactive, and the framework ships [skills](https://github.com/vercel-labs/skills) that teach agents the patterns docs alone don't cover. This guide shows how to prompt agents effectively once skills are installed — the vocabulary that changes output, the iteration patterns that save time, and the rules that prevent breakage.

## One-time setup

Install the skills in your project (or globally for your agent):

```bash theme={null}
npx skills add heygen-com/hyperframes
```

The installer shows a picker. Select the **core skills** below — every project needs them. In Claude Code, restart the session after installing; the skills register as **slash commands**. Start at `/hyperframes`: it orients you to the whole surface and routes "make me a video" requests to the right workflow.

**Core skills — install all of these**

| Slash command            | What it loads                                                                                                                                 |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `/hyperframes`           | **Read first.** The entry skill — capability map + video router; sends "make me a video" intent to the right workflow                         |
| `/hyperframes-core`      | Composition contract — HTML structure, `data-*` attributes, clips, tracks                                                                     |
| `/hyperframes-animation` | All animation — motion rules, scene blueprints, transitions, and the runtime adapters (GSAP, Lottie, Three.js, Anime.js, CSS, WAAPI, TypeGPU) |
| `/hyperframes-creative`  | Creative direction — design spec, palettes, typography, narration, beats                                                                      |
| `/hyperframes-cli`       | Dev-loop CLI — `init`, `lint`, `inspect`, `preview`, `render`, `doctor`                                                                       |
| `/hyperframes-media`     | Asset preprocessing — `tts`, `transcribe`, `remove-background`                                                                                |
| `/hyperframes-registry`  | Block and component installation via `hyperframes add`                                                                                        |
| `/general-video`         | The general authoring workflow — fallback for any video that doesn't match a specific workflow below                                          |

**Optional workflows — add the ones that match your inputs** (`/hyperframes` routes to whichever you've installed)

| Slash command              | Input → output                                                                          |
| -------------------------- | --------------------------------------------------------------------------------------- |
| `/product-launch-video`    | A product URL / brief / script → launch or promo video                                  |
| `/website-to-video`        | A general website / URL → a video of the site (tour / showcase / social clip)           |
| `/faceless-explainer`      | Arbitrary text (no URL) → faceless explainer with its own TTS narration                 |
| `/pr-to-video`             | A GitHub PR → code-change explainer                                                     |
| `/embedded-captions`       | An existing talking-head video → the same footage with captions / subtitles             |
| `/talking-head-recut`      | An existing talking-head video → footage packaged with designed graphic cards           |
| `/motion-graphics`         | A short, unnarrated, design-led motion graphic (logo sting, kinetic type, stat / chart) |
| `/remotion-to-hyperframes` | Port an existing Remotion (React) composition to HyperFrames HTML                       |

<Tip>
  To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all`. And start Hyperframes prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents) — it loads the routing + composition context explicitly so the agent picks the right workflow and gets the rules right the first time.
</Tip>

## Claude Design

Claude Design uses a different setup. Download [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) from GitHub (click the ↓ button), then **attach it to your chat** (don't paste the URL — file attachments produce better output):

```text theme={null}
Use the attached skill. 25-second LinkedIn video for my startup.

Problem: Sales teams waste 3 hours/day on manual CRM updates.
Solution: AutoCRM — AI that logs every call, email, and meeting.
Traction: 200+ teams, $1.2M ARR, 18% MoM growth.
CTA: autocrmhq.com
```

Claude Design produces a valid first draft (brand identity, scene content, animations, transitions). Download the ZIP and refine in any AI coding agent with `npx hyperframes preview` running. See the [Claude Design guide](/guides/claude-design) for the full workflow.

## The two prompt shapes

Most successful Hyperframes prompts fall into one of two shapes.

### Cold start — describe the video

You tell the agent what you want from scratch. Best for greenfield work where you have the creative direction in your head.

> Using `/hyperframes`, create a 10-second product intro with a fade-in title over a dark background and subtle background music.

> Make a 9:16 TikTok-style hook video about \[topic] using `/hyperframes`, with bouncy captions synced to a TTS narration.

Cold-start prompts work best when you specify:

* **Duration** (e.g. "10 seconds", "30s", "5 scenes of 3s each")
* **Aspect ratio** ("16:9", "9:16 vertical", "1:1 square") — defaults to 1920x1080 otherwise
* **Mood / style** ("minimal Swiss grid", "warm grain analog", "high-energy social")
* **Key elements** (title, lower third, captions, background video, music)

### Warm start — turn context into a video

You give the agent something to work with — a URL, a doc, a CSV, a transcript — and ask it to synthesize that into a video. This is where Hyperframes shines because the agent does the research/summarization step *and* the production step in one flow.

> Take a look at this GitHub repo [https://github.com/heygen-com/hyperframes](https://github.com/heygen-com/hyperframes) and explain its uses and architecture to me using `/hyperframes`.

> Summarize the attached PDF into a 45-second pitch video using `/hyperframes`.

> Read this changelog and turn the top three changes into a 30-second release announcement video using `/hyperframes`.

> Turn this CSV into an animated bar chart race using `/hyperframes`.

Warm-start prompts produce richer, more grounded videos because the agent is writing about *something specific* instead of inventing copy.

## Iterating

Hyperframes is a conversation. After the first render, talk to the agent the way you'd talk to a video editor — don't re-prompt from scratch:

> Make the title 2x bigger.

> Swap to dark mode.

> Add a fade-out at the end and a lower third at 0:03 with my name and title.

> The captions are too small and they overlap the lower third. Move them up and shrink them.

> Replace the background music with `assets/track.mp3`.

The agent already has the composition open and the skills loaded — small targeted edits produce better results than long re-specifications.

## Vocabulary that changes output

The skills map natural-language adjectives to specific framework settings. Using the right word gets you the right result without specifying technical details.

### Motion & easing

Describe how motion should *feel* and the agent picks the matching GSAP ease:

| Say this | Agent uses    | Feels like              |
| -------- | ------------- | ----------------------- |
| smooth   | `power2.out`  | Natural deceleration    |
| snappy   | `power4.out`  | Quick and decisive      |
| bouncy   | `back.out`    | Overshoots then settles |
| springy  | `elastic.out` | Oscillates into place   |
| dramatic | `expo.out`    | Fast start, long glide  |
| dreamy   | `sine.inOut`  | Slow, symmetrical       |

**Timing shorthand:** fast (0.2s) = energy, medium (0.4s) = professional, slow (0.6s) = luxury, very slow (1–2s) = cinematic.

### Caption tones

Describe the *energy* of your captions and the agent picks matching typography, size, and animation:

| Tone         | Typography         | Animation    | Size range |
| ------------ | ------------------ | ------------ | ---------- |
| Hype         | Heavy weight fonts | Scale-pop    | 72–96px    |
| Corporate    | Clean sans-serif   | Fade + slide | 56–72px    |
| Tutorial     | Monospace          | Typewriter   | 48–64px    |
| Storytelling | Serif              | Slow fade    | 44–56px    |
| Social       | Rounded, playful   | Bounce       | 56–80px    |

```
"Hype-style captions with scale-pop"
"Calm, elegant subtitles with slow fades"
"Karaoke-style word highlighting"
```

Per-word styling also works:

```
"Make brand names larger with accent color"
"Add bounce to emotional keywords"
"Highlight numbers differently"
```

### Transitions

Every multi-scene composition benefits from transitions. Describe the energy level:

| Energy | CSS option     | Shader option       |
| ------ | -------------- | ------------------- |
| Calm   | Blur crossfade | Cross-warp morph    |
| Medium | Push slide     | Whip pan            |
| High   | Zoom through   | Glitch, ridged burn |

Or describe by mood:

```
"Warm transitions for this wellness brand"
"Cold, clinical transitions for tech"
"Playful bouncy transitions"
"Dramatic zoom for the reveal"
```

### Audio-reactive animation

Map audio frequency bands to visual properties. The agent uses these defaults:

| Audio band | Maps to   | Visual effect     |
| ---------- | --------- | ----------------- |
| Bass       | `scale`   | Pulse on the beat |
| Treble     | `glow`    | Shimmer intensity |
| Amplitude  | `opacity` | Breathing         |
| Mids       | `shape`   | Morphing          |

```
"Make the text pulse with the beat"
"Add bass-driven scale to the logo"
"Create glow that responds to treble"
```

<Tip>
  Keep audio-reactive effects subtle for text (3–6% intensity). Go bigger for backgrounds (10–30%).
</Tip>

### Marker highlights

Hand-drawn emphasis effects for text:

| Mode        | Effect             | Best for     |
| ----------- | ------------------ | ------------ |
| `highlight` | Marker sweep       | Key phrases  |
| `circle`    | Hand-drawn ellipse | Single words |
| `burst`     | Radiating lines    | Hype moments |
| `scribble`  | Chaotic scratch    | Crossing out |
| `sketchout` | Rectangle outline  | Callouts     |

```
"Add a marker highlight sweep on 'revolutionary'"
"Circle this keyword with hand-drawn effect"
"Add burst lines around 'AMAZING'"
```

### Text-to-speech voices

TTS runs locally via Kokoro (no API key needed). Describe the content and the agent picks a voice, or request one directly:

| Content type | Recommended voices     |
| ------------ | ---------------------- |
| Product demo | `af_heart`, `af_nova`  |
| Tutorial     | `am_adam`, `bf_emma`   |
| Marketing    | `af_sky`, `am_michael` |

```
"Generate narration for this script"
"Create voiceover with a professional female voice"
"Add TTS with British male voice at 1.1x speed"
```

### Rendering quality

| Quality    | Use for             |
| ---------- | ------------------- |
| `draft`    | Fast iteration      |
| `standard` | Review and feedback |
| `high`     | Final delivery      |

```
"Quick draft render"
"Render at high quality"
"Export as transparent WebM"
```

## Rules to know

The skills enforce these automatically, but if you hand-edit compositions or debug issues, these are the rules that matter:

1. **Register all timelines** on `window.__timelines` — the renderer can't seek animations it doesn't know about.
2. **Video elements must be `muted`** — audio goes in separate `<audio>` elements so the renderer can mix it.
3. **No `Math.random()`** — random values produce different frames on each render, breaking determinism. Use a seeded PRNG (e.g. mulberry32) if you need pseudo-random values.
4. **Synchronous timeline construction** — no `async`/`await` or `fetch()` during GSAP timeline setup.
5. **Timed elements need `class="clip"`** — plus `data-start`, `data-duration`, and `data-track-index`.
6. **Add entrance animations to every scene** — elements appearing without animation feel broken on video.
7. **Add transitions between scenes** — jump cuts between scenes are almost always unintentional in composed video.

<Warning>
  Rules 1–5 are technical requirements — breaking them produces incorrect renders. Rules 6–7 are best practices that the skills apply by default. You can override them when you have a reason to.
</Warning>

## Anti-patterns

Things that cause friction (or wrong output):

* **Don't ask for React / Vue components.** Hyperframes compositions are plain HTML with `data-*` attributes and a GSAP timeline. Asking for "a React component for the intro" forces the agent to translate later.
* **Don't ask for 4K or 60fps unless you need it.** Defaults (1920×1080, 30fps) render fast and look great. Higher specs slow rendering meaningfully.
* **Don't skip the slash command.** Without `/hyperframes`, the agent may guess at HTML video conventions instead of using the framework's actual rules (`class="clip"` on timed elements, `window.__timelines` registration, etc.).
* **Don't paste long error logs into the prompt without context.** Run `npx hyperframes lint` and `npx hyperframes validate` first — lint catches structural issues, validate catches runtime errors (JS exceptions, missing assets, contrast problems).
* **Don't assume the agent knows your assets.** Mention file paths explicitly (`assets/intro.mp4`, `assets/logo.png`) — the agent will check what's there but a hint speeds it up.

## Recommended workflow

1. `npx hyperframes init my-video` — scaffold a project (skills install automatically)
2. Open the project in Claude Code (or Cursor / Codex)
3. Prompt with `/hyperframes` and one of the shapes above
4. `npx hyperframes preview` — watch in the browser as the agent edits
5. Iterate with small targeted prompts
6. `npx hyperframes render --output final.mp4` when you're happy

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Build and render your first video
  </Card>

  <Card title="Common Mistakes" icon="circle-exclamation" href="/guides/common-mistakes">
    Pitfalls the linter can't catch
  </Card>

  <Card title="GSAP Animation" icon="wand-magic-sparkles" href="/guides/gsap-animation">
    Add fade, slide, scale, and custom animations
  </Card>

  <Card title="Catalog" icon="grid-2" href="/catalog/blocks/data-chart">
    50+ ready-to-use blocks and components
  </Card>
</CardGroup>