mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-01 19:42:03 +00:00

Files

T

James Russo 4bde66f532 feat(skills): hyperframes-registry skill (#261 )

## What

New skill `hyperframes-registry` that teaches AI coding agents how to install and wire registry blocks and components into HyperFrames compositions.

### Skill structure
```
skills/hyperframes-registry/
  SKILL.md                          — triggers, overview, quick reference
  references/
    install-locations.md            — default paths, hyperframes.json config
    wiring-blocks.md                — iframe inclusion, data attributes, positioning
    wiring-components.md            — snippet merging (HTML, CSS, JS, timeline)
    discovery.md                    — manifest reading, item fields, available items table
    demo-html-pattern.md            — why components ship demo.html, structure conventions
  examples/
    add-block.md                    — worked example: data-chart block install + wiring
    add-component.md                — worked example: shimmer-sweep component install + wiring
```

## Why

Phase B of the catalog plan (PR 10). Without this skill, agents using `hyperframes add` have to guess how to wire installed items into compositions. The skill encodes the iframe/snippet patterns so agents get it right on the first attempt.

## How

- SKILL.md frontmatter triggers on: `hyperframes add`, "block", "component", `hyperframes.json`
- References cover every step: discovery, install, wiring blocks (iframe), wiring components (snippet merge), and the demo.html convention
- Two worked examples walk through complete install-to-preview workflows
- Updated CLAUDE.md skills table + trigger rules, README.md skills table, docs/packages/cli.mdx

## Test plan

- [x] `scripts/lint-skills.ts` passes (checked 4 skill files, no issues)
- [x] `oxfmt --check` passes on all markdown files
- [x] SKILL.md frontmatter has valid `name` and `description`
- [x] All reference links in SKILL.md resolve to existing files
- [x] CLAUDE.md, README.md, and docs CLI page updated with new skill

2026-04-14 16:27:24 -07:00

1.5 KiB

Raw Permalink Blame History

Install Locations

Default paths

Item type	Default install path	Configured by
Block	`compositions/<name>.html`	`hyperframes.json#paths.blocks`
Component	`compositions/components/<name>.html`	`hyperframes.json#paths.components`

How path remapping works

The target field in each item's registry-item.json specifies a default install path. The add command remaps the prefix based on hyperframes.json#paths:

Block targets starting with compositions/ get remapped to <paths.blocks>/
Component targets starting with compositions/components/ get remapped to <paths.components>/

hyperframes.json

Created automatically by hyperframes init. If it doesn't exist when you run add, the CLI creates it with defaults:

{
  "$schema": "https://hyperframes.heygen.com/schema/hyperframes.json",
  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
  "paths": {
    "blocks": "compositions",
    "components": "compositions/components",
    "assets": "assets"
  }
}

Custom layouts

To install blocks into a scenes/ directory instead of compositions/:

{
  "paths": {
    "blocks": "scenes"
  }
}

Then hyperframes add data-chart writes to scenes/data-chart.html instead of compositions/data-chart.html. The snippet output reflects the remapped path.

1.5 KiB Raw Permalink Blame History