HyperFrames — start here

HyperFrames renders video from HTML — a composition is an HTML file whose DOM declares timing with data-* attributes, whose animation runtime is seekable, and whose media playback is owned by the framework.

This skill is the technical how-to-use guide — it is intentionally non-design. For motion / animation recipes, see /hyperframes-motion. For design direction (palettes, typography, frame presets), see /hyperframes-design. Below: a capability map of every HyperFrames topic, a topic guide index for what's in this skill, and an intent router for picking a workflow.

Capability map — the HyperFrames skills

Three skills, one per concern. This one is the technical how-to-use guide. The other two cover design.

You want to…	Skill
How to use HyperFrames — composition contract, CLI dev loop, install registry blocks / components (this skill)	/hyperframes
Motion / animation — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js)	/hyperframes-motion
Design — palettes, typography, frame presets, beat planning, brand / style decisions (no animation recipes)	/hyperframes-design

---

Topic guide — what's inside this skill

The technical how-to-use guide is split into three sub-topics. Each has its own SKILL.md and references/:

Sub-topic	Path	Read it for
Composition core	core/SKILL.md	The composition contract — data-* attributes, clips, tracks, sub-compositions, variables, determinism rules
CLI dev loop	cli/SKILL.md	npx hyperframes init / lint / validate / inspect / preview / render + AWS Lambda cloud rendering
Registry add	registry/SKILL.md	hyperframes add <block-or-component> — install locations, wiring blocks, wiring components, contributing new items

Per-topic detail lives in each sub-topic's references/ folder. For animation runtime specifics (GSAP API, Lottie, Three.js, etc.) see /hyperframes-motion → adapters/<runtime>.md.

---

Intent routing — pick a workflow

This section knows only the top-level workflows; it does not load their internal references or the topic guides above.

Before routing — confirm the input, not the spec

Routing needs to know what the video is about — its input and subject. If that's unspecified ("make a video about our thing" with no URL, product, topic, or asset), ask before entering any workflow — committing to a workflow IS the routing decision. At most two questions:

• Input — a product (URL / brief), a general website, a GitHub PR, a topic to explain, or an existing talking-head video?

Spec defaults — state, don't ask (they never change the route): aspect 16:9 (use 9:16 only for a named vertical destination — TikTok / Reels / Shorts); caption language = the user's. The chosen workflow re-confirms its own specifics at its first step.

Workflow cheat-sheet

Workflow	Use it for
/faceless-explainer	Explaining a topic / concept from text — no product, no URL; every visual is LLM-invented
/pr-to-video	A GitHub PR / code change → changelog / feature-reveal / fix / refactor explainer
/embedded-captions	Adding captions / subtitles to an existing talking-head video (footage untouched)
/talking-head-recut	Packaging an existing talking-head video with designed graphic overlays — lower-thirds, data callouts, kinetic titles, pull-quotes
/motion-graphics	A short, design-led motion graphic — kinetic type, a stat / chart hit, a logo sting, a lower-third overlay
/slideshow	A presentation / pitch deck / interactive deck — discrete slides, fragments, branching, hotspots; output is a navigable deck, not a rendered video
/general-video	Anything else — longer or multi-scene pieces, a static loop / poster, a custom composition

Disambiguation (only where confusable):

• Motion-first (under ~10s, the motion is the message) → /motion-graphics, regardless of input.
• A URL or script — a GitHub PR link → /pr-to-video; explains a concept with no product / site → /faceless-explainer. Genuinely unclear input → ask one question.
• Existing footage — plain spoken-word subtitles → /embedded-captions; designed overlay cards → /talking-head-recut. Neither edits the footage itself (re-timing / recolor / reframe / reorder is NLE editing — out of scope).
• A presentation / pitch deck / interactive deck (discrete slides, navigation, presenter mode) → /slideshow — output is a navigable deck, not a rendered video. An explicit "slideshow" request proceeds directly; an adjacent trigger ("deck / slides / presentation / convert this page") makes /slideshow confirm it's a slideshow before authoring, and switch to the appropriate non-slideshow workflow if not.
• Length is a guide, not a gate — intent picks the workflow; go to /general-video only when the piece is clearly longer than ~3 min, or is a static / loop / custom format.

