refactor(skills): consolidate 15 skills into 3

CLAUDE.md

@@ -4,40 +4,22 @@
 
 This repo ships skills that are installed globally via `npx hyperframes skills` (runs automatically during `hyperframes init`). **Always use the appropriate skill instead of writing code from scratch or fetching external docs.**
 
-### HyperFrames Skills (from this repo)
-
-| Skill                    | Invoke with             | When to use                                                                                                                                                                           |
-| ------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **hyperframes-compose**  | `/hyperframes-compose`  | Creating ANY HTML composition — videos, animations, title cards, overlays. Contains required HTML structure, `class="clip"` rules, GSAP timeline patterns, and rendering constraints. |
-| **hyperframes-captions** | `/hyperframes-captions` | Any task involving text synced to audio: captions, subtitles, lyrics, lyric videos, karaoke. Also covers transcription strategy (whisper model selection, transcript format).         |
-| **hyperframes-tts**      | `/hyperframes-tts`      | Generating speech from text: narration, voiceovers, text-to-speech. Voice selection, speed control, and combining TTS output with compositions.                                       |
-| **marker-highlight**     | `/marker-highlight`     | Animated text highlighting — marker sweeps, hand-drawn circles, burst lines, scribble, sketchout. Use with captions for dynamic emphasis.                                             |
-
-### GSAP Skills (from [greensock/gsap-skills](https://github.com/greensock/gsap-skills))
-
-| Skill                  | Invoke with           | When to use                                                                      |
-| ---------------------- | --------------------- | -------------------------------------------------------------------------------- |
-| **gsap-core**          | `/gsap-core`          | `gsap.to()`, `from()`, `fromTo()`, easing, duration, stagger, defaults           |
-| **gsap-timeline**      | `/gsap-timeline`      | Timeline sequencing, position parameter, labels, nesting, playback               |
-| **gsap-performance**   | `/gsap-performance`   | Performance best practices — transforms over layout props, will-change, batching |
-| **gsap-plugins**       | `/gsap-plugins`       | ScrollTrigger, Flip, Draggable, SplitText, and other GSAP plugins                |
-| **gsap-scrolltrigger** | `/gsap-scrolltrigger` | Scroll-linked animations, pinning, scrub, triggers                               |
-| **gsap-utils**         | `/gsap-utils`         | `gsap.utils` helpers — clamp, mapRange, snap, toArray, wrap, pipe                |
+### Skills
+
+| Skill               | Invoke with        | When to use                                                                                                                                         |
+| ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **hyperframes**     | `/hyperframes`     | Creating or editing HTML compositions, captions/subtitles, TTS narration, audio-reactive animation, marker highlights. Composition authoring rules. |
+| **hyperframes-cli** | `/hyperframes-cli` | CLI commands: init, lint, preview, render, transcribe, tts, doctor. Use when scaffolding, validating, previewing, or rendering.                     |
+| **gsap**            | `/gsap`            | GSAP animations — tweens, timelines, easing, ScrollTrigger, plugins (Flip, Draggable, SplitText, etc.), React/Vue/Svelte, performance optimization. |
 
 ### Why this matters
 
-The skills encode HyperFrames-specific patterns (e.g., required `class="clip"` on all timed elements, GSAP timeline registration via `window.__GSAP_TIMELINE`, `data-*` attribute semantics) that are NOT in generic web docs. Skipping the skills and writing from scratch will produce broken compositions.
+The skills encode HyperFrames-specific patterns (e.g., required `class="clip"` on all timed elements, GSAP timeline registration via `window.__timelines`, `data-*` attribute semantics) that are NOT in generic web docs. Skipping the skills and writing from scratch will produce broken compositions.
 
 ### Rules
 
-- When creating or modifying HTML compositions → invoke `/hyperframes-compose` BEFORE writing any code
-- When adding captions, subtitles, lyrics, or any text synced to audio → invoke `/hyperframes-captions` BEFORE writing any code
-- When transcribing audio or choosing a whisper model → invoke `/hyperframes-captions` BEFORE running any transcription tool
-- When generating speech from text (narration, voiceover, TTS) → invoke `/hyperframes-tts` BEFORE running any TTS command
-- When creating a video from audio (music video, lyric video, audio visualizer with text) → invoke BOTH `/hyperframes-compose` AND `/hyperframes-captions`
-- When writing GSAP animations → invoke `/gsap-core` and `/gsap-timeline` BEFORE writing any code
-- When optimizing animation performance → invoke `/gsap-performance` BEFORE making changes
-- When adding animated text emphasis (highlight sweeps, circles, bursts, scribbles) → invoke `/marker-highlight` BEFORE writing any code
+- When creating or modifying HTML compositions, captions, TTS, audio-reactive, or marker highlights → invoke `/hyperframes` BEFORE writing any code
+- When writing GSAP animations (tweens, timelines, ScrollTrigger, plugins) → invoke `/gsap` BEFORE writing any code
 - After creating or editing any `.html` composition → run `npx hyperframes lint` and `npx hyperframes validate` in parallel, fix all errors before opening the studio or considering the task complete. `lint` checks the HTML structure statically; `validate` loads the composition in headless Chrome and catches runtime JS errors, missing assets, and failed network requests. Always validate before `npx hyperframes preview`.
 
 ### Installing skills
@@ -141,7 +123,7 @@ If captions are inaccurate (wrong words, bad timing):
 2. **Set language**: `--language en` to filter non-target speech
 3. **Use an external API**: Transcribe via OpenAI or Groq Whisper API, then import the JSON with `hyperframes transcribe response.json`
 
