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               |
+
+<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>
+
+## 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"
+```
+
+<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>
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index fef8ef91e..bc067e03d 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -13,11 +13,34 @@ 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 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 — `/hyperframes` for composition authoring, `/hyperframes-cli` for CLI commands, and `/gsap` for animation help. Invoking the slash command loads the skill context explicitly, which produces correct output the first time.
 
-> "Create a 10-second product intro with a fade-in title over a dark background and subtle background music"
+### Try it: example prompts
 
-The agent handles scaffolding, animation, and rendering. You can iterate by describing changes ("make the title bigger", "add a slide-in lower third at 3 seconds").
+Copy any of these into your agent to get started.
+
+<CardGroup cols={1}>
+  <Card title="Cold start — describe what you want">
+    > Using `/hyperframes`, create a 10-second product intro with a fade-in title over a dark background and subtle background music.
+  </Card>
+  <Card title="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`.
+  </Card>
+  <Card title="Format-specific">
+    > Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration.
+  </Card>
+  <Card title="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.
+  </Card>
+</CardGroup>
+
+The agent handles scaffolding, animation, and rendering. See the [prompting guide](/guides/prompting) for more patterns.
 
 <Tip>
   Skills encode HyperFrames-specific patterns — like required `class="clip"` on timed elements, GSAP timeline registration, and `data-*` attribute semantics — that are not in generic web docs. Using skills produces correct compositions from the start.
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
index 17fa7c4be..43a0d5f48 100644
--- a/packages/cli/src/commands/init.ts
+++ b/packages/cli/src/commands/init.ts
@@ -552,10 +552,16 @@ export default defineCommand({
         `     ${c.accent(`cd ${name}`)} then start ${c.accent("Claude Code")}, ${c.accent("Cursor")}, or your preferred agent`,
       );
       console.log();
-      console.log(`  ${c.accent("3.")} Preview in the browser:`);
+      console.log(`  ${c.accent("3.")} Try a starter prompt:`);
+      console.log(
+        `     ${c.dim('"Using /hyperframes, create a 15-second intro about [your topic]"')}`,
+      );
+      console.log(`     ${c.dim("More patterns: hyperframes.heygen.com/guides/prompting")}`);
+      console.log();
+      console.log(`  ${c.accent("4.")} Preview in the browser:`);
       console.log(`     ${c.accent(`cd ${name}`)} && ${c.accent("npx hyperframes preview")}`);
       console.log();
-      console.log(`  ${c.accent("4.")} Render to MP4 when ready:`);
+      console.log(`  ${c.accent("5.")} Render to MP4 when ready:`);
       console.log(`     ${c.accent(`cd ${name}`)} && ${c.accent("npx hyperframes render")}`);
       console.log();
       console.log(`  ${c.dim("Full docs: hyperframes.heygen.com")}`);
diff --git a/packages/cli/src/commands/skills.ts b/packages/cli/src/commands/skills.ts
index 1ea917d46..e0433c075 100644
--- a/packages/cli/src/commands/skills.ts
+++ b/packages/cli/src/commands/skills.ts
@@ -27,15 +27,12 @@ function runSkillsAdd(repo: string): Promise<void> {
   });
 }
 
-const SOURCES = [
-  { name: "HyperFrames", repo: "heygen-com/hyperframes" },
-  { name: "GSAP", repo: "greensock/gsap-skills" },
-];
+const SOURCES = [{ name: "HyperFrames", repo: "heygen-com/hyperframes" }];
 
 export default defineCommand({
   meta: {
     name: "skills",
-    description: "Install HyperFrames and GSAP skills for AI coding tools",
+    description: "Install HyperFrames skills for AI coding tools",
   },
   args: {},
   async run() {
diff --git a/packages/cli/src/templates/_shared/AGENTS.md b/packages/cli/src/templates/_shared/AGENTS.md
index ac0d7ac74..506ecf394 100644
--- a/packages/cli/src/templates/_shared/AGENTS.md
+++ b/packages/cli/src/templates/_shared/AGENTS.md
@@ -5,8 +5,7 @@
 This project uses AI agent skills for framework-specific patterns. Install them if not already present:
 
 ```bash
-npx skills add heygen-com/hyperframes   # HyperFrames composition skills
-npx skills add greensock/gsap-skills     # GSAP animation skills
+npx skills add heygen-com/hyperframes
 ```
 
 Skills encode patterns like `window.__timelines` registration, `data-*` attribute semantics, and shader-compatible CSS rules that are not in generic web docs. Using them produces correct compositions from the start.
diff --git a/packages/cli/src/templates/_shared/CLAUDE.md b/packages/cli/src/templates/_shared/CLAUDE.md
index 2106a5451..8863c999c 100644
--- a/packages/cli/src/templates/_shared/CLAUDE.md
+++ b/packages/cli/src/templates/_shared/CLAUDE.md
@@ -11,8 +11,7 @@
 | **gsap**            | `/gsap`            | GSAP animations for HyperFrames — tweens, timelines, easing, performance                          |
 
 > **Skills not available?** Ask the user to run `npx hyperframes skills` and restart their
-> agent session, or install manually: `npx skills add heygen-com/hyperframes` and
-> `npx skills add greensock/gsap-skills`.
+> agent session, or install manually: `npx skills add heygen-com/hyperframes`.
 
 ## Commands