Skip to content

Commit 95ca020

Browse files
ukimsanovclaude
ukimsanov
and
claude
committed
docs: update all Claude Design references for template-first skill
Update docs, quickstart, prompting guide, and README to reflect: - Template-first approach (attach file, not paste URL) - Claude Design produces drafts, refine in any AI coding agent - Known limitations (vertical shaders, seeking, no linting) - Practical example prompts (feature announcement, founder pitch) - Removed outdated references (invisible bridges, fetch-the-skills-tree) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent ee7c6c3 commit 95ca020

4 files changed

Lines changed: 109 additions & 126 deletions

File tree

‎README.md‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ npx skills add heygen-com/hyperframes
3333

3434
This teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions and GSAP animations. In Claude Code, the skills register as slash commands — invoke `/hyperframes` to author compositions, `/hyperframes-cli` for CLI commands, and `/gsap` for animation help.
3535

36-
For Claude Design, use the GitHub-hosted entry point at [`skills/claude-design-hyperframes/SKILL.md`](https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md) and let Claude fetch the repo's `skills/` tree from there. See the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design).
36+
For Claude Design, download [`skills/claude-design-hyperframes/SKILL.md`](https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md) and attach it to your chat. Claude Design produces a valid first draft; refine it in any AI coding agent. See the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design).
3737

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