If the matched workflow isn't installed

Once you've picked a workflow, check it's actually available to you. If the matched workflow skill isn't installed, don't fall back to guessing — tell the user to install it first:

• Just this workflow: npx skills add heygen-com/hyperframes --skill <workflow-name> (e.g. --skill pr-to-video — bare name, no leading /).
• All workflows at once: npx skills add heygen-com/hyperframes --all (core + every workflow, skips the picker).

After they run it, re-read the workflow's skill and continue.

Workflow details

/faceless-explainer

• Input: Arbitrary text — a topic, article, or notes — being explained, with no product being marketed and no site to capture.
• Output: faceless explainer → MP4, every visual LLM-invented per scene (typography / abstract / diagram / data-viz); ships the pin-and-paper preset. (sweet spot 30–90s).
• Triggers: "faceless explainer about X", "explain how DNS works as a video", "turn this article into an explainer", "explainer from my notes".

/pr-to-video

• Input: A GitHub pull request — a PR URL, an owner/repo#N ref, or "this PR" — read via the gh CLI (not a site to scrape).
• Output: code-change explainer (changelog / feature-reveal / fix / refactor) → MP4 — diff highlights, before/after, file-tree + impact scenes. ≤ (sweet spot 30–90s).
• Triggers: "make a video about this PR", "turn PR #1187 into a changelog video", "release-notes video from github.com/org/repo/pull/123".

/embedded-captions

• Input: An existing talking-head video (MP4) to caption — actual footage, not a URL or brief. Transcribed locally (Whisper, no API key) and matted (RVM) so the subject can occlude captions.
• Output: the same footage untouched, with a caption layer — Standard (verbatim lower-third rail + an embedded climax behind the subject) or Cinematic (every caption composited behind the subject). Any length.
• Triggers: "add captions / subtitles to this video", "captions behind the subject", "cinematic captions for my clip".

/talking-head-recut

• Input: An existing talking-head / interview / podcast video (MP4) to package with on-screen graphics — actual footage. Transcribed locally (Whisper). The clip plays in full underneath, untouched.
• Output: the same footage with timed graphic-overlay cards — kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, picture-in-picture — synced to the transcript. Any length.
• Triggers: "package this video", "add graphic overlays / lower-thirds / data callouts to my talk", "turn this interview into a graphics-packaged edit".

/motion-graphics

• Input: A short, design-led motion graphic where the motion is the message — typically under ~10s. Genres: kinetic typography, a stat / number count-up, a chart hit, a logo sting, a lower-third / overlay, or a search-driven page / tweet / headline shot.
• Output: a short motion graphic → MP4 or a transparent overlay (alpha WebM / MOV) for a lower-third / callout.
• Triggers: "an 8s logo sting", "animate this stat", "a kinetic-type intro", "turn this tweet into a motion graphic", "a transparent lower-third overlay".

/slideshow

• Input: A presentation / pitch deck / interactive deck to author — a brief, an outline, or an existing page to convert to slides. Not a request for a rendered video; if the intent is ambiguous, the skill confirms "do you want this as a HyperFrames slideshow?" before authoring.
• Output: a runnable HyperFrames composition + a JSON island the player's SlideshowController reads to turn the GSAP timeline into a navigable deck — discrete slides, fragment reveals, branching sequences, hotspot navigation, presenter mode, and speaker notes. The deliverable is a deck, not an MP4.
• Triggers: "make a pitch deck / presentation / slide deck", "an interactive deck", "convert this page into slides", "a slideshow with presenter mode".

/general-video

• Input: Anything not above — a creative brief, a single element to animate, an edit to a composition you're building. Input- and length-agnostic.
• Output: a HyperFrames composition (any length / format) via the original flow: design system → prompt expansion → plan → layout-before-animation → build (delegating to the hyperframes-* skills) → validate.
• Triggers: "make a title card", "animate this", "a longer brand / sizzle reel", "a multi-scene composition", "a static loop / poster", any "make a video" that fits no row above.