feat(skills): add contribute skill for registry block authoring

New skill that guides users through the full workflow of contributing
caption styles, VFX blocks, transitions, and other components to the
HyperFrames registry.

Covers: scaffolding, proven patterns (seeded PRNG, paused timelines,
hard kills, unique ID prefixes), validation, rendering, and PR prep.

Includes copy-paste HTML templates for caption and Three.js components
with all the non-negotiable rules baked in.

Tested by an unbiased agent with zero prior HyperFrames knowledge —
built a working cap-typewriter component that passed lint and validate
on the first attempt. Feedback incorporated: per-character animation
guidance, monospace font size exceptions, positioning variants, and
PREFIX naming convention table.

Author: miguel-heygen

skills/contribute/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: contribute
+description: Scaffold, build, validate, and ship new HyperFrames registry components (caption styles, VFX blocks, transitions, lower thirds). Guides the full workflow from idea to merged PR. Use when user says "contribute", "new component", "add a block", "create a caption style", "build a transition", or wants to add something to the HyperFrames registry.
+---
+
+# Contribute to HyperFrames Registry
+
+Guide the user from idea to merged PR for a new registry block.
+
+## Workflow
+
+```
+1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship
+```
+
+### Step 1: Clarify
+
+Ask what they're building:
+
+- **Caption style** — word-level karaoke, specific animation/highlight pattern
+- **VFX block** — Three.js 3D effect, shader, particle system
+- **Transition** — scene-to-scene transition effect
+- **Block** — lower third, social card, title card, data viz
+
+Then ask:
+- One-sentence description of the effect
+- Visual reference (URL, screenshot, or description)
+- Who uses this and when?
+
+### Step 2: Scaffold
+
+Create the registry block structure in the hyperframes repo:
+
+```
+registry/blocks/{block-name}/
+  {block-name}.html
+  registry-item.json
+```
+
+**Naming convention:**
+
+| Block name | ID prefix for elements | Example IDs |
+|-----------|----------------------|-------------|
+| `cap-hormozi` | `hz` | `hz-cg-0`, `hz-cw-3` |
+| `cap-typewriter` | `tw` | `tw-cg-0`, `tw-ch-0-5` |
+| `vfx-chrome` | `vc` | `vc-canvas` |
+
+Use a 2-3 letter prefix derived from the block name. ALL element IDs in the composition must use this prefix to avoid collisions when embedded as sub-compositions.
+
+**registry-item.json template:**
+
+```json
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "{block-name}",
+  "type": "hyperframes:block",
+  "title": "{Human Title}",
+  "description": "{one sentence}",
+  "stability": "experimental",
+  "dimensions": { "width": 1920, "height": 1080 },
+  "duration": 10,
+  "tags": ["{category}", "{subcategory}"],
+  "files": [
+    {
+      "path": "{block-name}.html",
+      "target": "compositions/{block-name}.html",
+      "type": "hyperframes:composition"
+    }
+  ]
+}
+```
+
+### Step 3: Build
+
+Apply the correct template based on component type. See [templates.md](templates.md) for copy-paste starters.
+
+#### Caption blocks
+
+Read the captions reference in the hyperframes skill BEFORE writing.
+
+**Non-negotiable caption rules:**
+- Font: **96px minimum** for proportional fonts (Montserrat, Figtree). **64-72px is acceptable for monospace** (JetBrains Mono, Chakra Petch) since monospace characters are wider.
+- Readability: `-webkit-text-stroke: 2-3px` OR multi-layer `text-shadow`
+- Overflow: call `window.__hyperframes.fitTextFontSize()` on every group
+- Karaoke: highlight active word via `tl.to(wordEl, { color/scale }, WORDS[wi].start)`
+- Hard kill: `tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)` on EVERY group
+- **Never use `tl.from(el, { opacity: 0 })` at the same position as `tl.set(el, { opacity: 1 })`** — the from clobbers the set. Use `tl.to` instead.
+
+**Per-character animation** (typewriter, scramble, fade-in letter by letter):
+- Wrap each character in its own `<span>` with ID `{prefix}-ch-{groupIndex}-{charIndex}`
+- Stagger `tl.set(charSpan, { opacity: 1 }, charStartTime)` at computed intervals based on the word timestamps
+- For cursors and decorative elements: use `tl.set` at fixed intervals for blinking — NOT CSS animation (not seekable)
+
+**Positioning variants:**
+- Centered (default): `display: flex; align-items: center; justify-content: center;`
+- Lower-third centered: `position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;`
+- Left-aligned: `position: absolute; bottom: 100px; left: 120px; text-align: left;`
+- Right-aligned: `position: absolute; bottom: 100px; right: 120px; text-align: right;`
+
+#### VFX blocks (Three.js)
+
+- Use `three@0.147.0` from CDN (global script, not ES modules)
+- `tl.eventCallback("onUpdate", renderScene); renderScene();` — NO requestAnimationFrame
+- State proxy pattern: GSAP animates plain JS object, render function applies to Three.js
+- Seeded PRNG (`mulberry32`) for any randomness
+
+#### All component types
+
+- `data-composition-id` MUST match `window.__timelines["id"]`
+- All element IDs prefixed with block abbreviation (see naming table above)
+- `gsap.timeline({ paused: true })` — always paused
+- No `Math.random()`, no `Date.now()`
+- Duration from `data-duration`, not GSAP timeline length
+
+### Step 4: Validate
+
+Run these in order. All must pass before proceeding.
+
+```bash
+hyperframes lint                    # 0 errors required
+hyperframes validate --no-contrast  # 0 console errors required
+```
+
+Common fixes:
+- `timed_element_missing_clip_class` → add `class="clip"` to timed elements
+- `timeline_id_mismatch` → make `window.__timelines["X"]` match `data-composition-id="X"`
+- `composition_file_too_large` → warning only, acceptable for complex blocks
+
+### Step 5: Preview
+
+```bash
+hyperframes render -o preview.mp4
+hyperframes snapshot --at "1.0,3.0,5.0,7.0"
+```
+
+Inspect every snapshot:
+- [ ] Text readable at 50% zoom (captions)
+- [ ] Animation visible at every timestamp (no blank frames)
+- [ ] No overflow or clipping
+
+### Step 6: Ship
+
+1. Create branch: `git checkout -b feat/registry-{block-name}`
+2. Format: `npx oxfmt registry/blocks/{block-name}/*.html`
+3. Stage only registry files: `git add registry/blocks/{block-name}/`
+4. Commit with descriptive message
+5. Push and open PR with rendered MP4 preview linked
+
+## Quality Gate
+
+Before opening the PR, verify:
+
+- [ ] `hyperframes lint` → 0 errors
+- [ ] `hyperframes validate` → 0 console errors
+- [ ] Preview video shows the effect clearly
+- [ ] All IDs unique and prefixed with block abbreviation
+- [ ] `npx oxfmt --check` passes on HTML files