@@ -184,14 +184,14 @@ HyperFrames ships [skills](https://github.com/vercel-labs/skills) that teach AI
184184
npx skills add heygen-com/hyperframes
185185
```
186186

187-
| Skill | What it teaches |
188-
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
189-
| `claude-design-hyperframes` | Claude Design entry point that pulls the upstream `skills/` tree and standardizes player-based previews |
190-
| `hyperframes` | HTML composition authoring, captions, TTS, audio-reactive animation, transitions |
191-
| `hyperframes-cli` | CLI commands: init, lint, preview, render, transcribe, tts, doctor |
192-
| `hyperframes-registry` | Block and component installation via `hyperframes add` |
193-
| `website-to-hyperframes` | Capture a URL and turn it into a video — full website-to-video pipeline |
194-
| `gsap` | GSAP animation API, timelines, easing, ScrollTrigger, plugins, React/Vue/Svelte, performance |
187+
| Skill | What it teaches |
188+
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
189+
| `claude-design-hyperframes` | Template-first Claude Design skill — pre-valid skeletons, produces video drafts for refinement in any coding agent |
190+
| `hyperframes` | HTML composition authoring, captions, TTS, audio-reactive animation, transitions |
191+
| `hyperframes-cli` | CLI commands: init, lint, preview, render, transcribe, tts, doctor |
192+
| `hyperframes-registry` | Block and component installation via `hyperframes add` |
193+
| `website-to-hyperframes` | Capture a URL and turn it into a video — full website-to-video pipeline |
194+
| `gsap` | GSAP animation API, timelines, easing, ScrollTrigger, plugins, React/Vue/Svelte, performance |
195195

196196
## Contributing
197197

‎docs/guides/claude-design.mdx‎

Lines changed: 91 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,37 @@
11
---
22
title: Claude Design
3-
description: "Use HyperFrames from Claude Design with a GitHub-hosted skill entry point that pulls the repo's existing skills and preview patterns."
3+
description: "Create HyperFrames video drafts in Claude Design using a template-first skill, then refine in any AI coding agent."
44
---
55

6-
Claude Design needs a different setup than Claude Code, Cursor, or Codex. The local `npx skills add heygen-com/hyperframes` flow is the right path for coding agents. For Claude Design, attach the HyperFrames skill file to your chat — empirically that produces sharper, more rule-compliant output than pasting the URL.
7-
8-
## Get the skill
9-
10-
<CardGroup cols={2}>
11-
<Card
12-
title="Download SKILL.md"
13-
icon="download"
14-
href="https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills/claude-design-hyperframes/SKILL.md"
15-
>
16-
Save the file, then drag it into a Claude Design chat as an attachment.
17-
</Card>
18-
<Card
19-
title="View on GitHub"
20-
icon="github"
21-
href="https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md"
22-
>
23-
Read the skill, copy sections, or link to it in a prompt.
24-
</Card>
25-
</CardGroup>
6+
Claude Design produces a **valid first draft** of a HyperFrames video — brand identity, scene content, layout, animations, and transitions. You then download the ZIP and refine in any AI coding agent (Claude Code, Cursor, Codex, Windsurf, etc.) with linting and live preview.
7+
8+
## Get started
9+
10+
<Steps>
11+
<Step title="Download the skill">
12+
Save [`SKILL.md`](https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills/claude-design-hyperframes/SKILL.md) to your computer.
13+
</Step>
14+
<Step title="Open Claude Design">
15+
Start a new chat at [claude.ai](https://claude.ai) with Claude Design enabled.
16+
</Step>
17+
<Step title="Attach the skill + describe your video">
18+
Drag the SKILL.md file into the chat. Describe what you want — include screenshots, brand assets, or a palette if you have them.
19+
</Step>
20+
<Step title="Download the ZIP">
21+
Claude Design produces `index.html`, `preview.html`, `README.md`, and `DESIGN.md`. Download the ZIP.
22+
</Step>
23+
<Step title="Refine in any AI coding agent">
24+
Open the project in Claude Code, Cursor, Codex, or any agent with terminal access for animation polish, timing, and production QA.
25+
```bash
26+
npx skills add heygen-com/hyperframes # install skills (one-time)
27+
npx hyperframes lint # should pass with zero errors
28+
npx hyperframes preview # open the studio
29+
```
30+
</Step>
31+
</Steps>
2632

2733
<Tip>
28-
**Prefer attaching the file over pasting the URL.** Claude Design reads file attachments natively with detail preserved. URL-driven runs produce usable output but consistently miss more rules than attachment-driven runs.
34+
**Attach the file, don't paste the URL.** Claude Design reads file attachments natively with detail preserved. URL-driven runs produce usable output but consistently miss more rules.
2935
</Tip>
3036

3137
## Which setup to use
@@ -36,127 +42,99 @@ Claude Design needs a different setup than Claude Code, Cursor, or Codex. The lo
3642
| Claude Code | `npx skills add heygen-com/hyperframes`, then use `/hyperframes` |
3743
| Cursor / Codex / Gemini CLI | `npx skills add heygen-com/hyperframes` |
3844

39-
## Prompt shape for Claude Design
40-
41-
Claude Design does not use slash commands. Lead with the skill file (attached or URL), describe the video, and ideally give Claude Design something to synthesize from — screenshots, a brand PDF, a reference video, a pasted palette, or at minimum a vibe in words.
45+
## How the skill works
4246

43-
The skill reads inputs in this order of reliability: **attachments → pasted content → web research → URLs**. A modern SPA homepage returns almost nothing via `web_fetch` because JavaScript isn't executed, so brand-accurate output on brief like "make a video for linear.app" depends on attaching screenshots or letting Claude Design search for the brand's blog, press, or Wikipedia.
47+
The skill gives Claude Design **pre-valid HTML skeletons** — the structural rules (data attributes, timeline registration, scene visibility, preview token forwarding) are already embedded. Claude Design fills in the creative work:
4448

45-
Strong Claude Design prompts usually include:
49+
1. **Palette + typography** — CSS custom properties on `:root`
50+
2. **Scene content** — text, images, layout inside `.scene-content` wrappers
51+
3. **Animations** — GSAP entrance tweens and mid-scene activity
52+
4. **Transitions** — hard cuts for most scenes, shader transitions at 2-3 key moments
4653

47-
- the attached skill file (or its URL)
48-
- the source material: screenshots, a brand PDF, a reference video, pasted copy, or a URL
49-
- duration and aspect ratio
50-
- tone or visual direction (if you have one — otherwise let Claude Design ask)
51-
- explicit deliverables: `index.html`, `preview.html`, `README.md`
54+
This template-first approach means the output passes `npx hyperframes lint` with zero errors on first download — Claude Code can start refining immediately without structural fixes.
5255

53-
## Copy-paste prompts
56+
## Example prompts
5457

5558
<CardGroup cols={1}>
56-
<Card title="Rich brief (attach SKILL.md + screenshots)">
59+
<Card title="Feature announcement (attach SKILL.md)">
5760
```text
58-
Use the attached skill. Make a 30-second 16:9 product walkthrough for my app,
59-
matching the design in these screenshots. 5 scenes: hero, three features,
60-
closing CTA. Shader transitions between scenes.
61+
Use the attached skill. I just shipped dark mode for my app. Make me a
62+
15-second Instagram reel announcing it.
63+
64+
- App name: Taskflow
65+
- Primary color: #6C5CE7
66+
- The vibe is clean, minimal, dark
67+
- Key stat: "47% of users requested this"
6168
```
6269
</Card>
63-
<Card title="Pasted-content brief (attach SKILL.md + paste your copy)">
70+
<Card title="Founder pitch (attach SKILL.md)">
6471
```text
65-
Use the attached skill. 30s hero reel with this copy for each scene:
72+
Use the attached skill. 25-second LinkedIn video for my startup.
6673
67-
1. "The fast web broke us."
68-
2. "Every app optimized for attention. None for thought."
69-
3. "Something is changing. Blogs are back."
70-
4. "Welcome to the slow web."
74+
Problem: Sales teams waste 3 hours/day on manual CRM updates.
75+
Solution: AutoCRM — AI that logs every call, email, and meeting.
76+
Traction: 200+ teams, $1.2M ARR, 18% MoM growth.
77+
CTA: autocrmhq.com
7178
72-
Dark theme, editorial, serif typography (not Playfair).
79+
Professional but not corporate. Think Linear or Vercel energy.
7380
```
7481
</Card>
75-
<Card title="Sparse brief (attach SKILL.md, let it ask)">
82+
<Card title="Stat highlight (attach SKILL.md)">
7683
```text
77-
Use the attached skill. Make a 30-second launch video for Orbit.
78-
```
84+
Use the attached skill. 10-second reel. Just one big number:
7985
80-
The skill will ask ONE short question offering five input channels
81-
(screenshot, PDF, reference video, vibe word, must-have element) plus
82-
a "just build" escape hatch before generating.
86+
"$4.2 billion processed in Q1 2026"
87+
88+
Dark background, the number should animate up from zero. Subtle,
89+
confident. End with logo placeholder and "stripe.com"
90+
```
8391
</Card>
84-
<Card title="Static URL brief (editorial piece, not a SPA)">
92+
<Card title="Sparse brief (attach SKILL.md, let it ask)">
8593
```text
86-
Use the HyperFrames Claude Design skill at
87-
https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md
88-
and turn https://www.anthropic.com/news/claude-design-anthropic-labs into a
89-
45-second editorial explainer. Keep copy close to the article's real headlines.
94+
Use the attached skill. Make a 30-second launch video for Orbit.
9095
```
96+
97+
The skill asks ONE short clarifying question before generating.
9198
</Card>
9299
</CardGroup>
93100

94-
## Preview with `@hyperframes/player`
95-
96-
When Claude Design generates a `preview.html`, it embeds the composition with `<hyperframes-player>` and forwards the Claude Design sandbox's preview token into the iframe src. Without the token forward, the in-pane preview renders black (the sandbox serves a `"preview token required"` placeholder to the iframe).
97-
98-
Copy this template verbatim:
99-
100-
```html
101-
<!doctype html>
102-
<html>
103-
<head>
104-
<meta charset="utf-8">
105-
<title>HyperFrames Preview</title>
106-
<style>html,body{margin:0;padding:0;background:#111;height:100%;overflow:hidden}</style>
107-
<script type="module" src="https://cdn.jsdelivr.net/npm/@hyperframes/player"></script>
108-
</head>
109-
<body>
110-
<hyperframes-player id="p" controls autoplay muted
111-
style="display:block;width:100vw;height:100vh"></hyperframes-player>
112-
<script>
113-
document.getElementById("p").setAttribute(
114-
"src",
115-
"./index.html" + location.search,
116-
);
117-
</script>
118-
</body>
119-
</html>
120-
```
101+
## What to include in your prompt
121102

122-
When `location.search` is empty (opened locally, outside Claude Design's sandbox), the token-forward line is a no-op and the player loads `./index.html` as expected.
103+
Claude Design reads inputs in this order of reliability: **attachments > pasted content > web research > URLs**.
123104

124-
The composition (`index.html`) must also pre-load the HyperFrames runtime right after GSAP so the player can drive playback inside Claude Design's sandbox:
105+
| Input type | What it gives Claude Design |
106+
| --- | --- |
107+
| Screenshots / PDFs / brand guides | Palette, typography, UI patterns, tone — strongest source |
108+
| Pasted hex codes, typefaces, copy | Authoritative for what it covers |
109+
| Brand name (well-known) | Claude Design can research blogs, press, Wikipedia |
110+
| SPA URL (React/Vue homepage) | Returns near-empty shell — pivot to blog/press instead |
125111

126-
```html
127-
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
128-
<script src="https://cdn.jsdelivr.net/npm/@hyperframes/core/dist/hyperframe.runtime.iife.js"></script>
129-
```
112+
The more specific your prompt, the better the output. Include palette, fonts, duration, and scene ideas when you have them.
130113

131-
If a classic script tag is needed instead of ESM, use the global player build with the same token-forwarding script:
132-
133-
```html
134-
<script src="https://cdn.jsdelivr.net/npm/@hyperframes/player/dist/hyperframes-player.global.js"></script>
135-
<hyperframes-player id="p" controls autoplay muted
136-
style="display:block;width:100vw;height:100vh"></hyperframes-player>
137-
<script>
138-
document.getElementById("p").setAttribute(
139-
"src",
140-
"./index.html" + location.search,
141-
);
142-
</script>
143-
```
114+
## Known limitations
115+
116+
- **In-pane preview** — scrubbing is unreliable in Claude Design's iframe sandbox. Download and use `npx hyperframes preview` locally for reliable playback.
117+
- **No linting** — Claude Design can't run `npx hyperframes lint`. The template-first skeletons handle structural validity, but the self-review checklist is the only QA before download.
118+
- **No shaders on vertical** — HyperShader's WebGL canvas is hardcoded to 1920x1080. Vertical (1080x1920) compositions use hard cuts only.
119+
- **3 fetch limit** — Claude Design limits web fetches per turn. All critical rules are inlined in the skill; external references are for edge cases only.
120+
- **Seeking backwards** — scrubbing backwards in the in-pane preview can show blank frames (async capture race condition). Forward seeking usually works.
144121

145-
See [`@hyperframes/player`](/packages/player) for the full API and framework examples.
122+
## The handoff to your coding agent
146123

147-
## What the skill teaches Claude Design
124+
Claude Design's output is a valid first draft. Open it in Claude Code, Cursor, Codex, or any AI coding agent with terminal access:
125+
126+
```bash
127+
npx skills add heygen-com/hyperframes # one-time setup
128+
npx hyperframes lint # verify structure
129+
npx hyperframes preview # open the studio
130+
```
148131

149-
The skill is self-contained — it includes every HyperFrames-specific contract and every known Claude Design sandbox workaround, so Claude Design rarely needs to fetch additional references. Highlights:
132+
Then iterate:
150133

151-
- An explicit opening redirect: Claude Design is told NOT to reach for its default video artifacts (`copy_starter_component` with `kind: "animations.jsx"`, the built-in "Animated video" skill, React + Babel JSX, hand-rolled scale-to-fit stage wrappers). This is the single change that most reliably keeps Claude Design on the HyperFrames path
152-
- Correct `data-*` composition structure, the clip contract on scenes, and paused GSAP timelines registered on `window.__timelines`
153-
- Shader-transition timing rules: transitions must span the scene boundary (not start at it), animated content must be wrapped in `<div class="scene-content">` so its pre-animation state doesn't leak into the WebGL texture, and the `scenes.length === transitions.length + 1` invariant (with `flash-through-white` as the invisible-bridge escape hatch)
154-
- Sandbox-compatible preview: token-forwarding `preview.html` template, runtime pre-load in `index.html`, `data-composition-id` ↔ `__timelines` key match (and a convention that the root element's DOM `id` matches too)
155-
- Attachment-first input model: read screenshots / PDFs / reference videos when provided, otherwise ask one short clarifying question before generating
156-
- A banned-font list (including Fraunces, Inter Tight, and common AI defaults) plus a banned-pairings line to break the training-data monoculture
157-
- Deterministic render-safe animation choices (no `Date.now()`, no unseeded `Math.random()`, no `repeat: -1`, no `stagger: { from: "random" }`)
158-
- Four worked-example anti-patterns with WRONG/RIGHT code pairs — exit tweens before shader transitions, non-deterministic `stagger` origins, absolute-positioned content containers, and SVG filter data URLs as `background-image` (the last one causes `SecurityError` on Safari + cross-origin iframe environments)
159-
- A `README.md` template for the end user with `npx hyperframes doctor` / `preview` / `render` commands and FFmpeg install instructions
134+
- "Make scene 3's entrance snappier"
135+
- "Add a counter animation to the stat in scene 5"
136+
- "Tighten the pacing — scenes 4 and 6 feel too long"
137+
- "Change the shader on transition 2 to glitch"
160138

161139
## Next steps
162140

‎docs/guides/prompting.mdx‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,13 +29,18 @@ In Claude Code, restart the session after installing. Skills register as **slash
2929

3030
## Claude Design
3131

32-
Claude Design uses a different setup. Instead of local slash commands, point it at the GitHub-hosted Claude Design entry point for HyperFrames:
32+
Claude Design uses a different setup. Download [`SKILL.md`](https://raw.githubusercontent.com/heygen-com/hyperframes/main/skills/claude-design-hyperframes/SKILL.md) and **attach it to your chat** (don't paste the URL — file attachments produce better output):
3333

3434
```text
35-
Use https://github.com/heygen-com/hyperframes/blob/main/skills/claude-design-hyperframes/SKILL.md and make a 30-second product video about [topic]. Deliver index.html, preview.html, and README.md.
35+
Use the attached skill. 25-second LinkedIn video for my startup.
36+
37+
Problem: Sales teams waste 3 hours/day on manual CRM updates.
38+
Solution: AutoCRM — AI that logs every call, email, and meeting.
39+
Traction: 200+ teams, $1.2M ARR, 18% MoM growth.
40+
CTA: autocrmhq.com
3641
```
3742

38-
That entry point tells Claude Design to fetch the broader [`skills/`](https://github.com/heygen-com/hyperframes/tree/main/skills) tree, apply the same HyperFrames rules, and use `@hyperframes/player` for preview pages. See the [Claude Design guide](/guides/claude-design) for the recommended prompt shape.
43+
Claude Design produces a valid first draft (brand identity, scene content, animations, transitions). Download the ZIP and refine in any AI coding agent with `npx hyperframes preview` running. See the [Claude Design guide](/guides/claude-design) for the full workflow.
3944

4045
## The two prompt shapes
4146

0 commit comments

Comments
 (0)