Skip to main content
skill CX Codex

contribute-catalog — Claude Code skill: what it does, how to install

The contribute-catalog skill guides a new HyperFrames block or component from an idea to an upstream catalog PR. Use it for captions, VFX, transitions, and lower thirds.

Apache-2.0 211 installs ★ 484 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add boraoztunc/skills --skill contribute-catalog -a claude-code
Open on GitHub

What contribute-catalog does

contribute-catalog takes a HyperFrames catalog contribution from planning to pull request. It separates standalone blocks in registry/blocks/ from reusable components in registry/components/, then guides the required files and registry-item.json entry.

The workflow covers implementation, checks, and previews with hyperframes lint, hyperframes validate, hyperframes render, hyperframes snapshot, and npx hyperframes publish. It also walks through branching, HTML formatting, catalog updates, committing, and opening the PR. A GitHub account is required to open that PR.

What it helps with

  • create a HyperFrames caption or lower-third block
  • build a reusable text-effect or overlay component
  • check a catalog item before publishing
  • generate a preview for a new registry entry
  • send a contribution to the upstream repository

Example prompts for the agent

  • Create a new HyperFrames lower-third block and prepare it for an upstream catalog PR.
  • Build a reusable text-effect component, run hyperframes lint, and generate a preview.
  • Guide me from a new transition idea to a pull request in the HyperFrames repository.

How to install contribute-catalog

1Skills CLI (Vercel)

npx skills add boraoztunc/skills --skill contribute-catalog -a claude-code

2Manually: put the files in place

~/.claude/skills/contribute-catalog/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/contribute-catalog/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about contribute-catalog

How do I install contribute-catalog in Claude Code?

Run npx skills add boraoztunc/skills --skill contribute-catalog -a claude-code. The skill file will be at ~/.claude/skills/contribute-catalog/SKILL.md.

What does contribute-catalog do?

It guides the creation of a HyperFrames block or component, validation, preview publishing, and an upstream pull request for the public catalog.

How is a HyperFrames block different from a component?

A block is a standalone composition with fixed dimensions and duration. A component is a reusable snippet without fixed dimensions or duration.

Source text

SKILL.md · Apache-2.0
---
name: contribute-catalog
description: Author a new HyperFrames registry block (caption style, VFX block, transition, lower third) or component (text effect, overlay, snippet) and ship it as an upstream PR to the hyperframes repo. Use ONLY when the user wants to CONTRIBUTE to the public catalog — for in-project caption/transition authoring use the `hyperframes` skill, for installing existing registry items use the `hyperframes-registry` skill.
---

# Contribute to HyperFrames Registry

Guide the user from idea to merged PR for a new registry block or component.

## Workflow

```
1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship
```

### Step 1: Clarify

Ask what they're building. The registry has two item types:

- **Block** (`registry/blocks/`, type `hyperframes:block`) — a full standalone composition with fixed dimensions and duration. Caption styles, VFX effects, title cards, lower thirds.
- **Component** (`registry/components/`, type `hyperframes:component`) — a reusable snippet with no fixed dimensions or duration. CSS effects, text treatments, overlays that adapt to any composition size.

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 structure:

**For blocks:**

```
registry/blocks/{block-name}/
  {block-name}.html
  registry-item.json
```

**For components:**

```
registry/components/{component-name}/
  {component-name}.html
  registry-item.json
```

**Naming convention:**

| Item name        | ID prefix | 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. ALL element IDs must use this prefix to avoid collisions in sub-compositions.

**registry-item.json for blocks:**

```json
{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "{block-name}",
  "type": "hyperframes:block",
  "title": "{Human Title}",
  "description": "{one sentence}",
  "dimensions": { "width": 1920, "height": 1080 }, // adjust: 1080x1920 for portrait/social
  "duration": 10, // adjust for your composition
  "tags": ["{category}", "{subcategory}"],
  "files": [
    {
      "path": "{block-name}.html",
      "target": "compositions/{block-name}.html",
      "type": "hyperframes:composition"
    }
  ]
}
```

**registry-item.json for components** (no `dimensions` or `duration`):

```json
{
  "$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
  "name": "{component-name}",
  "type": "hyperframes:component",
  "title": "{Human Title}",
  "description": "{one sentence}",
  "tags": ["{category}"],
  "files": [
    {
      "path": "{component-name}.html",
      "target": "compositions/components/{component-name}.html",
      "type": "hyperframes:snippet"
    }
  ]
}
```

### Step 3: Build

Apply the correct template based on type. See [templates.md](templates.md) for copy-paste starters.

#### Caption blocks

**Non-negotiable caption rules:**

- Font: **96px minimum** for proportional fonts. **64-72px acceptable for monospace** (wider characters need less size).
- 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):

