mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
James Russo
4bde66f532
## 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
46 lines
1.5 KiB
Markdown
46 lines
1.5 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"$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/`:
|
|
|
|
```json
|
|
{
|
|
"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.
|