feat(skills): contribute skill for registry block authoring

docs/contributing/catalog.mdx

@@ -0,0 +1,186 @@
+---
+title: Contributing to the Catalog
+description: How to add blocks and components to the HyperFrames registry.
+---
+
+Your agent already knows how to build video components. It writes HTML. HyperFrames renders it. The registry is the collection of everything that's been built — 52 blocks and counting.
+
+This guide shows you how to add to it.
+
+<Info>
+**Quick version** — Fork the repo. Write one HTML file with a paused GSAP timeline. Add `registry-item.json`. Run `hyperframes lint` + `validate`. Publish with `npx hyperframes publish`. Open a PR.
+</Info>
+
+## Why Contribute?
+
+Every block in the registry exists because someone needed it and built it. When you add a block, every HyperFrames user gets it with one command:
+
+```bash
+npx hyperframes add instagram-follow
+```
+
+The registry grows, HyperFrames gets more useful, and your work ships to everyone.
+
+## Two Paths
+
+### Ideas (No Code)
+
+You spot visual trends before anyone. That's the most valuable contribution.
+
+- Screen-record a caption style from TikTok/YouTube that doesn't exist yet
+- Sketch a lower-third in Figma with fonts, colors, and timing
+- Install a component, preview it, report what feels off
+
+Open an issue on [GitHub](https://github.com/heygen-com/hyperframes/issues) with a visual reference. Tag it `component-request`.
+
+<Tip>The bar for ideas is low. We'd rather have 100 and build the best 10.</Tip>
+
+### Build It
+
+Every block is a single HTML file. No build step, no framework.
+
+If you use Claude Code with HyperFrames skills:
+
+> "I want to contribute a new transition that looks like \[description\]"
+
+The `/contribute-catalog` skill scaffolds the structure, validates, renders a preview, publishes to [hyperframes.dev](https://hyperframes.dev), and prepares the PR.
+
+## What Goes in the Registry
+
+**Blocks** (`registry/blocks/`) — full standalone compositions. Fixed dimensions, fixed duration. Caption styles, VFX effects, title cards, transitions.
+
+**Components** (`registry/components/`) — reusable snippets. No fixed size. CSS effects, text treatments, overlays that adapt to any composition.
+
+### Structure
+
+```
+registry/blocks/my-block/
+  my-block.html           ← the composition
+  registry-item.json      ← metadata
+```
+
+### registry-item.json
+
+```json
+{
+  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
+  "name": "my-block",
+  "type": "hyperframes:block",
+  "title": "My Block",
+  "description": "What this block does in one sentence",
+  "tags": ["category", "subcategory"],
+  "dimensions": { "width": 1920, "height": 1080 },
+  "duration": 5,
+  "files": [
+    {
+      "path": "my-block.html",
+      "target": "compositions/my-block.html",
+      "type": "hyperframes:composition"
+    }
+  ]
+}
+```
+
+## The Rules
+
+Five things that must be true for every registry item:
+
+<Steps>
+  <Step title="Deterministic">
+    No `Math.random()`, no `Date.now()`. Use seeded PRNG only.
+  </Step>
+  <Step title="Paused timeline">
+    `gsap.timeline({ paused: true })`. The player controls playback.
+  </Step>
+  <Step title="Register timeline">
+    `window.__timelines["id"]` must match `data-composition-id`.
+  </Step>
+  <Step title="No requestAnimationFrame">
+    Use `tl.eventCallback("onUpdate", render)` for Three.js/WebGL scenes.
+  </Step>
+  <Step title="Hard kills on captions">
+    `tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)` — no lingering text.
+  </Step>
+</Steps>
+
+<Warning>
+Break any of these and renders won't be reproducible. The renderer captures every frame by seeking the timeline — if your animation depends on real time or random state, it breaks.
+</Warning>
+
+## Quality Bar
+
+Not everything belongs in the registry. The bar is production quality.
+
+| Type | Minimum standard |
+|------|-----------------|
+| Captions | 96px+ font, text-stroke/shadow, overflow prevention |
+| VFX | Solves a problem that takes 4+ hours from scratch |
+| Transitions | Smoother than CSS — if opacity 0→1 works, it's not a transition |
+| Blocks | Would a professional use this in a client project? |
+
+### Common rejection reasons
+
+1. **"Looks like a demo"** — a spinning cube is not a component
+2. **"Text unreadable"** — font too small, no contrast treatment
+3. **"Non-deterministic"** — `Math.random()` or `Date.now()`
+4. **"Timeline not found"** — ID mismatch between HTML and JS
+5. **"Breaks as sub-composition"** — element IDs collide (prefix everything)
+
+## Workflow
+
+<Steps>
+  <Step title="Fork and create">
+    Fork [heygen-com/hyperframes](https://github.com/heygen-com/hyperframes) and create your block directory:
+    ```bash
+    mkdir -p registry/blocks/your-block
+    ```
+  </Step>
+  <Step title="Write your block">
+    Create the HTML composition and `registry-item.json`. Use the templates above.
+  </Step>
+  <Step title="Validate">
+    ```bash
+    hyperframes lint
+    hyperframes validate
+    npx oxfmt your-block.html
+    ```
+  </Step>
+  <Step title="Update registry">
+    ```bash
+    # Add to registry index
+    # Update registry/registry.json
+    npx tsx scripts/generate-catalog-pages.ts
+    ```
+  </Step>
+  <Step title="Render preview">
+    ```bash
+    hyperframes render -o preview.mp4
+    ```
+  </Step>
+  <Step title="Publish and PR">
+    ```bash
+    npx hyperframes publish
+    ```
+    Open a PR with your [hyperframes.dev](https://hyperframes.dev) preview link.
+  </Step>
+</Steps>
+
+**External contributors:** attach the preview MP4 to your PR. A maintainer handles the catalog image.
+
+**HeyGen internal:** run `scripts/upload-docs-images.sh` to push catalog PNGs.
+
+## What's Needed Right Now
+
+These are gaps in the registry. If you're looking for something to build, start here.
+
+| Category | Gap | Difficulty |
+|----------|-----|-----------|
+| Captions | Karaoke with clip-path sweep (CapCut style) | Medium |
+| Captions | RTL language layouts (Arabic, Hebrew) | Medium |
+| Lower thirds | 10 variations for podcasts/interviews | Easy |
+| Lower thirds | News ticker / scrolling text bar | Easy |
+| Maps | Animated route maps, region highlights, location pins | Medium |
+| VFX | Product turntable with HDRI | Hard |
+| VFX | Particle system with physics (collisions, gravity) | Hard |
+| Transitions | Morphing shape transitions | Hard |
+| Data viz | Sankey / flow diagrams | Medium |

docs/docs.json

@@ -219,6 +219,7 @@
             "group": "Contributing",
             "pages": [
               "contributing",
+              "contributing/catalog",
               "contributing/release-channels",
               "contributing/testing-local-changes"
             ]