Skip to main content
Hyperframes is built for AI agents — compositions are plain HTML, the CLI is non-interactive, and the framework ships 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):
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 Optional workflows — add the ones that match your inputs (/hyperframes routes to whichever you’ve installed)
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.

​
Claude Design

Claude Design uses a different setup. Download 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):
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 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 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: 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:
Per-word styling also works:

​
Transitions

Every multi-scene composition benefits from transitions. Describe the energy level: Or describe by mood:

​
Audio-reactive animation

Map audio frequency bands to visual properties. The agent uses these defaults:
Keep audio-reactive effects subtle for text (3–6% intensity). Go bigger for backgrounds (10–30%).

​
Marker highlights

Hand-drawn emphasis effects for text:

​
Text-to-speech voices

HyperFrames supports three TTS providers: HeyGen (Starfish voices, requires sign-in via npx hyperframes auth), ElevenLabs (requires API key), and Kokoro (free, runs locally, no API key needed). The agent asks which provider to use — or picks automatically in autonomous mode. Describe the content and the agent picks a voice, or request one directly:

​
Rendering quality

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

​
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 check 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.
  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

Quickstart

Build and render your first video

Common Mistakes

Pitfalls the linter can’t catch

GSAP Animation

Add fade, slide, scale, and custom animations

Catalog

50+ ready-to-use blocks and components