Skip to content

Commit d61a895

Browse files
docs: reconcile skills surface; rename read-first entry skill to /hyperframes (#1428)
Make /hyperframes the single entry skill and bring the docs back in sync with the #1349 skills refactor. Skills: - Rename hyperframes-read-first -> hyperframes so the leaderboard-tracked /hyperframes is the entry/router skill; description leads with "READ THIS FIRST" to preserve the read-first intent. Update all references across CLAUDE.md, AGENTS.md, CLI templates, test script, and workflow SKILLs. Docs (closes the quickstart confusion in #1428): - quickstart + prompting: replace the dead standalone runtime slash commands (/gsap /lottie /three /waapi /animejs /css-animations /tailwind) with the real surface; document the picker as required core skills (8) vs optional workflows, with --all as the install-everything shortcut. - frame-adapters: map every runtime to /hyperframes-animation. - packages/cli: /tailwind -> /hyperframes-core; rewrite the skills-include blurb around the current domain skills. - copilot-cli/pipeline/migrating-to-lambda: /hyperframes is the router; the composition contract lives in /hyperframes-core. Fix a dead /gsap example. - antigravity: stop listing gsap/ and tailwind/ as separate skill dirs. - contributing/catalog: /contribute-catalog -> /hyperframes-registry. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 1e54827 commit d61a895

24 files changed

Lines changed: 111 additions & 72 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ This repo ships AI agent skills via [vercel-labs/skills](https://github.com/verc
1010
npx skills add heygen-com/hyperframes
1111
```
1212

13-
**Video-creation workflows** route through one entry skill — `/hyperframes-read-first` orients you to the whole surface and maps "make me a video" intent to a concrete workflow. Consult it before invoking a specific workflow:
13+
**Video-creation workflows** route through one entry skill — read `/hyperframes` first: it orients you to the whole surface and maps "make me a video" intent to a concrete workflow. Consult it before invoking a specific workflow:
1414

1515
- `/product-launch-video` — a **product** URL (or a pre-written script / text brief in no-capture mode) → product launch / promo video, up to ~3 min (sweet spot ~30-90s).
1616
- `/website-to-video` — a **general** website / URL → a video _of_ the site (tour / showcase / social clip from captured screenshots + assets); for a product **launch / promo**, use `/product-launch-video`.

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ This repo ships AI agent skills via [vercel-labs/skills](https://github.com/verc
1010
npx skills add heygen-com/hyperframes
1111
```
1212

13-
**Video-creation workflows** route through one entry skill — `/hyperframes-read-first` orients you to the whole surface and maps "make me a video" intent to a concrete workflow. Consult it before invoking a specific workflow:
13+
**Video-creation workflows** route through one entry skill — read `/hyperframes` first: it orients you to the whole surface and maps "make me a video" intent to a concrete workflow. Consult it before invoking a specific workflow:
1414

1515
- `/product-launch-video` — a **product** URL (or a pre-written script / text brief in no-capture mode) → product launch / promo video, up to ~3 min (sweet spot ~30-90s).
1616
- `/website-to-video` — a **general** website / URL → a video _of_ the site (tour / showcase / social clip from captured screenshots + assets); for a product **launch / promo**, use `/product-launch-video`.

‎docs/concepts/frame-adapters.mdx‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -106,14 +106,16 @@ These rules are non-negotiable for any adapter. They are the foundation of Hyper
106106

107107
First-party runtime adapters:
108108

109+
All runtime adapters live in the `/hyperframes-animation` skill — invoke it for the runtime-specific seek API as well as motion rules, scene blueprints, and transitions.
110+
109111
| Runtime | Seek Method | Skill |
110112
|---------|-------------|-------|
111-
| [GSAP](/guides/gsap-animation) | `timeline.totalTime(timeSeconds)` or `timeline.seek(timeSeconds)` | `/gsap` |
112-
| Anime.js | `instance.seek(timeMs)` for animations registered on `window.__hfAnime` | `/animejs` |
113-
| CSS keyframes | Browser `Animation.currentTime`, with paused negative-delay fallback | `/css-animations` |
114-
| Lottie / dotLottie | `goToAndStop(timeMs, false)`, raw-frame setters, or player seek APIs | `/lottie` |
115-
| Three.js / WebGL | `hf-seek` events plus `window.__hfThreeTime` for deterministic scene rendering | `/three` |
116-
| Web Animations API | `document.getAnimations()` and `animation.currentTime` | `/waapi` |
113+
| [GSAP](/guides/gsap-animation) | `timeline.totalTime(timeSeconds)` or `timeline.seek(timeSeconds)` | `/hyperframes-animation` |
114+
| Anime.js | `instance.seek(timeMs)` for animations registered on `window.__hfAnime` | `/hyperframes-animation` |
115+
| CSS keyframes | Browser `Animation.currentTime`, with paused negative-delay fallback | `/hyperframes-animation` |
116+
| Lottie / dotLottie | `goToAndStop(timeMs, false)`, raw-frame setters, or player seek APIs | `/hyperframes-animation` |
117+
| Three.js / WebGL | `hf-seek` events plus `window.__hfThreeTime` for deterministic scene rendering | `/hyperframes-animation` |
118+
| Web Animations API | `document.getAnimations()` and `animation.currentTime` | `/hyperframes-animation` |
117119

118120
Community adapters are welcome -- if it can seek by frame, it belongs in Hyperframes.
119121

‎docs/contributing/catalog.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ If you use Claude Code with HyperFrames skills:
4343

4444
> "I want to contribute a new transition that looks like \[description\]"
4545
46-
The `/contribute-catalog` skill scaffolds the structure, validates, renders a preview, publishes to [hyperframes.dev](https://hyperframes.dev), and prepares the PR.
46+
The `/hyperframes-registry` skill scaffolds the structure, validates, renders a preview, publishes to [hyperframes.dev](https://hyperframes.dev), and prepares the PR.
4747

4848
## What Goes in the Registry
4949

‎docs/deploy/migrating-to-hyperframes-lambda.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ The default policy doc emitted by `hyperframes lambda policies user/role` uses `
8888
## Migration checklist
8989

9090
1. **Inventory** the compositions you want to migrate. Filter out anything that needs HDR — that stays on your current framework for now. webm renders distributed via closed-GOP VP9 + concat-copy (see the webm section above).
91-
2. **Translate** each composition to plain HTML. The `[Concepts](/concepts)` page covers the data-attribute conventions; the `/hyperframes` skill (`npx skills add heygen-com/hyperframes`) makes Claude / Cursor / Codex aware of them too.
91+
2. **Translate** each composition to plain HTML. The `[Concepts](/concepts)` page covers the data-attribute conventions; installing the skills (`npx skills add heygen-com/hyperframes`) makes Claude / Cursor / Codex aware of them too — start at `/hyperframes`, which routes to `/hyperframes-core` for the composition contract.
9292
3. **Wire** the new composition into your build pipeline alongside the old one. HyperFrames doesn't need an external bundler — you can `npx hyperframes preview` against the HTML directly.
9393
4. **Deploy** in a separate AWS account or with a `--stack-name=hyperframes-staging` first. Run a real render with `--wait`; verify the output bytes.
9494
5. **Add the policy** to your CI. `hyperframes lambda policies user > infra/iam/hyperframes.json` then `hyperframes lambda policies validate infra/iam/hyperframes.json` on every PR.

‎docs/guides/antigravity.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,17 +31,17 @@ Verify the skills are installed:
3131
ls .agents/skills/
3232
```
3333

34-
You should see directories like `hyperframes/`, `hyperframes-cli/`, `gsap/`, `tailwind/`, and others — each containing a `SKILL.md` that the agent reads on demand.
34+
You should see directories like `hyperframes/` (the entry skill), `hyperframes-core/`, `hyperframes-animation/`, `hyperframes-cli/`, and others — each containing a `SKILL.md` that the agent reads on demand.
3535

3636
## How skills work in Antigravity
3737

3838
Antigravity uses **semantic matching** — when you type a prompt, the agent compares it against the `description` field of every available skill and loads the ones that are relevant. You don't need to invoke skills with a slash command (though you can reference them by name for precision).
3939

4040
| You say | Agent loads |
4141
|---|---|
42-
| "Create a 10-second product intro with captions" | `hyperframes`, `hyperframes-cli` |
43-
| "Add a GSAP scale-pop to the title" | `gsap` |
44-
| "Use Tailwind for styling" | `tailwind` |
42+
| "Create a 10-second product intro with captions" | `hyperframes`, `hyperframes-core` |
43+
| "Add a GSAP scale-pop to the title" | `hyperframes-animation` |
44+
| "Use Tailwind for styling" | `hyperframes-core` |
4545
| "Transcribe this audio and add captions" | `hyperframes-media` |
4646
| "Add a shimmer sweep transition" | `hyperframes-registry` |
4747

‎docs/guides/copilot-cli.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Prefix a skill name with `/` to load it explicitly:
4646
```
4747

4848
```
49-
/gsap Add a scale-pop animation to the title element.
49+
/hyperframes-animation Add a scale-pop animation to the title element.
5050
```
5151

5252
```
@@ -166,7 +166,7 @@ Authorize via OAuth when prompted. See the [MCP guide](/guides/mcp) for full det
166166

167167
## Tips
168168

169-
- **Always start with `/hyperframes` for composition work.** This loads the full skill context — composition rules, data attributes, GSAP patterns, caption formats — that generic web knowledge doesn't cover.
169+
- **Always start with `/hyperframes`.** It's the entry skill — it orients you to the whole surface and routes your request to the right workflow, pulling in the domain skills (`/hyperframes-core` for composition rules and data attributes, `/hyperframes-animation` for GSAP and other runtime patterns) that generic web knowledge doesn't cover.
170170
- **Use `/skills` to check skill status.** If output looks wrong, open the skills picker to verify the HyperFrames skills are enabled.
171171
- **Run `npx hyperframes lint` before rendering.** The linter catches structural issues the agent might miss on complex multi-scene edits.
172172
- **Keep the preview server running in a separate terminal.** You see every edit reflected in real time while prompting in Copilot CLI.

‎docs/guides/pipeline.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -154,7 +154,7 @@ This is where the storyboard becomes runnable HTML. Each composition is a self-c
154154

155155
For multi-beat videos, spawn a focused sub-agent per beat. Each one gets fresh context, the storyboard section for its beat, the asset paths it needs, and the relevant technique references. That produces noticeably better output than building every beat in one long-running context.
156156

157-
After each composition is built, run a self-review for layout, asset placement, and animation quality. The [`/hyperframes`](/guides/prompting) skill encodes the composition rules: required `class="clip"` attributes, GSAP timeline registration, `data-*` attribute semantics, and adapter registries.
157+
After each composition is built, run a self-review for layout, asset placement, and animation quality. The [`/hyperframes-core`](/guides/prompting) skill encodes the composition rules — required `class="clip"` attributes, `data-*` attribute semantics — and [`/hyperframes-animation`](/guides/prompting) covers GSAP timeline registration and adapter registries.
158158

159159
**Gate:** Every composition is self-reviewed. No overlapping elements, no misplaced assets, no static images sitting unanimated.
160160

‎docs/guides/prompting.mdx‎

Lines changed: 28 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -13,19 +13,36 @@ Install the skills in your project (or globally for your agent):
1313
npx skills add heygen-com/hyperframes
1414
```
1515

16-
In Claude Code, restart the session after installing. Skills register as **slash commands**:
17-
18-
| Slash command | What it loads |
19-
| -------------------------- | -------------------------------------------------------------------------- |
20-
| `/hyperframes` | Composition authoring — HTML structure, timing, captions, TTS, transitions |
21-
| `/hyperframes-cli` | Dev-loop CLI — `init`, `lint`, `inspect`, `preview`, `render`, `doctor` |
22-
| `/hyperframes-media` | Asset preprocessing — `tts`, `transcribe`, `remove-background` |
23-
| `/hyperframes-registry` | Block and component installation via `hyperframes add` |
24-
| `/website-to-video` | Capture a URL and turn it into a video; runs the full [Hyperframes pipeline](/guides/pipeline) |
25-
| `/gsap` | GSAP animation API — timelines, easing, ScrollTrigger, plugins |
16+
The installer shows a picker. Select the **core skills** below — every project needs them. In Claude Code, restart the session after installing; the skills register as **slash commands**. Start at `/hyperframes`: it orients you to the whole surface and routes "make me a video" requests to the right workflow.
17+
18+
**Core skills — install all of these**
19+
20+
| Slash command | What it loads |
21+
| ----------------------- | -------------------------------------------------------------------------- |
22+
| `/hyperframes` | **Read first.** The entry skill — capability map + video router; sends "make me a video" intent to the right workflow |
23+
| `/hyperframes-core` | Composition contract — HTML structure, `data-*` attributes, clips, tracks |
24+
| `/hyperframes-animation`| All animation — motion rules, scene blueprints, transitions, and the runtime adapters (GSAP, Lottie, Three.js, Anime.js, CSS, WAAPI, TypeGPU) |
25+
| `/hyperframes-creative` | Creative direction — design spec, palettes, typography, narration, beats |
26+
| `/hyperframes-cli` | Dev-loop CLI — `init`, `lint`, `inspect`, `preview`, `render`, `doctor` |
27+
| `/hyperframes-media` | Asset preprocessing — `tts`, `transcribe`, `remove-background` |
28+
| `/hyperframes-registry` | Block and component installation via `hyperframes add` |
29+
| `/general-video` | The general authoring workflow — fallback for any video that doesn't match a specific workflow below |
30+
31+
**Optional workflows — add the ones that match your inputs** (`/hyperframes` routes to whichever you've installed)
32+
33+
| Slash command | Input → output |
34+
| ------------------------ | --------------------------------------------------------------------------- |
35+
| `/product-launch-video` | A product URL / brief / script → launch or promo video |
36+
| `/website-to-video` | A general website / URL → a video of the site (tour / showcase / social clip) |
37+
| `/faceless-explainer` | Arbitrary text (no URL) → faceless explainer with its own TTS narration |
38+
| `/pr-to-video` | A GitHub PR → code-change explainer |
39+
| `/embedded-captions` | An existing talking-head video → the same footage with captions / subtitles |
40+
| `/graphic-overlays` | An existing talking-head video → footage packaged with designed graphic cards |
41+
| `/motion-graphics` | A short, unnarrated, design-led motion graphic (logo sting, kinetic type, stat / chart) |
42+
| `/remotion-to-hyperframes` | Port an existing Remotion (React) composition to HyperFrames HTML |
2643

2744
<Tip>
28-
Always prefix Hyperframes prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents). This loads the skill context explicitly so the agent gets composition rules right the first time, instead of relying on whatever it remembers about web video.
45+
To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all`. And start Hyperframes prompts with `/hyperframes` (or invoke the skill another way for non-Claude agents) — it loads the routing + composition context explicitly so the agent picks the right workflow and gets the rules right the first time.
2946
</Tip>
3047

3148
## Claude Design

‎docs/packages/cli.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -184,7 +184,7 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
184184

185185
In non-interactive mode, `--example` is required — the CLI errors with a usage example if missing. In interactive mode (default on TTY), you choose the example interactively. Pass `--non-interactive` to require `--example` via flag. When `--video` or `--audio` is provided, the CLI automatically transcribes the audio with Whisper and patches captions into the composition (use `--skip-transcribe` to disable).
186186

187-
`--tailwind` injects the pinned Tailwind v4 browser runtime into scaffolded HTML and exposes a `window.__tailwindReady` promise that renders wait on before capturing frame 0. Use the `/tailwind` skill when editing these projects so agents follow v4 CSS-first patterns instead of v3 `tailwind.config.js` and `@tailwind` directive patterns. The browser runtime is still intended for scaffolded projects and quick iteration; for fully offline or locked-down production renders, compile Tailwind to CSS and include the stylesheet directly.
187+
`--tailwind` injects the pinned Tailwind v4 browser runtime into scaffolded HTML and exposes a `window.__tailwindReady` promise that renders wait on before capturing frame 0. Use the `/hyperframes-core` skill when editing these projects so agents follow v4 CSS-first patterns instead of v3 `tailwind.config.js` and `@tailwind` directive patterns. The browser runtime is still intended for scaffolded projects and quick iteration; for fully offline or locked-down production renders, compile Tailwind to CSS and include the stylesheet directly.
188188

189189
After scaffolding, the CLI installs AI coding skills for Claude Code, Gemini CLI, and Codex CLI (use `--skip-skills` to disable). See [`skills`](#skills) command.
190190

@@ -888,7 +888,7 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
888888
| `--codex` | Install to Codex CLI (`~/.codex/skills/`) |
889889
| `--cursor` | Install to Cursor (`.cursor/skills/` in current project) |
890890

891-
Skills are fetched from GitHub and include composition authoring, Tailwind v4 browser-runtime guidance, GSAP animation patterns, Anime.js, CSS animation, Lottie, Three.js, and WAAPI adapter patterns, registry block/component wiring, and other domain-specific knowledge. The `init` command also offers to install skills automatically after scaffolding a project.
891+
Skills are fetched from GitHub: the `/hyperframes` entry skill (routes "make me a video" to a workflow), the composition contract and Tailwind v4 browser-runtime guidance (`/hyperframes-core`), all animation including the GSAP / Anime.js / CSS / Lottie / Three.js / WAAPI / TypeGPU runtime adapters (`/hyperframes-animation`), creative direction (`/hyperframes-creative`), media preprocessing (`/hyperframes-media`), registry block/component wiring (`/hyperframes-registry`), and the video workflows. The `init` command also offers to install skills automatically after scaffolding a project.
892892

893893
#### Troubleshooting: `fatal: active post-checkout hook found during git clone`
894894

0 commit comments

Comments
 (0)