From 237847e5c68f2a35ee39b617bcc335eb9c39913c Mon Sep 17 00:00:00 2001 From: James Russo Date: Wed, 15 Apr 2026 22:22:46 -0700 Subject: [PATCH] docs: add prompt cookbook + prompting guide for AI agents (#286) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: add prompt cookbook + prompting guide for AI agents Addresses user feedback that there's no guidance on how to actually prompt Claude Code (or other agents) once the hyperframes skills are installed. Adds copy-pasteable example prompts in the README and quickstart, a new prompting guide page, and a starter-prompt nudge in the `hyperframes init` output. Co-Authored-By: Claude Opus 4.6 (1M context) * docs(prompting): add vocabulary tables, rules, and TTS voice guide Merges the best content from the internal prompt guide into prompting.mdx: easing vocabulary, caption tone table, transition energy matrix, audio-reactive frequency mapping, marker highlight modes, TTS voice recommendations, rendering quality presets, and framework rules (technical requirements vs best practices). Co-Authored-By: Claude Opus 4.6 (1M context) * docs(prompting): rename page title to "Prompt Guide" Co-Authored-By: Claude Opus 4.6 (1M context) * chore: remove greensock/gsap-skills dependency, fix Math.random nuance The bundled skills/gsap/ already covers the GSAP surface needed for HyperFrames compositions. Installing greensock/gsap-skills on top adds a competing full-ecosystem skill that's mostly irrelevant (ScrollTrigger, Draggable, SplitText, etc.) and can confuse agents about which GSAP context to load. Also adds seeded-PRNG nuance to the Math.random() rule in the prompt guide (matching the skill's actual guidance). Removed from: skills.ts, README, AGENTS.md, shared AGENTS.md/CLAUDE.md, and prompting.mdx. Co-Authored-By: Claude Opus 4.6 (1M context) * chore: require minimal reproduction link in bug report template Adds a required "Link to reproduction" input field asking users to push a minimal repro to a public GitHub repo (scaffolded via `hyperframes init repro --non-interactive --example blank`). Also consolidates the OS/Node/FFmpeg/version fields into a single "Environment" field using `npx hyperframes info` output — fewer fields to fill, more consistent data. Follows the same pattern as Next.js and Gatsby issue templates. Co-Authored-By: Claude Opus 4.6 (1M context) * fix(issue-template): use hyperframes doctor for environment info `hyperframes info` only prints project metadata (resolution, duration, elements). `hyperframes doctor` prints the full environment: version, Node.js, FFmpeg, Chrome, memory, disk, Docker — everything needed to diagnose bugs. Co-Authored-By: Claude Opus 4.6 (1M context) * docs(prompting): mention validate alongside lint in anti-patterns Per Vance's review comment — validate catches runtime errors (JS exceptions, missing assets, contrast) that lint doesn't. Co-Authored-By: Claude Opus 4.6 (1M context) * docs: replace libretto example URL with hyperframes repo Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- .github/ISSUE_TEMPLATE/bug.yml | 62 ++--- AGENTS.md | 3 +- README.md | 33 ++- docs/docs.json | 1 + docs/guides/prompting.mdx | 260 +++++++++++++++++++ docs/quickstart.mdx | 29 ++- packages/cli/src/commands/init.ts | 10 +- packages/cli/src/commands/skills.ts | 7 +- packages/cli/src/templates/_shared/AGENTS.md | 3 +- packages/cli/src/templates/_shared/CLAUDE.md | 3 +- 10 files changed, 355 insertions(+), 56 deletions(-) create mode 100644 docs/guides/prompting.mdx diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 746900d69..02a81272a 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -8,6 +8,7 @@ body: Thanks for taking the time to report a bug! Before filing, please: - Search [existing issues](https://github.com/heygen-com/hyperframes/issues) to avoid duplicates - Make sure the issue reproduces without custom extensions or plugins + - Test on the latest version (`npx hyperframes upgrade`) - type: textarea id: description @@ -17,13 +18,27 @@ body: validations: required: true + - type: input + id: reproduction-link + attributes: + label: Link to reproduction + description: | + A link to a **public** GitHub repository with a minimal reproduction of the issue. + + Start from a clean project with `npx hyperframes init repro --non-interactive --example blank`, make only the changes needed to demonstrate the bug, push to a public repo, and paste the link here. + + **Issues without a minimal reproduction may be closed.** A reproduction helps us diagnose and fix your issue faster — often in hours instead of days. + placeholder: "https://github.com/username/my-hyperframes-repro" + validations: + required: true + - type: textarea id: reproduction attributes: label: Steps to reproduce - description: Minimal steps to reproduce the behavior. + description: Step-by-step instructions using the linked reproduction. placeholder: | - 1. Create a composition with... + 1. Clone the repo above 2. Run `npx hyperframes render` 3. See error... validations: @@ -45,40 +60,17 @@ body: validations: required: true - - type: dropdown - id: os + - type: textarea + id: environment attributes: - label: Operating System - options: - - macOS - - Linux (Ubuntu/Debian) - - Linux (Other) - - Windows - - Other - validations: - required: true - - - type: input - id: node-version - attributes: - label: Node.js version - placeholder: "e.g., 22.12.0" - validations: - required: true - - - type: input - id: ffmpeg-version - attributes: - label: FFmpeg version - placeholder: "e.g., 7.1" - validations: - required: true - - - type: input - id: hyperframes-version - attributes: - label: Hyperframes version - placeholder: "e.g., 0.1.0" + label: Environment + description: Run `npx hyperframes doctor` and paste the output here. + render: shell + placeholder: | + ✓ Version 0.x.x (latest) + ✓ Node.js v22.x.x (darwin arm64) + ✓ FFmpeg ffmpeg version 7.x ... + ✓ Chrome bundled: /path/to/chrome validations: required: true diff --git a/AGENTS.md b/AGENTS.md index f68c11e3b..19f951973 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,8 +7,7 @@ Open-source video rendering framework: write HTML, render video. This repo ships AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. ```bash -npx skills add heygen-com/hyperframes # HyperFrames skills -npx skills add greensock/gsap-skills # GSAP animation skills +npx skills add heygen-com/hyperframes ``` ## Build & Test diff --git a/README.md b/README.md index 402ef6655..23cc8e4c5 100644 --- a/README.md +++ b/README.md @@ -31,11 +31,35 @@ Install the HyperFrames skills, then describe the video you want: npx skills add heygen-com/hyperframes ``` -This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions and GSAP animations. Then just prompt it: +This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions and GSAP animations. In Claude Code, the skills register as slash commands — invoke `/hyperframes` to author compositions, `/hyperframes-cli` for CLI commands, and `/gsap` for animation help. -> "Create a 10-second product intro video with a fade-in title, a background video, and background music" +#### Try it: example prompts -The agent handles scaffolding, animation, and rendering. +Copy any of these into your agent to get started. The `/hyperframes` prefix loads the skill context explicitly so you get correct output the first time. + +**Cold start — describe what you want:** + +> Using `/hyperframes`, create a 10-second product intro with a fade-in title, a background video, and background music. + +**Warm start — turn existing context into a video:** + +> 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`. + +> Turn this CSV into an animated bar chart race using `/hyperframes`. + +**Format-specific:** + +> Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration. + +**Iterate — talk to the agent like a video editor:** + +> Make the title 2x bigger, swap to dark mode, and add a fade-out at the end. + +> Add a lower third at 0:03 with my name and title. + +The agent handles scaffolding, animation, and rendering. See the [prompting guide](https://hyperframes.heygen.com/guides/prompting) for more patterns. ### Option 2: Start a project manually @@ -126,8 +150,7 @@ Full documentation at **[hyperframes.heygen.com/introduction](https://hyperframe HyperFrames ships [skills](https://github.com/vercel-labs/skills) that teach AI agents framework-specific patterns that generic docs don't cover. ```bash -npx skills add heygen-com/hyperframes # HyperFrames skills -npx skills add greensock/gsap-skills # GSAP animation skills +npx skills add heygen-com/hyperframes ``` | Skill | What it teaches | diff --git a/docs/docs.json b/docs/docs.json index 9a9d9d9e0..9e9b5129a 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -69,6 +69,7 @@ { "group": "Guides", "pages": [ + "guides/prompting", "guides/gsap-animation", "guides/rendering", "guides/common-mistakes", diff --git a/docs/guides/prompting.mdx b/docs/guides/prompting.mdx new file mode 100644 index 000000000..be2f0325a --- /dev/null +++ b/docs/guides/prompting.mdx @@ -0,0 +1,260 @@ +--- +title: Prompt Guide +description: "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 +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` | +| `/gsap` | GSAP animation API — timelines, easing, ScrollTrigger, plugins | + + + 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. + + +## 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: + +| 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" +``` + + + Keep audio-reactive effects subtle for text (3–6% intensity). Go bigger for backgrounds (10–30%). + + +### 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 `