- Wrap each character in `<span>` with ID `{prefix}-ch-{group}-{char}`
- Stagger via `tl.set` at computed intervals from word timestamps
- Cursors/decorative elements: use `tl.set` at intervals — NOT CSS animation (not seekable)

**Positioning variants:**

- Centered: `display: flex; align-items: center; justify-content: center;`
- Lower-third: `position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center;`
- Left-aligned: `position: absolute; bottom: 100px; left: 120px; text-align: left;`

#### VFX blocks (Three.js)

- Use `[email protected]` from CDN (global script)
- `tl.eventCallback("onUpdate", renderScene); renderScene();` — NO requestAnimationFrame
- State proxy pattern: GSAP animates plain JS object, render function reads it
- Seeded PRNG (`mulberry32`) for randomness

#### All types

- `data-composition-id` MUST match `window.__timelines["id"]`
- All element IDs prefixed with block abbreviation
- `gsap.timeline({ paused: true })` — always paused
- No `Math.random()`, no `Date.now()`

### Step 4: Validate

```bash
hyperframes lint                    # 0 errors required
hyperframes validate --no-contrast  # 0 console errors required
```

### Step 5: Preview

```bash
# Render preview video
hyperframes render -o preview.mp4

# Snapshot for visual QA
hyperframes snapshot --at "1.0,3.0,5.0,7.0"

# Publish to hyperframes.dev for review
npx hyperframes publish
```

**Catalog preview image** — The catalog card uses a PNG at `docs/images/catalog/{kind}/{name}.png` (where `{kind}` is `blocks` or `components`). Generate it from a snapshot, then:

- **HeyGen internal contributors:** run `scripts/upload-docs-images.sh` (requires AWS profile `engineering-767398024897`)
- **External contributors:** attach the preview MP4 to your PR description. A maintainer will generate and upload the catalog image before merging.

### Step 6: Ship

**All steps are required. Missing any one produces a broken catalog entry.**

`{kind}` is `blocks` or `components` depending on what you built in Step 1.

```bash
# 1. Create branch
git checkout -b feat/registry-{name}

# 2. Format HTML
npx oxfmt registry/{kind}/{name}/*.html

# 3. Update registry/registry.json — add entry to the "items" array:
#    { "name": "{name}", "type": "hyperframes:block" }  (or "hyperframes:component")

# 4. Generate catalog docs page
npx tsx scripts/generate-catalog-pages.ts

# 5. Publish to hyperframes.dev so reviewers can preview
npx hyperframes publish

# 6. Stage everything
git add registry/{kind}/{name}/ registry/registry.json docs/catalog/

# 7. Commit
git commit -m "feat(registry): add {name} — {one sentence}"

# 8. Push and open PR with hyperframes.dev link
git push origin feat/registry-{name}
gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"
```

**If you don't have a GitHub account:** you need one to open a PR. Sign up at https://github.com/signup, then run `gh auth login`.

## Quality Gate

- [ ] `hyperframes lint` → 0 errors
- [ ] `hyperframes validate` → 0 console errors
- [ ] `npx oxfmt --check` passes
- [ ] `registry/registry.json` updated with new entry
- [ ] `scripts/generate-catalog-pages.ts` run (docs page generated)
- [ ] `npx hyperframes publish` run (claim your project URL)
- [ ] Preview MP4 attached to PR (external) or catalog PNG uploaded (internal)
- [ ] All IDs unique and prefixed

© boraoztunc · Apache-2.0 · boraoztunc/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set22

The whole set →
tailwind A skill for Tailwind CSS v4.2 in HyperFrames compositions, with rules for stable browser rendering and v3-to-v4 fixes. CX Codex +1 218installs hyperframes-cli hyperframes-cli controls the HyperFrames video pipeline through npx hyperframes, covering scaffolding, layout verification, studio preview, and final rendering. CX Codex +1 216installs lottie Teaches the agent to embed Lottie and dotLottie animations in HyperFrames so the composition timeline can be seeked to any frame. CX Codex +1 212installs waapi waapi instructs agents to write deterministic Web Animations API code for HyperFrames without relying on heavy external animation engines. CX Codex +1 211installs three Keeps a Three.js scene in HyperFrames tied to composition time: the adapter fires hf-seek and the scene draws the frame requested. CX Codex +1 209installs typegpu Skill for building GPU compositions with TypeGPU and WebGPU in HyperFrames: WGSL fragment shaders, compute pipelines, liquid glass effects, and particles on canvas. CX Codex +1 207installs linear-local-first-architecture linear-local-first-architecture tells the agent how to build a web app that answers instantly: workspace in IndexedDB, edits applied locally, sync queued in the background. CX Codex +1 201installs conductor-rewrite-performance conductor-rewrite-performance optimizes React performance in local-first Tauri desktop apps. Stops cascading re-renders on route changes and cleans up sluggish streaming lists. CX Codex +1 186installs

Project sponsors

Companies that keep this analytics open