From eb0edfdb2bd949fc6a7872a49bc42e489244dede Mon Sep 17 00:00:00 2001 From: Miao Yang Date: Wed, 29 Jul 2026 14:29:37 +0800 Subject: [PATCH 1/7] docs(prompting): correct workflow one-liners against skill contracts general-video leads with its positive identity and companion mode; faceless-explainer keys on invented visuals instead of TTS; talking-head-recut uses the 'graphic overlays' trigger term; motion-graphics gains its input side and overlay output; music-to-video stops implying images are required. --- docs/prompting/overview.mdx | 10 +++++----- docs/quickstart.mdx | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/prompting/overview.mdx b/docs/prompting/overview.mdx index abfc5a0120..bc0a3eab54 100644 --- a/docs/prompting/overview.mdx +++ b/docs/prompting/overview.mdx @@ -48,19 +48,19 @@ The installer shows a picker. Select the **core skills** below — every project | `/media-use` | Media OS — TTS voiceover (`tts`), `transcribe`, `remove-background`, plus BGM / SFX / image resolution | | `/hyperframes-registry` | Block and component installation via `hyperframes add` | | `/hyperframes-keyframes`| Seek-safe keyframe authoring across runtimes, plus `hyperframes keyframes` diagnostics | -| `/general-video` | The general authoring workflow — fallback for any video that doesn't match a specific workflow below | +| `/general-video` | The general authoring workflow — multi-scene pieces, reels, montages, remixes, and the home of **companion mode**; the fallback when no workflow below fits | **Optional workflows — add the ones that match your inputs** (`/hyperframes` routes to whichever you've installed) | Slash command | Input → output | | ------------------------ | --------------------------------------------------------------------------- | | `/product-launch-video` | Any website URL / brief / script → launch or promo video, or a site tour / showcase | -| `/faceless-explainer` | Arbitrary text (no URL) → faceless explainer with its own TTS narration | +| `/faceless-explainer` | Arbitrary text (no URL, no footage) → faceless explainer — every visual invented (typography, diagrams, data-viz) | | `/pr-to-video` | A GitHub PR → code-change explainer | | `/embedded-captions` | An existing talking-head video → the same footage with captions / subtitles | -| `/talking-head-recut` | An existing talking-head video → footage packaged with designed graphic cards | -| `/motion-graphics` | A short, unnarrated, design-led motion graphic (logo sting, kinetic type, stat / chart) | -| `/music-to-video` | A music track + your images → beat-synced video (lyric / slideshow / kinetic promo) | +| `/talking-head-recut` | An existing talking-head video → footage packaged with transcript-synced graphic overlays (kinetic titles, lower-thirds, PiP) | +| `/motion-graphics` | A logo / stat / tweet / brief → a short (~10s) unnarrated motion graphic (kinetic type, count-up, logo sting) — MP4 or transparent overlay | +| `/music-to-video` | A music track (or a video's audio) → beat-synced video (lyric / slideshow / kinetic promo); your images optional, cut on the beat | | `/slideshow` | A deck outline or slides → navigable presentation with presenter mode (not a rendered MP4) | | `/remotion-to-hyperframes` | Port an existing Remotion (React) composition to HyperFrames HTML | | `/figma` | A Figma file / frame / URL → imported assets, brand tokens, and reconstructed motion | diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 8da022d5ca..916ab1244d 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -24,7 +24,7 @@ The installer shows a picker. Select the **core set** every project needs — th | `/hyperframes-cli` | Dev-loop CLI — init, lint, preview, render, doctor | | `/media-use` | Asset preprocessing — TTS, transcription, background removal | | `/hyperframes-registry` | Install catalog blocks and components | -| `/general-video` | The general authoring workflow — the fallback for any video that doesn't match a specific workflow | +| `/general-video` | The general authoring workflow — multi-scene pieces, reels, montages, remixes, and the home of companion mode; the fallback when no specific workflow fits | The **workflow skills** are optional — add the ones that match your inputs, and `/hyperframes` routes to whichever you've installed: `/product-launch-video`, `/faceless-explainer`, `/pr-to-video`, `/embedded-captions`, `/talking-head-recut`, `/motion-graphics`, `/music-to-video`, `/slideshow`, `/general-video`, `/remotion-to-hyperframes`. See the [skills catalog](/guides/skills) for the full list with one-line "use when" descriptions. From 833e20ca9f5338448f600f53d7d751125e3b30a6 Mon Sep 17 00:00:00 2001 From: Miao Yang Date: Wed, 29 Jul 2026 14:29:38 +0800 Subject: [PATCH 2/7] docs(prompting): make vocabulary video grids readable Replace the 4-5 column table hack with a 3-column CSS grid, switch demo clips to autoplay muted loops (no black poster frame, no player chrome over tiny videos), and align cells at 16:9. --- docs/prompting/vocabulary.mdx | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/docs/prompting/vocabulary.mdx b/docs/prompting/vocabulary.mdx index 27ccdc6bea..b870d218f2 100644 --- a/docs/prompting/vocabulary.mdx +++ b/docs/prompting/vocabulary.mdx @@ -22,10 +22,14 @@ Describe how motion should *feel* and the agent picks the matching GSAP ease: Each word, rendered — the same move, only the ease changes: - - - -
smooth · power2.out
snappy · power4.out
bouncy · back.out
springy · elastic.out
dramatic · expo.out
dreamy · sine.inOut
+
+
smooth · power2.out
+
snappy · power4.out
+
bouncy · back.out
+
springy · elastic.out
+
dramatic · expo.out
+
dreamy · sine.inOut
+
## Camera language @@ -44,10 +48,15 @@ Compositions have no physical camera, but camera words translate directly into s The same scene under each camera word: - - - -
slow push-in
pull back
pan across
crane down
whip to
parallax
drone orbit (Three.js)
+
+
slow push-in
+
pull back
+
pan across
+
crane down
+
whip to
+
parallax
+
drone orbit (Three.js)
+
## Depth language @@ -161,9 +170,13 @@ Hand-drawn emphasis effects for text: The five modes on the same sentence: - - -
highlight
circle
burst
scribble
sketchout
+
+
highlight
+
circle
+
burst
+
scribble
+
sketchout
+
## Text-to-speech voices From 12e663b1385b2897ecc7e1de589c919656dbd4d4 Mon Sep 17 00:00:00 2001 From: Miao Yang Date: Wed, 29 Jul 2026 14:50:07 +0800 Subject: [PATCH 3/7] docs(prompting): document the opening interview and run-shape questions The guide taught prompt shapes but never prepared readers for the conversation that follows: the intent interview, the two run-shape questions (storyboard, automation vs companion), the just-build-it skip, and BRIEF.md as the resumable artifact. Add that section to the overview, a disambiguation note on the storyboards page, and free up 'companion' as a reserved term in media-and-audio. --- docs/prompting/media-and-audio.mdx | 2 +- docs/prompting/overview.mdx | 19 +++++++++++++++++++ docs/prompting/storyboards.mdx | 6 +++++- 3 files changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/prompting/media-and-audio.mdx b/docs/prompting/media-and-audio.mdx index 5e0abf0e43..bff7bf82dd 100644 --- a/docs/prompting/media-and-audio.mdx +++ b/docs/prompting/media-and-audio.mdx @@ -3,7 +3,7 @@ title: Media and audio description: "Ask for the voiceover, music, sound, captions, cutouts, and assets a composition needs — with the precise, unambiguous phrasing the media pipeline acts on." --- -By now your video moves and reads right; this level gives it a voice. HyperFrames owns media *playback*; a companion media pipeline resolves everything else — voice, music, sound effects, images, icons, logos, captions, and background removal. You reach all of it by describing what the composition needs, and the agent resolves each need to a frozen local file. The craft here is precision: vague media asks ("add some music," "no sound") are the ones that come back wrong, because the pipeline does exactly what the words say. +By now your video moves and reads right; this level gives it a voice. HyperFrames owns media *playback*; a sibling media pipeline resolves everything else — voice, music, sound effects, images, icons, logos, captions, and background removal. You reach all of it by describing what the composition needs, and the agent resolves each need to a frozen local file. The craft here is precision: vague media asks ("add some music," "no sound") are the ones that come back wrong, because the pipeline does exactly what the words say. ## Voiceover (TTS) diff --git a/docs/prompting/overview.mdx b/docs/prompting/overview.mdx index bc0a3eab54..3f89625cf7 100644 --- a/docs/prompting/overview.mdx +++ b/docs/prompting/overview.mdx @@ -108,6 +108,25 @@ Warm-start prompts produce richer, more grounded videos because the agent is wri The four prompts above illustrate shape, not results — every prompt in this guide that ships with an embedded render was run exactly as written, and the gallery of those lives in [Verified examples](/prompting/examples). +## The interview: what the agent asks first + +Either shape starts a short interview before anything is built. This isn't the agent stalling — it's the intent layer turning "make me a video" into a confirmed brief, so the build never has to guess the things you'd have corrected afterward. The agent confirms the route, then asks that workflow's must-have questions (recommended answer first, so most are one-word confirmations). When the selected workflow supports both run shapes, it then closes with two questions that shape the run itself: + +| Question | Your options | +| --- | --- | +| **Storyboard?** | `yes` — review the plan, wireframe sketches, and the build pass by pass on a live board (recommended past a couple of scenes) · `no` — one finished video from the confirmed brief | +| **Automation or companion?** | `automation` — the matched workflow's pipeline executes the brief end to end · `companion` — build it together in `/general-video` with every HyperFrames capability on the table | + +The two are independent — all four combinations are valid, and a companion run reviews on the live board too when you said yes to the storyboard. Four routes skip both questions because neither has anything to add: `/motion-graphics` (the piece is seconds long), `/slideshow` (the deliverable is a navigable deck, not a rendered video), and `/embedded-captions` and `/talking-head-recut` (the footage is untouched, so there's no storyboard to review). + +In a hurry, skip the whole conversation by saying so: + +> Just build it — don't ask me anything. + +That locks `automation` with no storyboard wherever those apply, and every question the agent would have asked becomes a stated default in its heads-up instead. + +Everything the interview settles is written to **`BRIEF.md`** in the project root — the brief is the artifact, not the chat. A later session (or a different agent) resumes from that file and asks nothing again; to change an answer, edit `BRIEF.md` rather than re-explaining yourself in the prompt. + ## Recommended workflow 1. `npx hyperframes init my-video` — scaffold a project (skills install automatically) diff --git a/docs/prompting/storyboards.mdx b/docs/prompting/storyboards.mdx index a36e60ad18..66c69fb5bc 100644 --- a/docs/prompting/storyboards.mdx +++ b/docs/prompting/storyboards.mdx @@ -7,6 +7,10 @@ description: "For multi-scene work, don't prompt the scenes one by one — promp This narrative vocabulary is a writing discipline, not additional `STORYBOARD.md` schema: the workflow translates the plan into the smaller machine-readable shape the build consumes. + +"Storyboard" is also a question the agent asks in the [opening interview](/prompting/overview#the-interview-what-the-agent-asks-first) — answering yes there means the plan, the sketches, and the build get reviewed with you pass by pass on a live board. That answer changes the review process, not the route, and either way the plan this page teaches is what the build works from. + + ## Prompt the plan, not the scenes A storyboard is a short, structured document that sits above the individual frames: one arc, one direction block that every frame inherits, and a light per-frame spec (not a full description) for each key moment. The workflow reads the plan and builds each frame's HTML sub-composition against it — so a plan that's precise about the *shape* of the film produces frames that already agree with each other on pacing, palette, and payoff, without you re-stating any of that per frame. @@ -97,7 +101,7 @@ Without stating the return explicitly, a rebuild is free to treat the early moti The two-color discipline and brand tokens a storyboard's direction block draws from. - `STORYBOARD.md` as a production artifact — the file format this chapter's prompts turn into. + `STORYBOARD.md` as a production artifact — where this chapter's plans land, downstream of `BRIEF.md`. From 30f9dd1c8a125de02930f7bc973a365e0007409b Mon Sep 17 00:00:00 2001 From: Miao Yang Date: Wed, 29 Jul 2026 14:50:08 +0800 Subject: [PATCH 4/7] docs(guides): make BRIEF.md the pipeline's Step 3 artifact Step 3 (Strategy & Messaging) listed no output while describing exactly what BRIEF.md now captures. Name the artifact in the step table, project tree, step body, gate, and iterating list, and fix SCRIPT.md's step label in the tree (Step 4, not 3). --- docs/guides/pipeline.mdx | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/guides/pipeline.mdx b/docs/guides/pipeline.mdx index 909293eb03..ff391b04b1 100644 --- a/docs/guides/pipeline.mdx +++ b/docs/guides/pipeline.mdx @@ -15,7 +15,7 @@ Each step produces an artifact that feeds the next: |---|-------------------------|-----------------------------------------|-------------------------------------------------------------------------| | 1 | **Capture** | `capture/` | Extract screenshots, design tokens, fonts, assets, animations from a source | | 2 | **Design** | `DESIGN.md` | Brand reference: colors, typography, component stylings, spacing, iteration guide | -| 3 | **Strategy & Messaging**| — | Align on video type, style, the ONE message, narrative arc, and audience | +| 3 | **Strategy & Messaging**| `BRIEF.md` | Lock video type, style, the ONE message, arc, audience — and the run's shape (automation or companion, storyboard or one-shot) | | 4 | **Storyboard + Script** | `STORYBOARD.md` + `SCRIPT.md` | Concept-first storyboard and narration script, written together | | 5 | **VO + Timing** | `narration.wav` + `transcript.json` | TTS audio with word-level timestamps | | 6 | **Build** | `compositions/*.html` | Animated HTML compositions, one per beat | @@ -38,7 +38,8 @@ my-video/ │ ├── AGENTS.md # capture summary for AI agents │ └── CLAUDE.md ├── DESIGN.md # Step 2, brand cheat sheet -├── SCRIPT.md # Step 3, narration backbone +├── BRIEF.md # Step 3, confirmed intent: message, audience, run shape +├── SCRIPT.md # Step 4, narration backbone ├── STORYBOARD.md # Step 4, beat-by-beat creative plan ├── narration.wav # Step 5, TTS audio ├── narration.txt # Step 5, exact spoken text (with pronunciation subs) @@ -92,13 +93,15 @@ A typical `DESIGN.md` has five sections: ## Step 3: Strategy & Messaging -**Output:** Alignment on video type, duration, style, and — critically — the ONE message and narrative arc +**Output:** `BRIEF.md` in the project root Before any creative decisions, align with the user on the story this video must tell. Parse the user's prompt first — they probably already gave you the video type and style. Only ask about things they didn't specify. If the prompt is detailed enough, confirm the direction in one message and move to Step 4. The questions to resolve: what type of video (social ad, product demo, brand reel, etc.), what style and energy, what's the ONE thing this video must communicate, what narrative arc serves that message, and whether narration is wanted. -**Gate:** Video type, duration, format, and the message and narrative arc are locked. Without those, Step 4 can't write a concept-first storyboard. +When the project starts from `/hyperframes`, this step is the [opening interview](/prompting/overview#the-interview-what-the-agent-asks-first) — and it runs before Step 1, since the answers decide whether there's anything to capture at all. Either way, the confirmed answers land in `BRIEF.md`: frontmatter keys for the deterministic fields (`workflow`, `flow`, `storyboard`, `message`, audience, length), prose sections for the intent and any supplied material. A later session resumes from this file instead of re-asking. + +**Gate:** `BRIEF.md` exists — video type, duration, format, message, and narrative arc locked. Without those, Step 4 can't write a concept-first storyboard. ## Step 4: Storyboard + Script @@ -185,6 +188,7 @@ For personalized or catalog outputs, render the same validated composition with The pipeline is built around named artifacts on disk so you can re-enter anywhere without re-running everything: +- To change what the video is *for* — the message, the audience, the run's shape — edit `BRIEF.md`; it's the file the agent trusts over chat history. - To rework the creative plan, edit `STORYBOARD.md`: change a beat's mood, swap an asset, retime the entrance, then ask the agent to rebuild just that beat. - For surgical tweaks, open a composition file directly (e.g. `compositions/beat-3-proof.html`) and adjust animations, colors, or layout. `npx hyperframes preview` shows changes live. - To rebuild one beat from scratch, prompt the agent: _"Rebuild beat 2 with more energy. Use the product screenshot as full-bleed background."_ It reads `STORYBOARD.md`, `DESIGN.md`, and the transcript, then regenerates just that file. From d3b0430e6a7ab18e1a06a68a0a86e71896c0d710 Mon Sep 17 00:00:00 2001 From: Miao Yang Date: Thu, 30 Jul 2026 20:24:33 +0800 Subject: [PATCH 5/7] docs(quickstart): realign the setup surface with the skills catalog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The quickstart drifted from docs/guides/skills.mdx, CLAUDE.md, and the prompting overview — it had never been updated when those surfaces were: - `--full-depth` on both install commands, with the reason inline. Without it `skills add` fetches the skills.sh registry blob, which lags `main` by hours, so a reader following the quickstart installs stale skills. - `check` in the `/hyperframes-cli` row, and a validate step in the manual dev loop, which went preview → render with no gate at all. The prompting overview calls `check` "the step people skip and regret" and states both `lint` and `check` must pass before rendering. - `/hyperframes-keyframes` in the core-skills table (8 rows → 9). - `/figma` in the optional-workflow list (10 → 11). Co-Authored-By: Claude Opus 5 (1M context) --- docs/quickstart.mdx | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 916ab1244d..07f4754300 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -10,9 +10,11 @@ Go from zero to a rendered MP4 — either by prompting your AI agent or by start 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 ``` +Keep `--full-depth`: it installs the current `main`. Without it, `skills add` fetches the skills.sh registry blob, which lags `main` by hours — you'd get stale skills. + The installer shows a picker. Select the **core set** every project needs — these register as slash commands in Claude Code (Cursor, Gemini CLI, Codex, [Google Antigravity](/guides/antigravity), and [GitHub Copilot CLI](/guides/copilot-cli) load them too): | Core skill (install all) | What it does | @@ -21,15 +23,16 @@ The installer shows a picker. Select the **core set** every project needs — th | `/hyperframes-core` | Composition contract — HTML structure, `data-*` attributes, clips, tracks | | `/hyperframes-animation` | All animation + the GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU runtime adapters | | `/hyperframes-creative` | Design direction — palettes, typography, narration, beat planning | -| `/hyperframes-cli` | Dev-loop CLI — init, lint, preview, render, doctor | +| `/hyperframes-cli` | Dev-loop CLI — init, lint, check, preview, render, doctor | | `/media-use` | Asset preprocessing — TTS, transcription, background removal | | `/hyperframes-registry` | Install catalog blocks and components | +| `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes, plus `hyperframes keyframes` diagnostics | | `/general-video` | The general authoring workflow — multi-scene pieces, reels, montages, remixes, and the home of companion mode; the fallback when no specific workflow fits | -The **workflow skills** are optional — add the ones that match your inputs, and `/hyperframes` routes to whichever you've installed: `/product-launch-video`, `/faceless-explainer`, `/pr-to-video`, `/embedded-captions`, `/talking-head-recut`, `/motion-graphics`, `/music-to-video`, `/slideshow`, `/general-video`, `/remotion-to-hyperframes`. See the [skills catalog](/guides/skills) for the full list with one-line "use when" descriptions. +The **workflow skills** are optional — add the ones that match your inputs, and `/hyperframes` routes to whichever you've installed: `/product-launch-video`, `/faceless-explainer`, `/pr-to-video`, `/embedded-captions`, `/talking-head-recut`, `/motion-graphics`, `/music-to-video`, `/slideshow`, `/general-video`, `/remotion-to-hyperframes`, `/figma`. See the [skills catalog](/guides/skills) for the full list with one-line "use when" descriptions. - To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all`. + To skip the picker and install everything (core + every workflow) in one shot, run `npx skills add heygen-com/hyperframes --all --full-depth`. These skills teach your agent how to write correct compositions, GSAP and runtime-adapter animations, Tailwind v4 browser-runtime styles, captions, and voiceovers. Invoking a slash command loads its context explicitly, which produces correct output the first time — and **starting at `/hyperframes` lets it route your request to the right workflow.** @@ -219,6 +222,15 @@ The agent handles scaffolding, animation, and rendering. See the [prompting guid - **GSAP timeline** must be created with `{ paused: true }` and registered on `window.__timelines` + + ```bash + npx hyperframes lint + npx hyperframes check + ``` + + `lint` checks the HTML structure statically; `check` runs the composition in a headless browser and reports what a still frame can't — an element overflowing its region, colliding text, a runtime error that only fires mid-timeline, contrast below WCAG AA. Both must pass before you render: a render that took ten minutes will happily contain a defect `check` names in seconds. + + ```bash npx hyperframes render --output output.mp4 From 7608fa89904a856ca3433fbd8134b253fce49a2f Mon Sep 17 00:00:00 2001 From: Miao Yang Date: Thu, 30 Jul 2026 22:01:18 +0800 Subject: [PATCH 6/7] docs(skills): close the catalog drift class and complete the music-to-video input MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up on the two review nits from #2872. `/music-to-video`'s SKILL.md names three inputs — an audio file, a video to pull audio from, or a track generated from a mood brief. Every compressed copy of that description carried only the first two, and the third is the one that makes "a complete video needs zero assets" true. Fixed on all eight surfaces that state it, so no surface is now more correct than its siblings: the prompting overview and quickstart setup tables, docs/guides/skills.mdx, the README catalog, root CLAUDE.md + AGENTS.md, both CLI project templates, and the router's own routes/music-to-video.md Input line (whose Interview must-haves already listed all three). The drift was structural, not accidental: the sync set declared in docs/guides/skills.mdx and in CLAUDE.md's "Skill catalog maintenance" named four surfaces and never the two setup tables, so those two were free to rot while the declared four stayed correct. Both declarations now name them, and both say the set applies to a *changed contract* — a reworded description — not only to an added or renamed skill. skills-manifest.json regenerated for the touched route file. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 2 +- CLAUDE.md | 4 ++-- README.md | 2 +- docs/guides/skills.mdx | 4 ++-- docs/prompting/overview.mdx | 2 +- packages/cli/src/templates/_shared/AGENTS.md | 2 +- packages/cli/src/templates/_shared/CLAUDE.md | 2 +- skills-manifest.json | 2 +- skills/hyperframes/references/routes/music-to-video.md | 2 +- 9 files changed, 11 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dc26d2fdf3..8c01de6aa1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,7 +19,7 @@ npx skills add heygen-com/hyperframes --full-depth # interactive picker (termi - `/talking-head-recut` — an existing talking-head / interview / podcast video (MP4) → the same footage packaged with designed **graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath, footage untouched. For plain captions/subtitles → `/embedded-captions`. - `/pr-to-video` — a GitHub PR (URL / `owner/repo#N` / "this PR") → code-change explainer, up to ~3 min (changelog / feature reveal / fix / refactor). A PR link, not a product website. - `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`. -- `/music-to-video` — a **music track** (audio file, or video to pull audio from) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid. +- `/music-to-video` — a **music track** (audio file, video to pull audio from, or one generated from a mood brief) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid. - `/slideshow` — a **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. - `/general-video` — fallback for any other video creation (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of **companion mode** — co-create with the full HyperFrames toolbox; the original hyperframes flow — design → plan → layout → build → validate, any length. diff --git a/CLAUDE.md b/CLAUDE.md index 188eaf9e6f..4d9e0728ef 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,7 +25,7 @@ Keep `--full-depth`: it installs the current `main`. Without it, `skills add` fe - `/embedded-captions` — an existing talking-head video (MP4) → the same footage with captions / subtitles added (verbatim rail + embedded climax, or pure-cinematic embed); the footage itself is untouched (no NLE-style editing). - `/talking-head-recut` — an existing talking-head / interview / podcast video (MP4) → the same footage packaged with designed **graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, PiP) synced to the transcript; the clip plays unchanged underneath, footage untouched. For plain captions/subtitles → `/embedded-captions`. - `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`. -- `/music-to-video` — a **music track** (audio file, or video to pull audio from) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid. +- `/music-to-video` — a **music track** (audio file, video to pull audio from, or one generated from a mood brief) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid. - `/slideshow` — a **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. - `/general-video` — fallback for any other video creation (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of **companion mode** — co-create with the full HyperFrames toolbox; the original hyperframes flow — design → plan → layout → build → validate, any length. - `/remotion-to-hyperframes` — port an existing Remotion (React) composition to HyperFrames HTML. One-way migration, not creation. @@ -47,7 +47,7 @@ Atomic capabilities the creation workflows compose against — pull one when you When adding a new skill, or substantially renaming / repurposing an existing one, update all agent-facing discoverability surfaces in lockstep: -1. The skill list above (CLAUDE.md) AND the workflow list in the root `AGENTS.md` (it carries workflows only, no domain-skill section) AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)). Out-of-date entries silently kill discovery. +1. The skill list above (CLAUDE.md) AND the workflow list in the root `AGENTS.md` (it carries workflows only, no domain-skill section) AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)) AND the two setup tables that compress the same descriptions — `docs/prompting/overview.mdx` ("One-time setup") and `docs/quickstart.mdx`. Out-of-date entries silently kill discovery. This list is also the sync set for a **changed contract**, not just an added or renamed skill: a reworded `description:` has to be pushed to every surface or the compressed copies start asserting the opposite of the skill. 2. The scaffolded project template `packages/cli/src/templates/_shared/CLAUDE.md` + `AGENTS.md` — written into every `hyperframes init` project, so a stale entry there ships to users. The two template files must stay byte-identical. 3. If the skill changes the routing surface for "make a video" requests, also update the routing table + intent layer in `skills/hyperframes/SKILL.md` AND that workflow's entry in `skills/hyperframes/references/workflow-catalog.md` (the input/output/trigger contract the router reads before the workflow is installed) — plus its row in `references/route-briefs.md` when the route asks questions. 4. Mirror the Router / Creation workflows / Domain skills grouping across all surfaces so a skill always lives in the same column. diff --git a/README.md b/README.md index b3e8d69560..2a34005a40 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ This writes `dist/hyperframes-plugin.zip` with a `hyperframes/` root folder and | `/embedded-captions` | Adding **captions / subtitles** to an existing talking-head video (footage untouched) — verbatim rail, embedded climax behind the subject, or pure-cinematic embed. | | `/talking-head-recut` | Packaging an existing talking-head / interview / podcast video with **designed graphic overlays** — lower-thirds, data callouts, kinetic titles, pull-quotes, side panels, PiP. | | `/motion-graphics` | A short, **unnarrated, design-led motion graphic** (~under 10s) — kinetic type, stat / chart hit, logo sting, lower-third, animated tweet / headline. MP4 or transparent overlay. | -| `/music-to-video` | A **music track** (audio file, or video to pull audio from) → a **beat-synced** video — lyric, slideshow, or kinetic promo; music drives pacing. | +| `/music-to-video` | A **music track** (audio file, video to pull audio from, or one generated from a mood brief) → a **beat-synced** video — lyric, slideshow, or kinetic promo; music drives pacing. | | `/slideshow` | A **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. | | `/general-video` | **Anything else** — longer or multi-scene pieces, brand / sizzle reel, title card, static loop, freeform composition. Input- and length-agnostic fallback, and the home of companion mode (co-create with the full toolbox). | | `/remotion-to-hyperframes` | **Porting an existing Remotion** (React) composition's source to HyperFrames HTML. One-way migration, not creation. | diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index 0b7047bd86..8c60644600 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -89,7 +89,7 @@ One workflow per input shape. The router (`/hyperframes`) picks one of these for | `/embedded-captions` | Adding **captions / subtitles** to an existing talking-head video (footage untouched) — verbatim rail, embedded climax behind the subject, or pure-cinematic embed. | | `/talking-head-recut` | Packaging an existing talking-head / interview / podcast video with **designed graphic overlays** — lower-thirds, data callouts, kinetic titles, pull-quotes, side panels, PiP. | | `/motion-graphics` | A short, **unnarrated, design-led motion graphic** (~under 10s) — kinetic type, stat / chart hit, logo sting, lower-third, animated tweet / headline. MP4 or transparent overlay. | -| `/music-to-video` | A **music track** (audio file, or video to pull audio from) → a **beat-synced** video — lyric, slideshow, or kinetic promo; music drives pacing. | +| `/music-to-video` | A **music track** (audio file, video to pull audio from, or one generated from a mood brief) → a **beat-synced** video — lyric, slideshow, or kinetic promo; music drives pacing. | | `/slideshow` | A **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. | | `/general-video` | **Anything else** — longer or multi-scene pieces, brand / sizzle reel, title card, static loop, freeform composition. Input- and length-agnostic fallback, and the home of companion mode (co-create with the full toolbox). | | `/remotion-to-hyperframes` | **Porting an existing Remotion** (React) composition's source to HyperFrames HTML. One-way migration, not creation. | @@ -111,7 +111,7 @@ Atomic capabilities the creation workflows compose against — pull one when you ## Source of truth -The one-line "use when" for each skill comes from its own `SKILL.md` frontmatter `description:` field in the [hyperframes repo](https://github.com/heygen-com/hyperframes/tree/main/skills). The same catalog lives in the [README's `## Skills` section](https://github.com/heygen-com/hyperframes#skills) and the repo `CLAUDE.md`; all three surfaces are kept in sync when a skill is added or renamed. +The one-line "use when" for each skill comes from its own `SKILL.md` frontmatter `description:` field in the [hyperframes repo](https://github.com/heygen-com/hyperframes/tree/main/skills). The same catalog lives in the [README's `## Skills` section](https://github.com/heygen-com/hyperframes#skills) and the repo `CLAUDE.md`. Two more surfaces compress the same descriptions and drift the same way, so they belong to the same sync set: the setup tables in the [prompting guide](/prompting/overview#one-time-setup) and the [quickstart](/quickstart). All of them are kept in sync when a skill is added, renamed, or has its contract changed. ## Next steps diff --git a/docs/prompting/overview.mdx b/docs/prompting/overview.mdx index 3f89625cf7..2635f378f6 100644 --- a/docs/prompting/overview.mdx +++ b/docs/prompting/overview.mdx @@ -60,7 +60,7 @@ The installer shows a picker. Select the **core skills** below — every project | `/embedded-captions` | An existing talking-head video → the same footage with captions / subtitles | | `/talking-head-recut` | An existing talking-head video → footage packaged with transcript-synced graphic overlays (kinetic titles, lower-thirds, PiP) | | `/motion-graphics` | A logo / stat / tweet / brief → a short (~10s) unnarrated motion graphic (kinetic type, count-up, logo sting) — MP4 or transparent overlay | -| `/music-to-video` | A music track (or a video's audio) → beat-synced video (lyric / slideshow / kinetic promo); your images optional, cut on the beat | +| `/music-to-video` | A music track — a file, a video's audio, or one generated from a mood brief → beat-synced video (lyric / slideshow / kinetic promo); your images optional, cut on the beat | | `/slideshow` | A deck outline or slides → navigable presentation with presenter mode (not a rendered MP4) | | `/remotion-to-hyperframes` | Port an existing Remotion (React) composition to HyperFrames HTML | | `/figma` | A Figma file / frame / URL → imported assets, brand tokens, and reconstructed motion | diff --git a/packages/cli/src/templates/_shared/AGENTS.md b/packages/cli/src/templates/_shared/AGENTS.md index 6b10521743..5c8126aeb2 100644 --- a/packages/cli/src/templates/_shared/AGENTS.md +++ b/packages/cli/src/templates/_shared/AGENTS.md @@ -12,7 +12,7 @@ - `/talking-head-recut` — an existing talking-head / interview / podcast video (MP4) → the same footage **packaged with designed graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath. (Plain captions/subtitles → `/embedded-captions`.) - `/pr-to-video` — a GitHub PR (URL / `owner/repo#N` / "this PR") → 30-90s code-change explainer (changelog / feature reveal / fix / refactor). - `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`. -- `/music-to-video` — a **music track** (audio file, or video to pull audio from) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid. +- `/music-to-video` — a **music track** (audio file, video to pull audio from, or one generated from a mood brief) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid. - `/slideshow` — a **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. - `/general-video` — fallback for any other video (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of **companion mode** — co-create with the full HyperFrames toolbox; the original hyperframes authoring flow, any length. diff --git a/packages/cli/src/templates/_shared/CLAUDE.md b/packages/cli/src/templates/_shared/CLAUDE.md index 6b10521743..5c8126aeb2 100644 --- a/packages/cli/src/templates/_shared/CLAUDE.md +++ b/packages/cli/src/templates/_shared/CLAUDE.md @@ -12,7 +12,7 @@ - `/talking-head-recut` — an existing talking-head / interview / podcast video (MP4) → the same footage **packaged with designed graphic overlays** (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, pip) synced to the transcript; the clip plays unchanged underneath. (Plain captions/subtitles → `/embedded-captions`.) - `/pr-to-video` — a GitHub PR (URL / `owner/repo#N` / "this PR") → 30-90s code-change explainer (changelog / feature reveal / fix / refactor). - `/motion-graphics` — a short (typically under 10s) design-led **motion graphic**, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → `/general-video`. -- `/music-to-video` — a **music track** (audio file, or video to pull audio from) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid. +- `/music-to-video` — a **music track** (audio file, video to pull audio from, or one generated from a mood brief) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid. - `/slideshow` — a **presentation / pitch deck / interactive deck** — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video. - `/general-video` — fallback for any other video (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition) and the home of **companion mode** — co-create with the full HyperFrames toolbox; the original hyperframes authoring flow, any length. diff --git a/skills-manifest.json b/skills-manifest.json index 12d4925207..fd90f93045 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -18,7 +18,7 @@ "files": 4 }, "hyperframes": { - "hash": "db16e302ad866b42", + "hash": "3a3ea01fe52e1600", "files": 17 }, "hyperframes-animation": { diff --git a/skills/hyperframes/references/routes/music-to-video.md b/skills/hyperframes/references/routes/music-to-video.md index f83a12562f..205418299a 100644 --- a/skills/hyperframes/references/routes/music-to-video.md +++ b/skills/hyperframes/references/routes/music-to-video.md @@ -1,6 +1,6 @@ # Route: music-to-video -- **Input:** A music track, or a video whose audio becomes the track, with no narration or website capture. User images or videos are optional. +- **Input:** A music track, a video whose audio becomes the track, or a track generated from a mood brief — with no narration or website capture. User images or videos are optional, so a complete video needs zero supplied assets. - **Output:** A beat-synced MP4 driven by a deterministic beat/energy map (`audiomap.json`). It may become a lyric video, slideshow, visualizer, or kinetic promo without changing pipelines. - **Triggers:** "make a video for this song", "beat-synced video", "lyric video", "music visualizer", "kinetic promo to this beat". From 579c2dcadd2190bc14ddd92b1356f1fb2fe96c56 Mon Sep 17 00:00:00 2001 From: Miao Yang Date: Fri, 31 Jul 2026 01:03:45 +0800 Subject: [PATCH 7/7] docs(claude): point the routing-surface rule at routes/, not the moved stubs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Item 3 of "Skill catalog maintenance" still sent readers to `references/workflow-catalog.md` for a workflow's input/output/trigger contract and `references/route-briefs.md` for its interview entry. Both are now "moved" stubs — the contract and the interview entry live together in `references/routes/.md`, one read per candidate route. Same failure class the previous commit fixed at item 1: a maintenance rule outliving the layout it describes. Swept the tree for other pointers at the two stubs; there are none, so this closes it rather than fixing one instance. Co-Authored-By: Claude Opus 5 (1M context) --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4d9e0728ef..638926508f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,7 +49,7 @@ When adding a new skill, or substantially renaming / repurposing an existing one 1. The skill list above (CLAUDE.md) AND the workflow list in the root `AGENTS.md` (it carries workflows only, no domain-skill section) AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)) AND the two setup tables that compress the same descriptions — `docs/prompting/overview.mdx` ("One-time setup") and `docs/quickstart.mdx`. Out-of-date entries silently kill discovery. This list is also the sync set for a **changed contract**, not just an added or renamed skill: a reworded `description:` has to be pushed to every surface or the compressed copies start asserting the opposite of the skill. 2. The scaffolded project template `packages/cli/src/templates/_shared/CLAUDE.md` + `AGENTS.md` — written into every `hyperframes init` project, so a stale entry there ships to users. The two template files must stay byte-identical. -3. If the skill changes the routing surface for "make a video" requests, also update the routing table + intent layer in `skills/hyperframes/SKILL.md` AND that workflow's entry in `skills/hyperframes/references/workflow-catalog.md` (the input/output/trigger contract the router reads before the workflow is installed) — plus its row in `references/route-briefs.md` when the route asks questions. +3. If the skill changes the routing surface for "make a video" requests, also update the routing table + intent layer in `skills/hyperframes/SKILL.md` AND that workflow's own route file, `skills/hyperframes/references/routes/.md`. One file carries both halves: the input/output/trigger contract the router reads before the workflow is installed, and its interview entry (must-haves, conditionals, deferred asks, run-shape). The older `references/workflow-catalog.md` and `references/route-briefs.md` are now "moved" stubs pointing at `routes/` — don't edit them. 4. Mirror the Router / Creation workflows / Domain skills grouping across all surfaces so a skill always lives in the same column. 5. Skill count appears in the README and CLAUDE.md intro lines ("19 AI agent skills…") — update on add/remove. The `docs/guides/skills.mdx` page and the CLI templates deliberately omit a count to avoid drift; keep them count-free.