-See the `/hyperframes-captions` skill for full details on model selection and API usage.
+See the `/hyperframes` skill (references/captions.md and references/transcript-guide.md) for full details on model selection and API usage.
 
 ## Text-to-Speech
 

packages/cli/package.json

@@ -21,7 +21,7 @@
     "build:fonts": "cd ../producer && tsx scripts/generate-font-data.ts",
     "build:studio": "cd ../studio && bun run build",
     "build:runtime": "tsx scripts/build-runtime.ts",
-    "build:copy": "mkdir -p dist/studio dist/docs dist/templates dist/skills && cp -r ../studio/dist/* dist/studio/ && cp -r src/templates/blank src/templates/_shared dist/templates/ && cp -r ../../skills/hyperframes-compose ../../skills/hyperframes-captions ../../skills/hyperframes-tts dist/skills/ && (cp src/docs/*.md dist/docs/ 2>/dev/null || true)",
+    "build:copy": "mkdir -p dist/studio dist/docs dist/templates dist/skills && cp -r ../studio/dist/* dist/studio/ && cp -r src/templates/blank src/templates/_shared dist/templates/ && cp -r ../../skills/hyperframes ../../skills/hyperframes-cli ../../skills/gsap dist/skills/ && (cp src/docs/*.md dist/docs/ 2>/dev/null || true)",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

packages/cli/src/commands/init.ts

@@ -7,6 +7,7 @@ export const examples: Example[] = [
   ["Start from an existing video file", "hyperframes init my-video --video clip.mp4"],
   ["Start from an audio file", "hyperframes init my-video --audio track.mp3"],
   ["Non-interactive mode (for CI or AI agents)", "hyperframes init my-video --non-interactive"],
+  ["Skip AI coding skills installation", "hyperframes init my-video --skip-skills"],
 ];
 import {
   existsSync,
@@ -390,12 +391,17 @@ export default defineCommand({
       type: "boolean",
       description: "Disable interactive prompts (for CI/agents)",
     },
+    "skip-skills": {
+      type: "boolean",
+      description: "Skip AI coding skills installation",
+    },
   },
   async run({ args }) {
     const templateFlag = args.template;
     const videoFlag = args.video;
     const audioFlag = args.audio;
     const skipTranscribe = args["skip-transcribe"] === true;
+    const skipSkills = args["skip-skills"] === true;
     const nonInteractive = args["non-interactive"] === true;
     const modelFlag = args.model;
     const languageFlag = args.language;
@@ -693,17 +699,19 @@ export default defineCommand({
     clack.note(files.map((f) => c.accent(f)).join("\n"), c.success(`Created ${name}/`));
 
     // Offer to install AI coding skills
-    const installSkills = await clack.confirm({
-      message: "Install AI coding skills? (for Claude Code, Cursor, Codex, etc.)",
-      initialValue: true,
-    });
-    if (clack.isCancel(installSkills)) {
-      clack.cancel("Setup cancelled.");
-      process.exit(0);
-    }
-    if (installSkills) {
-      const skillsCmd = await import("./skills.js").then((m) => m.default);
-      await runCommand(skillsCmd, { rawArgs: [] });
+    if (!skipSkills) {
+      const installSkills = await clack.confirm({
+        message: "Install AI coding skills? (for Claude Code, Cursor, Codex, etc.)",
+        initialValue: true,
+      });
+      if (clack.isCancel(installSkills)) {
+        clack.cancel("Setup cancelled.");
+        process.exit(0);
+      }
+      if (installSkills) {
+        const skillsCmd = await import("./skills.js").then((m) => m.default);
+        await runCommand(skillsCmd, { rawArgs: [] });
+      }
     }
 
     // Auto-launch studio preview

packages/cli/src/templates/_shared/CLAUDE.md

@@ -4,13 +4,11 @@
 
 **Always invoke the relevant skill before writing or modifying compositions.** Skills encode framework-specific patterns (e.g., `class="clip"`, `window.__timelines`, `data-*` attributes) that are NOT in generic web docs. Skipping them produces broken compositions.
 
-| Skill                    | Command                 | When to use                                                                                            |
-| ------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------ |
-| **hyperframes-compose**  | `/hyperframes-compose`  | Creating or editing ANY HTML composition — videos, animations, title cards, overlays, sub-compositions |
-| **hyperframes-captions** | `/hyperframes-captions` | Any text synced to audio: captions, subtitles, lyrics, karaoke. Also covers transcription strategy.    |
-| **gsap-core**            | `/gsap-core`            | GSAP tweens: `gsap.to()`, `from()`, `fromTo()`, easing, stagger, defaults                              |
-| **gsap-timeline**        | `/gsap-timeline`        | Timeline sequencing, position parameter, labels, nesting                                               |
-| **gsap-performance**     | `/gsap-performance`     | Animation performance — transforms over layout props, will-change, batching                            |
+| Skill               | Command            | When to use                                                                                                     |
+| ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| **hyperframes**     | `/hyperframes`     | Creating or editing HTML compositions, captions, TTS, audio-reactive animation, marker highlights               |
+| **hyperframes-cli** | `/hyperframes-cli` | CLI commands: init, lint, preview, render, transcribe, tts                                                      |
+| **gsap**            | `/gsap`            | GSAP animations — tweens, timelines, easing, ScrollTrigger, plugins, React/Vue/Svelte, performance optimization |
 
 > **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