refactor(skills): consolidate 15 skills into 3

[jrusso1020]

Summary

• Merge 9 GSAP skills and 6 HyperFrames skills into 3 consolidated skills: gsap, hyperframes, and hyperframes-cli
• Progressive disclosure preserved — core info in SKILL.md, specialized content in references/ loaded on demand
• Fix incorrect window.__GSAP_TIMELINE reference in CLAUDE.md (should be window.__timelines)
• Add --skip-skills flag to hyperframes init to skip skills installation prompt

Motivation

With 15 separate skills, agents must correctly trigger the right subset for any task. A task like "create an animated video with captions" needed 6+ skills to fire — each with ~90% trigger accuracy means ~53% chance of getting all of them. With 3 skills, that same task needs just hyperframes + gsap (~90% both fire).

The key insight: progressive disclosure should happen within a skill (SKILL.md → references/) not between skills. Between-skill progressive disclosure relies on triggering, which is the weakest link. Within-skill progressive disclosure relies on Claude reading a file and following a reference link, which it does reliably.

New structure

skills/
├── gsap/                     # 9 GSAP skills → 1
│   ├── SKILL.md              # Core API + timelines + performance (213 lines)
│   ├── references/           # ScrollTrigger, plugins, utils, React, Vue/Svelte, effects
│   └── scripts/              # extract-audio-data.py
├── hyperframes/              # 5 HyperFrames skills → 1
│   ├── SKILL.md              # Composition authoring rules (132 lines)
│   ├── references/           # Captions, TTS, audio-reactive, marker-highlight, transcript guide
│   ├── house-style.md, patterns.md, data-in-motion.md
│   └── palettes/
└── hyperframes-cli/          # Kept separate (different trigger: CLI usage vs authoring)
    └── SKILL.md              # CLI commands (113 lines)

CLI change

Added --skip-skills flag to hyperframes init:

hyperframes init my-video --skip-skills  # scaffold without skills installation prompt

Test plan

• Invoke /gsap — verify it loads the consolidated GSAP skill with core + timelines + performance
• Invoke /hyperframes — verify it loads composition authoring rules
• Invoke /hyperframes-cli — verify CLI commands skill loads independently
• Ask an agent to "create an animated video with captions" — verify both hyperframes and gsap trigger without needing to invoke 6+ separate skills
• Run hyperframes init test --skip-skills — verify skills prompt is skipped
• Run hyperframes init test — verify skills prompt still appears by default

🤖 Generated with Claude Code

[vanceingalls]

Code Review

Architecture: Solid

The consolidation from 15 → 3 skills is well-motivated. The references/ subdirectory pattern is clean — progressive disclosure within a skill rather than between skills. The --skip-skills CLI flag is implemented correctly.

---

Critical (must fix)

1. overflow: hidden regression in captions

skills/hyperframes/references/captions.md line ~90 says:

CSS safety nets: `max-width`, `overflow: hidden`, `position: absolute`, explicit `height`.

The old skill explicitly warned against this:

overflow: visible — not overflow: hidden. Hidden clips scaled emphasis words and their glow effects. Rely on fitTextFontSize with reduced maxWidth instead.

This will cause rendering bugs — scaled per-word emphasis and glow effects will be clipped. Must revert to overflow: visible.

2. Audio-reactive reference lost its most important operational content

skills/hyperframes/references/audio-reactive.md dropped two critical sections:

• Sampling Frequency — the pattern showing you must sample at 100-200ms intervals with a for loop, not one tween per element. The old skill had a side-by-side ✓/✗ comparison. Without this, agents produce single-tween "audio-reactive" compositions that don't actually react to audio.

• textShadow on Containers — hard-won debugging insight: textShadow on a parent with semi-transparent children (e.g., inactive caption words at rgba(255,255,255,0.3)) renders a visible glow rectangle behind all children instead of per-word glow. Fix: apply scale to container, textShadow to individual active words only.

---

Important (should fix)

3. gsap/references/effects.md over-compressed (65% reduction)

Typewriter section lost:

