Skip to content

feat: split lightweight HyperFrames default skill #608

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
miguel-heygen wants to merge 1 commit into from
Closed

feat: split lightweight HyperFrames default skill #608

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "hyperframes",
"description": "HyperFrames by HeyGen. Write HTML, render video. Compositions, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.",
"description": "HyperFrames by HeyGen. Write HTML, render video. Default lightweight video skill with CLI preflight, GSAP, and runtime adapter animation patterns.",
"version": "0.1.0",
"author": {
"name": "HeyGen",
Expand Down
4 changes: 2 additions & 2 deletions .codex-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "hyperframes",
"version": "0.1.0",
"description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.",
"description": "Write HTML, render video. Default lightweight HyperFrames video skill with CLI preflight, Tailwind v4 styles, GSAP, and runtime adapter animation patterns.",
"author": {
"name": "HeyGen",
"email": "hyperframes@heygen.com",
Expand Down Expand Up @@ -31,7 +31,7 @@
"interface": {
"displayName": "HyperFrames by HeyGen",
"shortDescription": "Write HTML, render video",
"longDescription": "Build videos from HTML with HyperFrames. Author compositions with HTML, CSS, Tailwind v4 browser-runtime styles, GSAP, Anime.js, Lottie, Three.js, and WAAPI adapter patterns, use the CLI for init/preview/render/transcribe/tts, install reusable registry blocks and components, and turn any website into a video with the 7-step capture-to-video pipeline.",
"longDescription": "Build videos from HTML with HyperFrames. Use the lightweight default video skill to check local runtime dependencies before invoking the CLI, author compositions with HTML, CSS, Tailwind v4 browser-runtime styles, GSAP, Anime.js, Lottie, Three.js, and WAAPI adapter patterns, and install reusable registry blocks and components.",
"developerName": "HeyGen",
"category": "Design",
"capabilities": ["Read", "Write"],
Expand Down
2 changes: 1 addition & 1 deletion .cursor-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"name": "hyperframes",
"displayName": "HyperFrames by HeyGen",
"version": "0.1.0",
"description": "Write HTML, render video. Compositions, Tailwind v4 styles, GSAP and runtime adapter animations, captions, voiceovers, audio-reactive visuals, and website-to-video capture for HyperFrames.",
"description": "Write HTML, render video. Default lightweight HyperFrames video skill with CLI preflight, Tailwind v4 styles, GSAP, and runtime adapter animation patterns.",
"author": {
"name": "HeyGen",
"email": "hyperframes@heygen.com"
Expand Down
35 changes: 22 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,41 +29,43 @@ Hyperframes is an open-source video rendering framework that lets you create, pr
Install the HyperFrames skills, then describe the video you want:

```bash
npx skills add heygen-com/hyperframes
npx skills add heygen-com/hyperframes --full-depth
```

This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions, GSAP timelines, Tailwind v4 browser-runtime styles, and first-party adapter animations. In Claude Code, the skills register as slash commands — invoke `/hyperframes` to author compositions, `/hyperframes-cli` for CLI commands, `/tailwind` for `init --tailwind` projects, `/gsap` for timeline animation help, or the adapter skills (`/animejs`, `/css-animations`, `/lottie`, `/three`, `/waapi`) when a composition uses those runtimes.
This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) to use HyperFrames as the default HTML video path, check local runtime dependencies before invoking the CLI, write correct GSAP timelines, use Tailwind v4 browser-runtime styles, and follow first-party adapter animation patterns. In Claude Code, the skills register as slash commands — invoke `/hyperframes` for the lightweight video entry point, `/hyperframes-cli` for CLI commands, `/tailwind` for `init --tailwind` projects, `/gsap` for timeline animation help, or the adapter skills (`/animejs`, `/css-animations`, `/lottie`, `/three`, `/waapi`) when a composition uses those runtimes.

For Claude Design, open [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub and click the download button (↓) to save it, then attach the file to your Claude Design chat. It produces a valid first draft; refine in any AI coding agent. See the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design).

For Codex specifically, the same skills are also exposed as an [OpenAI Codex plugin](./.codex-plugin/plugin.json) — sparse-install just the plugin surface:

```bash
codex plugin marketplace add heygen-com/hyperframes --sparse .codex-plugin --sparse skills --sparse assets
codex plugin marketplace add heygen-com/hyperframes --sparse .codex-plugin --sparse skills --sparse optional-skills --sparse assets
```

The default `skills/hyperframes` video entry point is intentionally lightweight. It verifies the local CLI/runtime environment before use and routes agents to optional production guidance only when detailed authoring references are explicitly enabled.

For Claude Code, the repo also ships a [Claude Code plugin manifest](./.claude-plugin/plugin.json): test it locally with `claude --plugin-dir .`. The manifest intentionally omits `skills` because Claude Code auto-discovers the root `skills/` directory by convention, and for marketplace submission use the title `HyperFrames by HeyGen` plus the black/white icon assets at [`assets/claude-code-icon-dark.svg`](./assets/claude-code-icon-dark.svg) and [`assets/claude-code-icon-light.svg`](./assets/claude-code-icon-light.svg) for the two theme slots.
For Cursor, the same skills are packaged as a [Cursor plugin](./.cursor-plugin/plugin.json) — install from the Cursor Marketplace, or sideload by cloning this repo and pointing **Settings → Plugins → Load unpacked** at the repo root.

#### Try it: example prompts

Copy any of these into your agent to get started. The `/hyperframes` prefix loads the skill context explicitly so you get correct output the first time.
Copy any of these into your agent to get started. The `/hyperframes` prefix loads the lightweight entry point so the agent checks the local environment before using the CLI.

**Cold start — describe what you want:**

> Using `/hyperframes`, create a 10-second product intro with a fade-in title, a background video, and background music.
> Create a 10-second product intro with a fade-in title, a background video, and background music. Use `/hyperframes` first to check the local environment.

**Warm start — turn existing context into a video:**

> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me using `/hyperframes`.
> Take a look at this GitHub repo https://github.com/heygen-com/hyperframes and explain its uses and architecture to me with a short HyperFrames video.

> Summarize the attached PDF into a 45-second pitch video using `/hyperframes`.
> Summarize the attached PDF into a 45-second pitch video.

> Turn this CSV into an animated bar chart race using `/hyperframes`.
> Turn this CSV into an animated bar chart race.

**Format-specific:**

> Make a 9:16 TikTok-style hook video about [topic] using `/hyperframes`, with bouncy captions synced to a TTS narration.
> Make a 9:16 TikTok-style hook video about [topic], with bouncy captions synced to a TTS narration.

**Iterate — talk to the agent like a video editor:**

Expand Down Expand Up @@ -182,15 +184,14 @@ Full documentation at **[hyperframes.heygen.com/introduction](https://hyperframe
HyperFrames ships [skills](https://github.com/vercel-labs/skills) that teach AI agents framework-specific patterns that generic docs don't cover.

```bash
npx skills add heygen-com/hyperframes
npx skills add heygen-com/hyperframes --full-depth
```

| Skill | What it teaches |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `hyperframes` | HTML composition authoring, captions, TTS, audio-reactive animation, transitions |
| `hyperframes` | Lightweight default entry point, environment preflight, and routing to the CLI/docs or optional production skill |
| `hyperframes-cli` | CLI commands: init, lint, preview, render, transcribe, tts, doctor |
| `hyperframes-registry` | Block and component installation via `hyperframes add` |
| `website-to-hyperframes` | Capture a URL and turn it into a video — full website-to-video pipeline |
| `remotion-to-hyperframes` | Translate a Remotion (React) composition into a HyperFrames HTML composition |
| `gsap` | GSAP timelines for HyperFrames: paused registration, deterministic seeking, easing, sequencing, performance |
| `animejs` | Anime.js animations and timelines registered on `window.__hfAnime` for deterministic HyperFrames seeking |
Expand All @@ -199,6 +200,14 @@ npx skills add heygen-com/hyperframes
| `three` | Three.js scenes that render from HyperFrames `hf-seek` events and `window.__hfThreeTime` instead of wall-clock time |
| `waapi` | Web Animations API `element.animate()` patterns seeked through `document.getAnimations()` |

Optional skills live under `optional-skills/` so default skill bundles do not need to carry the detailed authoring references and helper assets unless those workflows are explicitly enabled.
The install command above uses `--full-depth` so people explicitly installing HyperFrames get these production workflows too.

| Optional skill | What it adds |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `hyperframes-production` | Full production authoring workflow: design systems, captions, TTS, audio-reactive animation, transitions, helpers |
| `website-to-hyperframes` | Full website-to-video pipeline for capturing a URL and turning it into a video |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
Expand All @@ -222,7 +231,7 @@ winget install GitHub.GitLFS
git lfs install
```

If you hit `git-lfs filter-process: command not found` during `git clone` or `npx skills add heygen-com/hyperframes`, install Git LFS and retry. You can also skip LFS content if you only need the source files:
If you hit `git-lfs filter-process: command not found` during `git clone` or `npx skills add heygen-com/hyperframes --full-depth`, install Git LFS and retry. You can also skip LFS content if you only need the source files:

```bash
GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/heygen-com/hyperframes.git
Expand Down
10 changes: 5 additions & 5 deletions docs/guides/claude-design-hyperframes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -496,7 +496,7 @@ Opens the HyperFrames Studio at `http://localhost:3002` with frame-accurate scru
This project was drafted in Claude Design. To polish animations, timing, and pacing:

```bash
npx skills add heygen-com/hyperframes # install HyperFrames skills (one-time)
npx skills add heygen-com/hyperframes --full-depth # install HyperFrames skills (one-time)
npx hyperframes lint # verify structure (should pass with zero errors)
npx hyperframes preview # open the studio for live feedback
```
Expand Down Expand Up @@ -1222,8 +1222,8 @@ tl.to("#s5-headline", { backgroundSize: "100% 30%", duration: 0.6, ease: "power2
Everything critical is inlined above. These are for edge cases:

- Core composition contract (data attributes, sub-comp wiring): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/SKILL.md
- Motion theory (easing as emotion, direction rules): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/motion-principles.md
- Typography (full banned list, weight contrast, OpenType): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/typography.md
- Transitions (shader catalog, CSS transition patterns): https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/transitions.md
- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/skills/hyperframes/references/captions.md
- Motion theory (easing as emotion, direction rules): https://github.com/heygen-com/hyperframes/blob/main/optional-skills/hyperframes/references/motion-principles.md
- Typography (full banned list, weight contrast, OpenType): https://github.com/heygen-com/hyperframes/blob/main/optional-skills/hyperframes/references/typography.md
- Transitions (shader catalog, CSS transition patterns): https://github.com/heygen-com/hyperframes/blob/main/optional-skills/hyperframes/references/transitions.md
- Captions synced to audio: https://github.com/heygen-com/hyperframes/blob/main/optional-skills/hyperframes/references/captions.md
- Full docs: https://hyperframes.heygen.com/
8 changes: 4 additions & 4 deletions docs/guides/claude-design.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Claude Design produces a **valid first draft** of a HyperFrames video — brand
<Step title="Refine in any AI coding agent">
Open the project in Claude Code, Cursor, Codex, or any agent with terminal access for animation polish, timing, and production QA.
```bash
npx skills add heygen-com/hyperframes # install skills (one-time)
npx skills add heygen-com/hyperframes --full-depth # install skills (one-time)
npx hyperframes lint # should pass with zero errors
npx hyperframes preview # open the studio
```
Expand All @@ -39,8 +39,8 @@ Claude Design produces a **valid first draft** of a HyperFrames video — brand
| Surface | Recommended setup |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Claude Design | Download [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) from GitHub and attach to your chat |
| Claude Code | `npx skills add heygen-com/hyperframes`, then use `/hyperframes` |
| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes` |
| Claude Code | `npx skills add heygen-com/hyperframes --full-depth`, then use `/hyperframes` |
| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes --full-depth` |

## How it works

Expand Down Expand Up @@ -124,7 +124,7 @@ The more specific your prompt, the better the output. Include palette, fonts, du
Claude Design's output is a valid first draft. Open it in Claude Code, Cursor, Codex, or any AI coding agent with terminal access:

```bash
npx skills add heygen-com/hyperframes # one-time setup
npx skills add heygen-com/hyperframes --full-depth # one-time setup
npx hyperframes lint # verify structure
npx hyperframes preview # open the studio
```
Expand Down
8 changes: 4 additions & 4 deletions docs/guides/open-design.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Open Design produces a **valid first draft** of a HyperFrames composition — pa
The Open Design project folder is already a real on-disk working directory. Hand it off to Claude Code, Cursor, Codex, or any agent with terminal access:
```bash
cd .od/projects/<id>
npx skills add heygen-com/hyperframes # install skills (one-time)
npx skills add heygen-com/hyperframes --full-depth # install skills (one-time)
npx hyperframes lint # should pass with zero errors
npx hyperframes preview # open the studio
```
Expand All @@ -51,8 +51,8 @@ Open Design produces a **valid first draft** of a HyperFrames composition — pa
| Surface | Recommended setup |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open Design (open-source) | Drop [`open-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/open-design-hyperframes.md) into `skills/hyperframes-handoff/SKILL.md` |
| Claude Code | `npx skills add heygen-com/hyperframes`, then use `/hyperframes` |
| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes` |
| Claude Code | `npx skills add heygen-com/hyperframes --full-depth`, then use `/hyperframes` |
| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes --full-depth` |
| Claude Design (closed-source) | Attach [`claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) to your chat |

## How it works
Expand Down Expand Up @@ -151,7 +151,7 @@ Open Design's project folder is the agent's `cwd`. There's no "export then re-im

```bash
cd .od/projects/<your-project-id>
npx skills add heygen-com/hyperframes # one-time setup
npx skills add heygen-com/hyperframes --full-depth # one-time setup
npx hyperframes lint # verify structure
npx hyperframes preview # open the studio
```
Expand Down
Loading
Loading