feat(skills): hyperframes-registry skill - #261
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
87d4099 to
ceaf889
Compare
ceaf889 to
24012ed
Compare
24012ed to
7b0bcdc
Compare
7b0bcdc to
462bff8
Compare
462bff8 to
0f8e9d2
Compare
0f8e9d2 to
f711805
Compare
miguel-heygen
left a comment
miguel-heygen
left a comment
There was a problem hiding this comment.
Review: hyperframes-registry skill
Well-structured skill. The reference decomposition (install-locations, wiring-blocks, wiring-components, discovery, demo-html-pattern) covers the full workflow, and the worked examples walk through realistic end-to-end scenarios. Consistent with the existing hyperframes and hyperframes-cli skills in tone, depth, and SKILL.md frontmatter format. The catalog doc pages and preview generation improvements are a nice bonus.
Two issues to fix, one important suggestion, and some minor notes.
Must fix
1. Stale iframe references — the wiring mechanism is <div data-composition-src>, not <iframe>
This PR itself changes buildSnippet from <iframe src="..."> to <div data-composition-src="...">, and the wiring code examples throughout the skill are correct. But the prose still says iframe in three places:
- SKILL.md frontmatter
description: "...block iframe wiring, component snippet merging..." - SKILL.md body (line 2 of the bullet list): "Included via
<iframe>in a host composition." - CLAUDE.md skills table: "...block iframe wiring, component snippet merging, discovery."
- CLAUDE.md rules section: "...block iframes, component snippets..."
An agent reading the description and intro will think blocks use iframes, then see <div data-composition-src> in the examples and be confused about which is correct. The existing hyperframes skill already documents the <div data-composition-src> pattern — these references should say "sub-composition div" or "data-composition-src" instead of "iframe."
2. SKILL.md "snippet is a starting point" note is incomplete
The snippet is a starting point — you'll need to add
data-startanddata-track-indexattributes when wiring blocks.
The CLI's buildSnippet also omits data-composition-id, which the hyperframes skill's Composition Clips table marks as Required. The note should mention all three missing attributes: data-composition-id, data-start, and data-track-index. Without data-composition-id the runtime can't match the sub-composition's timeline registration.
Important
3. Consider mentioning data-composition-id must match the block's internal ID in the quick-reference section
The "Wiring blocks" section later explains this, but the quick-reference section is what agents hit first. A one-liner after the snippet note would save agents from wiring a block without the ID and getting a silent failure — e.g.:
The snippet is a starting point — you'll need to add
data-composition-id(must match the block's internal composition ID),data-start, anddata-track-indexattributes.
Minor notes (non-blocking)
-
discovery.md available items table: This is a static snapshot of 3 blocks and 3 components. If the registry grows, this table goes stale. Not a blocker for this PR, but worth a
<!-- keep in sync with registry.json -->comment or a note that agents should prefer readingregistry.jsondirectly for the authoritative list. -
wiring-blocks.md "Timeline coordination" section: Clear and helpful. The sentence "You do NOT need to reference the block's timeline in your host's GSAP code" is exactly the kind of thing agents get wrong without explicit guidance.
-
Catalog doc pages: The
<video>with poster fallback pattern is a good upgrade from the static<img>. The block usage snippets in the generated MDX now correctly show<div data-composition-src>with dimensions — consistent with the skill's wiring examples. -
generate-catalog-previews.ts wrapper: The
prepareProjectDirwrapper that generates anindex.htmlfor items that don't have one is a pragmatic solution. The fallback dimensions fromregistry-item.jsonare sensible. -
Registry component cleanups (grain-overlay, grid-pixelate-wipe, shimmer-sweep demo.html): Moving inline styles to CSS classes and replacing the external texture URL with an inline SVG data URI are both good — eliminates a network dependency during preview generation.
Overall this is solid work. Fix the iframe text, clarify the missing data-composition-id in the snippet note, and this is ready to merge.
PR #259: Scope all GSAP JS selectors in flowchart.html under [data-composition-id="flowchart"] prefix. Remove unnecessary setTimeout retry in data-chart.html. PR #261: Replace 'iframe' text with 'sub-composition' / 'data-composition-src' in SKILL.md description + body, CLAUDE.md skills table + rules. Add data-composition-id to missing-attributes note in snippet guidance. PR #262: Fix CI workflow — replace grep -P lookbehind with sed (PCRE variable-length alternation fails on Ubuntu), use fetch-depth: 0 + base SHA for diff, remove continue-on-error: true, add per-item timeout, reduce artifact retention to 7 days. Fix doc comment to remove stale 'examples' reference. PR #263: Add try/catch around JSON.parse in codegen discovery (prevents partial wipe on malformed manifest). Guard docs.json tabs array existence. PR #269: Fix Three.js CDN in ascii-dashboard (was broken relative path). Fix composition ID mismatches in 6 blocks (instagram-follow, tiktok-follow, x-post, reddit-post, spotify-card, app-showcase) — IDs now match block names.
miguel-heygen
left a comment
miguel-heygen
left a comment
There was a problem hiding this comment.
Skill structure is solid. Note: SKILL.md description and body still reference iframe wiring — should be updated to match the data-composition-src pattern in CLAUDE.md.
PR #259: Scope all GSAP JS selectors in flowchart.html under [data-composition-id="flowchart"] prefix. Remove unnecessary setTimeout retry in data-chart.html. PR #261: Replace 'iframe' text with 'sub-composition' / 'data-composition-src' in SKILL.md description + body, CLAUDE.md skills table + rules. Add data-composition-id to missing-attributes note in snippet guidance. PR #262: Fix CI workflow — replace grep -P lookbehind with sed (PCRE variable-length alternation fails on Ubuntu), use fetch-depth: 0 + base SHA for diff, remove continue-on-error: true, add per-item timeout, reduce artifact retention to 7 days. Fix doc comment to remove stale 'examples' reference. PR #263: Add try/catch around JSON.parse in codegen discovery (prevents partial wipe on malformed manifest). Guard docs.json tabs array existence. PR #269: Fix Three.js CDN in ascii-dashboard (was broken relative path). Fix composition ID mismatches in 6 blocks (instagram-follow, tiktok-follow, x-post, reddit-post, spotify-card, app-showcase) — IDs now match block names.
93ec271 to
c0bdaf7
Compare
f711805 to
630b5ab
Compare
Merge activity
|
Teaches AI coding agents how to use the registry end-to-end: - Install blocks/components via `hyperframes add` - Wire blocks as iframes with data-start/data-duration/data-track-index - Merge component snippets (HTML, CSS, JS, timeline) into host compositions - Discover available items via registry.json manifest - Understand the demo.html convention for component previews Includes worked examples for adding a block (data-chart) and a component (shimmer-sweep) with full wiring instructions. Updates CLAUDE.md skills table, README.md skills table, and docs CLI page.
630b5ab to
36a5a49
Compare
PR #259: Scope all GSAP JS selectors in flowchart.html under [data-composition-id="flowchart"] prefix. Remove unnecessary setTimeout retry in data-chart.html. PR #261: Replace 'iframe' text with 'sub-composition' / 'data-composition-src' in SKILL.md description + body, CLAUDE.md skills table + rules. Add data-composition-id to missing-attributes note in snippet guidance. PR #262: Fix CI workflow — replace grep -P lookbehind with sed (PCRE variable-length alternation fails on Ubuntu), use fetch-depth: 0 + base SHA for diff, remove continue-on-error: true, add per-item timeout, reduce artifact retention to 7 days. Fix doc comment to remove stale 'examples' reference. PR #263: Add try/catch around JSON.parse in codegen discovery (prevents partial wipe on malformed manifest). Guard docs.json tabs array existence. PR #269: Fix Three.js CDN in ascii-dashboard (was broken relative path). Fix composition ID mismatches in 6 blocks (instagram-follow, tiktok-follow, x-post, reddit-post, spotify-card, app-showcase) — IDs now match block names.
PR heygen-com#259: Scope all GSAP JS selectors in flowchart.html under [data-composition-id="flowchart"] prefix. Remove unnecessary setTimeout retry in data-chart.html. PR heygen-com#261: Replace 'iframe' text with 'sub-composition' / 'data-composition-src' in SKILL.md description + body, CLAUDE.md skills table + rules. Add data-composition-id to missing-attributes note in snippet guidance. PR heygen-com#262: Fix CI workflow — replace grep -P lookbehind with sed (PCRE variable-length alternation fails on Ubuntu), use fetch-depth: 0 + base SHA for diff, remove continue-on-error: true, add per-item timeout, reduce artifact retention to 7 days. Fix doc comment to remove stale 'examples' reference. PR heygen-com#263: Add try/catch around JSON.parse in codegen discovery (prevents partial wipe on malformed manifest). Guard docs.json tabs array existence. PR heygen-com#269: Fix Three.js CDN in ascii-dashboard (was broken relative path). Fix composition ID mismatches in 6 blocks (instagram-follow, tiktok-follow, x-post, reddit-post, spotify-card, app-showcase) — IDs now match block names.
## 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
This branch was successfully deployed
2 participants
What
New skill
hyperframes-registrythat teaches AI coding agents how to install and wire registry blocks and components into HyperFrames compositions.Skill structure
Why
Phase B of the catalog plan (PR 10). Without this skill, agents using
hyperframes addhave 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
hyperframes add, "block", "component",hyperframes.jsonTest plan
scripts/lint-skills.tspasses (checked 4 skill files, no issues)oxfmt --checkpasses on all markdown filesnameanddescription