• Word rotation full code example (type → hold → backspace → next with cursor state management)
• Appending words pattern (building a sentence word-by-word into the same element)
• Spacing with static text (margin-left wrapper, why flex gap breaks cursor positioning)
• Multi-line cursor handoff pattern (hide previous → blink new → pause → solid when typing)

Audio visualizer section lost:

• Spatial mapping conventions (bass left/bottom, treble right/top)
• Fetch vs inline loading patterns with the critical note about wrapping timeline setup inside the fetch callback
• WebGL/Three.js and DOM Elements rendering approaches
• Layering pattern (multiple canvases with z-index)

4. Captions reference lost key patterns

• Caption layer full-width container pattern and explicit warning against left: 50%; transform: translateX(-50%) (causes clipping at composition edges)
• Scale headroom formula: maxWidth = safeWidth / maxScale when per-word styling uses scale > 1.0
• Self-lint placement guidance ("before window.__timelines[id] = tl")

5. Multi-Scene Compositions deleted, not relocated

Removed from house-style.md:

• Hard visibility kills after scene exit tweens
• Vertical zones (bottom 280px reserved for captions)
• Scene overlap prevention during scrubbing

This prevents real rendering bugs. Should be restored to house-style.md or moved to patterns.md.

6. --strict-all dropped from CLI skill

The old hyperframes-cli/SKILL.md documented --strict-all (fail on errors AND warnings) in the render flags table. If this flag still exists in the CLI, it needs documentation.

---

Minor

• Script path in effects.md — scripts/extract-audio-data.py is ambiguous from project root; consider full path skills/gsap/scripts/extract-audio-data.py
• CLAUDE.md — still references class="clip" which doesn't appear in any skill; may be stale
• data-duration="auto" in TTS reference is not documented in the main SKILL.md attributes table
• "Approach" section removed from compose SKILL.md — useful structural framing for agents tackling complex compositions

[jrusso1020]

Thanks for the thorough review @vanceingalls! Addressed all findings in 07ede4b:

Critical — fixed

1. overflow: hidden regression — Changed to overflow: visible in captions reference, added warning about glow clipping, and added scale headroom formula (maxWidth = safeWidth / maxScale). Also added container pattern warning against left: 50%; transform: translateX(-50%).

2. Audio-reactive lost content — Restored both sections:

• Sampling frequency pattern with ✅/❌ comparison (per-frame tl.call loop vs single tween)
• textShadow on containers gotcha (glow rectangle on semi-transparent children)

Important — fixed

3. effects.md over-compressed — Restored all lost typewriter patterns:

• Word rotation with full cursor state management
• Appending words (building sentences word-by-word)
• Spacing with static text (margin-left wrapper, why flex gap breaks)
• Multi-line cursor handoff (hide → blink → pause → solid)

And audio visualizer patterns:

• Spatial mapping conventions (bass left/bottom, treble right/top, circular)
• Fetch vs inline loading with callback wrapping note
• WebGL/Three.js and DOM rendering approaches
• Canvas layering with z-index

4. Captions lost patterns — Restored container pattern warning, scale headroom formula, and self-lint placement guidance ("before window.__timelines[id] = tl").

5. Multi-scene compositions — These were not deleted. house-style.md was copied intact (verified with diff — zero differences). The Scene Pacing section (Build/Breathe/Resolve) is at lines 64-72. It's referenced from SKILL.md via [house-style.md](./house-style.md).

6. --strict-all — Restored to CLI render flags table.

Minor

• Script path — Left as scripts/extract-audio-data.py since it's relative to the skill directory (matches how skills resolve paths)
• class="clip" — Still used in 10+ files across packages/core and packages/cli. The CLAUDE.md reference is accurate.
• data-duration="auto" — This is TTS-specific shorthand documented in the TTS reference; keeping it there rather than adding to the main attributes table where it could confuse non-TTS usage
• "Approach" section — Intentionally removed per skill-creator best practices (body loads after triggering, generic problem-solving steps don't add HyperFrames-specific value). The structural thinking still happens naturally when agents read the data attributes and composition structure sections.