> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-feat-blue-sweater-showcase.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Guide

> How to prompt Claude Code, Cursor, Codex, 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
```

In Claude Code, restart the session after installing. Skills register as **slash commands**:

| Slash command             | What it loads                                                              |
| ------------------------- | -------------------------------------------------------------------------- |
| `/hyperframes`            | Composition authoring — HTML structure, timing, captions, TTS, transitions |
| `/hyperframes-cli`        | CLI commands — `init`, `lint`, `preview`, `render`, `transcribe`, `tts`    |
| `/hyperframes-registry`   | Block and component installation via `hyperframes add`                     |
| `/website-to-hyperframes` | Capture a URL and turn it into a video — full website-to-video pipeline    |
| `/gsap`                   | GSAP animation API — timelines, easing, ScrollTrigger, plugins             |

<Tip>
  Always prefix Hyperframes prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents). This loads the skill context explicitly so the agent gets composition rules right the first time, instead of relying on whatever it remembers about web video.
</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>