[WaterrrForever]

What

The published skill pack goes from 21 skills to 7, the same seven the desktop app's Studio already runs: hyperframes, hyperframes-cli, hyperframes-registry, media-use, figma, slideshow, remotion-to-hyperframes. Every skill carries knowledge an agent cannot infer and no process.

	Before	After
Published skills	21	7
Descriptions listed on every turn	10.9 KB	2.2 KB
hyperframes entry, read on every video	21.8 KB	6.7 KB
All seven entries	470 KB for 21	39 KB
skills/ on disk	about 18 MB	3.9 MB

1. hyperframes holds:

   • the render contract;
   • how to keep a project editable in Studio;
   • the terminal work loop: timeline → history → edit → check → snapshot the changed moments → preview before render;
   • the desktop-app hand-off.

   Its references are Studio's format, runtimes, motion (with the craft measured from shipped films), look and captions, plus:

   • film.md: measured facts from the retired workflows;
   • overlays.md: talking-head card geometry;
   • storyboard.md: the board page from chore(skills): storyboards are a board of stills with one page format #5599.

   The 13 frame presets move to assets/.

2. media-use shows each need with a HeyGen route beside a free local route. HeyGen: heygen auth login --oauth carries a free allowance, an API key bills credits, plus video-agent, avatar, clone, lipsync, translate and clipping. Free with no account: Kokoro TTS, Parakeet/whisper, background removal, the 19 bundled SFX, MusicGen and logos. mixing.md and local.md come from Studio.

3. hyperframes-cli and hyperframes-registry are slimmed (24.8 → 6.9 KB and 9.9 → 4.3 KB). Their detail moved whole into references.

4. slideshow, figma and remotion-to-hyperframes are slimmed (33.5 → 4.9 KB, 18.2 → 6.2 KB and 11.0 → 4.9 KB). Each keeps what only it holds:

   • slideshow: present and hand-off;
   • figma: the motion helpers, the 15 dB verify gate, storyboard decoding and the usage beacons;
   • remotion-to-hyperframes: the Remotion lint, the SSIM check and the API map.

5. Retired: the 8 workflow skills (product-launch-video, faceless-explainer, pr-to-video, general-video, motion-graphics, music-to-video, embedded-captions, talking-head-recut), the 6 domain skills folded earlier (hyperframes-core, -animation, -keyframes, -creative, -studio, -audio), and the router's intent interview, briefs, pitch and review loops, and frame-worker dispatch.

   • npx hyperframes skills update removes the 14 retired skills from existing installs (RETIRED_SKILLS).
   • skills update <retired name> says where that knowledge now lives instead of installing it.
   • Two scripts with no CLI equivalent move to skills/hyperframes/scripts/: bake-basemap.mjs, and locate.mjs (grid image location).

Why

Strong coding agents plan, sequence and check their own work; what they lack are private facts. The same restructure for Studio (hyperframes-internal#3731) raised tool and CLI correctness from 5% to 83%. This PR brings it to terminal agents, measured on the same kind of run below.

Related work

• Refs hyperframes-internal#3731 (Studio skills) and hyperframes-internal#4142 (the Studio skills carry the storyboard recipe).
• Refs chore(skills): storyboards are a board of stills with one page format #5599 (one storyboard format) and feat(cli,skills): tell the agent to take the person to the desktop app #5610 (desktop-app hand-off wording, kept in a shorter form).

How

• Moves used git mv. A script recomputed every relative path and skill-name reference across skills, docs, the CLI and tests. lint-skills reports no unresolved cross-reference.
• Budget check. scripts/check-core-skills.mjs runs in lint and holds each entry and description to budget. It also checks every taught npx hyperframes <command> against cli.ts, and every path against its skill folder. The seven entries are exempt from oxfmt, whose table padding added about 1.5 KB per entry on every read.
• Catalog surfaces were updated together: CLAUDE.md, AGENTS.md, README.md, the docs pages, both init templates (still byte-identical), the marketplace core-skills list and FALLBACK_CORE_SKILLS. The init template now asks for a snapshot of the changed moments after check.
• CLI size budget raised (@hyperframes/cli, packed 7,902,966 / unpacked 23,722,874, measured plus 5%). The CLI bundles skills/hyperframes, which now carries the 13 frame presets (fonts, caption skins and showcases) that lived in hyperframes-creative.
• Content tests moved to the files the knowledge now lives in. Assertions that pinned retired process or workflow wording were removed; each is listed in commit cbdc00500.
• Generated catalog pages and docs/docs.json stay as on main. Renaming the "Workflows" nav group needs a PR with no catalog changes, so it comes separately.

Test plan

• bun run lint: includes lint-skills, check-core-skills and the skill mirror. format:check, comment citations and fallow audit --base origin/main are clean.

• test:scripts 749 pass. test:skills 547 pass. The CLI tests for skills, the manifest, the mirror, core and figma content, init and capture: 678 pass. Plus the core storyboard and swapScenes tests, the engine live-map warning, the Studio safe margins and the edit prompt.

• gen-skills-manifest --check: in sync (7 skills).

• Plugin package: bun run package:agent-plugin builds a 2,139,275-byte archive holding exactly the 7 skills, with no nested SKILL.md. package-agent-plugin.test.mjs passes 3/3. claude plugin validate . passes, with one warning that is already on main (a root CLAUDE.md is not loaded as plugin context).

• Terminal eval.

  • Setup: claude -p with the repo as a plugin and no host app, the same pinned CLI on both sides (0.8.161), Sonnet 5.5 at medium effort, 19 cases × 2 repeats, and an Opus blind judge on frames only. Each fixture project carries the CLAUDE.md its own side's init writes.
  • Compared: main 76222e4 against this branch at b65388b and at e05215d (adds Studio's "snapshot the moments you changed" sentence). The main side was run once and reused.

  	main	b65388b	e05215d
  G1: correct HyperFrames (check, contract, case asserts)	74%	84%	82%
  G3: CLI and tools used right	13%	34%	79%
  Both	11%	32%	71%
  Required steps (check and snapshot after the last edit, …)	65%	69%	93%
  Rule breaks (e.g. skills update inside a plugin)	10	2	2
  Cost per run	$0.117	$0.092	$0.089
  Seconds per run	85	89	75
  Blind judge, 1–10 (same old runs, judged again each time)	6.86 / 6.94	7.21	7.11
  Pairwise vs main		13 wins, 1 loss, 20 ties	8 wins, 7 losses, 19 ties

  The judge sees only frames and swings between runs: the identical main runs went from 1 win to 7. The pass rates are graded from files and commands and are the steadier signal. The misses that remain on this branch, mostly shared with main, are beat sync without beats, check still failing on the grade case, and one caption hard kill.

• Not exercised: installing the archive in isolated Claude, Cursor and Codex profiles, the N → N+1 marketplace upgrade, and migration from core-skills@hyperframes on a real client. These are only covered by unit tests of skills update pruning.

Follow-ups (separate PRs)

• Rename the docs "Workflows" nav group.
• Unpublish the retired skills' last versions on ClawHub. The sync stops republishing them.
• check treats a <video> cutout as opaque, so it can't measure text placed behind a speaker.
• The skills-manifest hash also counts untracked files such as __pycache__.

No visible change

Studio and player change only in text no screen renders. domEditingAgentPrompt.ts changes one line of the prompt Studio hands an agent: the skill path it names for timeline edits. projectProvenance.ts changes one example in a code comment. Neither path draws anything, and the rest of the Studio diff is tests. That is 4 lines in non-test files under packages/studio, with no .tsx, .css or .html file there or under packages/player.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Oct 16, 2026, 1:55 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

Edit accuracy: accurate 271 (base branch 271), smooth 155 of those

The gate passes.
Smoothness is reported in the artifact, not gated. A case fails only if it fails 2 of 3 runs.

Quarantined, measured but not gated (0)

Unstable (2)

• seqplainkeys-none-center-r0-root-z100: tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo false, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true / tracking 0.06, pressJump 0, drop 0, reload 0, render 0.03, renderKey -, undo true, teleport true
• seqheldtwice-tlhold-px-r0-root-z100: tracking 0.41, pressJump 60.41, drop 0.35, reload 0.35, render 0.02, renderKey -, undo true, teleport true / tracking 0.08, pressJump 0.11, drop 0.35, reload 0.35, render 0.02, renderKey -, undo true, teleport true / tracking 0.08, pressJump 0.11, drop 0.35, reload 0.35, render 0.02, renderKey -, undo true, teleport true

[jrusso1020]

Reviewed at 8366864f1b7b482bb53a64d361fdb0f4f252a7c1. The direction holds up and most of this checks out (details below). I'm requesting changes for two places that still send people to scripts this PR deletes. Both are small fixes.

Blocking: live instructions that point at deleted scripts

1. docs/reference/audio-effects.mdx:449 (and the prose at :33) tells users to run node <SKILL_DIR>/scripts/carve.mjs --comp index.html. carve.mjs only ever existed at skills/hyperframes-audio/scripts/carve.mjs, which this PR deletes, and nothing replaces it. So the documented command now fails. docs/prompting/audio-effects.mdx:57 still tells people to ask the agent to "carve it", and no kept skill teaches data-fx-carve any more: there are no hits under skills/, and media-use/references/mixing.md:67 only points at Studio's carve. Either drop the CLI section and send people to Studio's carve, or carry the script into media-use. Two Studio comments also cite scripts/carve.mjs (audioFxTelemetry.ts:201, useFxChainObserved.ts:19).
2. skills/hyperframes/assets/frame-presets/code-editorial/FRAME.md:274 says "build-frame.mjs stages weights 400 + 700 into assets/fonts/ and appends the exact @font-face block". That script lived only in the retired workflows. An agent using this preset will assume its fonts are staged and won't add them. The render then falls back to Google Fonts or a substitute, and look.md:23 says the opposite. Rewording it to "copy the bundled WOFF2s into assets/fonts/ and add the @font-face block" is enough.

Should fix (not blocking)

• skills/hyperframes/references/storyboard-format.md:31,75,86 still documents transition_in (crossfade, cut, wipe). The transitions.mjs inject step that acted on it is gone, with all three copies deleted together with transitionsContract.test.ts. Now nothing acts on the key, and no kept doc tells the agent to build the crossfade overlap itself. Either say that, or drop the key.
• skills/remotion-to-hyperframes/references/limitations.md:125 still says "see creator-editing-recipes.md", a hyperframes-core file. You fixed the same citation at line 35 but not this one.
• Registry comments still cite sub-compositions.md "Pitfall 1/2/3" and "Per-Instance Variables" after their headers moved to format.md, which has no Pitfall sections. Cosmetic: device-frame-stage.html:63,80,264,349, overwhelm-surround.html:46,225, toggle-flip.html:60,240,255, touch-indicator.html:75,91,240, touch-indicator/demo.html:400, packages/lint/src/rules/composition.ts:695. The generated docs/catalog/components/*.mdx pages that cite hyperframes-core are fine as they are: check-catalog-source-pr forbids editing them here, and the catalog bot regenerates them.
• @hyperframes/core/storyboard (parseStoryboard, editStoryboard) has no in-repo consumer left, since its only users were the three vendored storyboard.mjs copies. Nothing breaks, but it now matters only if something outside the repo imports it.
• ClawHub: clawhub sync --all doesn't unpublish, so the retired skills' last versions stay listed there.

Checked and fine

• skills update pruning. Retired workflow names (generic names such as general-video) are removed only when the skills lock attributes them to heygen-com/hyperframes; leaves a same-named workflow bundle alone when no lock attributes it to us covers that. Removal goes through skills remove in the scope detection read from, and the prune uses canonical: true, so a repo checkout's own manifest can't widen it. The one deliberate exception is the six retired hyperframes-* domain skills: they are removed by name when the bundle is on disk with no lock entry. That departs from manifestCoversSkill's "unknown provenance must fail safe" rule. The prefix makes the call reasonable and the run prints each name it removes, but a user who hand-copied and edited hyperframes-core into ~/.claude/skills loses it. A line in the release notes would cover that.
• Upgrade path. Naming a retired skill in skills update <name> prints where its knowledge went rather than failing. FALLBACK_CORE_SKILLS is now the four kept core skills. The legacy core-skills marketplace entry lists only kept skills, and plugin installs skip skills update entirely (plugin-installation.md).
• References. Every markdown link and every backticked references/, scripts/ or assets/ path in the 95 .md files under the seven kept skills resolves. Plugin manifests, skills-manifest.json, README/AGENTS/CLAUDE.md, the CLI templates, the docs nav (608 pages) and the CI path filters name no retired skill. generate-skill-module-copies.mjs --check is in sync, and check-core-skills.mjs passes.
• media-use. The OAuth free-allowance wording matches what main already said. I haven't verified it against the backend. The host rule (HEYGEN_API_BASE set means the host pays, so don't ask for a sign-in) is kept. It sits after the HeyGen setup paragraph, though; putting it first would stop an agent from reading the sign-in steps before it learns they don't apply.
• Sizes. skills/hyperframes/SKILL.md goes from 21.1 KB on main to 6.8 KB here, which matches the description.
• The eval. I can't reproduce it from here. The 13 wins and 1 loss come with 20 ties out of 34, so the judge found no difference in most cases; the hard counts (rule breaks 10 → 2, CLI used right 13% → 34%) carry more of the case.

CI

At this head, the required regression failed only in shard-10, where sub-composition-video couldn't launch Chrome (Failed to launch the browser process, dbus). Tests on windows-latest failed in checkDeadline.process.test.ts ("managed launches own distinct profiles…"), which this PR doesn't touch. Both look like runner flakes and were re-running when I posted. I didn't install the plugin archive in a real Claude, Cursor or Codex profile, and the PR says it didn't either.

— Rames

[miguel-heygen]

Reviewed exact head 8366864f1b7b482bb53a64d361fdb0f4f252a7c1. The seven-skill inventory, terminal check → changed-frame snapshot → preview loop, and scoped migration implementation check out within the scope below.

Audited: retained entry points and folded contract references; skills.ts/skillsManifest.ts retirement, attribution and scope paths; manifests/plugin packagers and launcher paths; installer/content tests; changed production call-site/reference strings. Independently built both agent and Codex ZIPs: each has exactly the seven intended skill entries, the launcher and storyboard recipe, with no retired skill directories. Local results: 142 installer/content tests, 547 skill tests, eight script tests, and skill lint/budget pass. Hosted manifest job actually reports seven skills in sync.
Trusting: historical benchmark/corpus judgments, binary preset assets and exhaustive semantic equivalence of every deleted workflow. No isolated Claude/Cursor/Codex profile install, real marketplace/core-skills upgrade, model behavior run or paid call was performed.

Blockers — +1 to Rames's current review: I independently checked both surviving instructions against the final tree:

• docs/reference/audio-effects.mdx:449 still teaches node <SKILL_DIR>/scripts/carve.mjs --comp index.html, but no carve.mjs remains or is moved into a kept skill. This is an executable documented path that now fails. Retire that CLI instruction in favor of the actual Studio path, or preserve a working implementation; update the associated instructions at docs/reference/audio-effects.mdx:33 and docs/prompting/audio-effects.mdx:57 together.
• skills/hyperframes/assets/frame-presets/code-editorial/FRAME.md:274 promises automatic font staging by the removed build-frame.mjs. The retained look.md instead requires copying the preset and staging non-bundled fonts explicitly. Make the preset's instructions self-contained rather than promising the deleted staging step.

Evidence note, non-blocking: the PR body's terminal benchmark compares older b65388b, before the final snapshot instruction. The 19 × 2 setup has 38 runs, while 13 wins + 1 loss + 20 ties accounts for 34 pairs. Explain the four omitted pairs and link the raw per-case results when reporting the pending rerun; I have not independently reproduced those gains.

CI: latest required snapshot still has regression and Windows tests failed with reruns underway. I read the actual failures: Chrome process signal 11 during sub-composition-video, and checkDeadline.process.test.ts receiving a navigation timeout rather than its expected script deadline. These are not demonstrated skill defects; I have not base-reproduced them. Required gates still need a clean result, not an inferred flake waiver.

— Magi (desktop-review)

Verdict: REQUEST CHANGES
Reasoning: The installer/package checks support the intended migration, but live instructions still depend on scripts deleted by this PR. Correct those contracts and complete current-head required CI before approval.

[jerrai-bot-heygen]

Changes requested at exact 866babcb70345d815e0c72b638efac9f59b6a1bb. The merge-forward introduced a detectable loss in check craft coverage: craft frames now share the overlap grid's 180-time cap rather than their prior 8-fps/up-to-600 grid, so a short readable line in a 60s film can fall between every sample and escape line_unread. The inline review gives a specific 10.1–10.3s witness and a discriminating regression request. This finding is from first-hand comparison of the merge's first parent, new head, craft candidate builder and the 20s test—not an exhaustive review of all 916 changed files. The GitHub changed-file API surfaced only the first 100 of 916 files; I inspected its metadata and the focused patch, not every patch, and rely on earlier exact-head peer reviews only for unchanged surfaces. Seven retained skill directory names and the manifest remain, and the new-head deletion, skills lint/mirror and manifest jobs executed green. The new-head Comments job executed failed: its citation checker treats project-output REVIEW.md/STORYLINES.md as nonexistent repository paths, and its comment-share ratchet reports increases in touched files; resolve or explicitly reclassify these checks before landing. Other required jobs were still in progress at review time. Auto-merge was armed by the author, so approval could enqueue a merge; this request changes and grants neither merge nor publication. I did not run local tests, install a client, merge, or release. — Jerrai

[jerrai-bot-heygen]

The merge reuses the overlap grid as the only source of craft frames. That grid is capped at OVERLAP_MAX_SAMPLES - OVERLAP_HOLD_PROBES = 180 times (lines 597–619), whereas the pre-merge craft pass sampled the 8-fps grid up to 600. For a 60s film with no interior clip edges, merged shiftedTimes is uniform every ~0.335s: it seeks at 10.056 and 10.391 but not during a seven-word line visible at 10.1–10.3. Before this merge the .125s grid caught it at 10.125/10.25. trackBlocks builds candidates only from sampled frames, so line_unread disappears entirely; refinement cannot recover an unseen line. The new 20s craft test remains below this 180-sample ceiling. Please preserve the fine craft sampling budget independently of the capped overlap grid (or otherwise prove equivalent coverage), with a >23s brief-line regression that fails this merge and passes the intended resolution.

[jrusso1020]

Reviewed exact successor 866babcb70345d815e0c72b638efac9f59b6a1bb, including the deletion-guard follow-up to requested 5c16c421d and all prior blocking reviews.

The seven-skill inventory and scoped migration are coherent. Both lint commands retain the core-skills guard; the earlier carve/font instructions are repaired. The current source regenerates the seven-skill manifest exactly. Skill lint checks 130 Markdown files and three registry snapshots without unresolved references, and the core entry budgets/command/path guard passes.

[P1 blocker] +1 to Jerrai's craft-grid finding (packages/cli/src/utils/checkPipeline.ts:686–695), independently reproduced. The merge uses denseOverlapTimes as the only craft sampling schedule, inheriting the overlap grid's 180-time cap. For 60 seconds with no internal clip edges, its neighboring samples are 10.056 and 10.391. A seven-word line shown at 10.1–10.3 is never observed, so there is no line_unread candidate to refine. The former 8-fps craft grid sampled it at 10.125 and 10.25. A fresh independent exact-source control ran the old/new grids through the unchanged craft detector: old reports the approximately 0.203-second line; current reports nothing. Preserve the separate fine craft schedule while retaining main's batched overlap collection, and add a >23-second short-line regression. The existing 20-second test stays below the cap.

Audited: all 916 changed-file metadata entries; retained entries/references, installer/manifest/mirror implementation and tests, docs/plugin inventories, previous script/font/lint repairs, merge-adjusted production and test surfaces with emphasis on check/craft/snapshot contracts. Local checks: 137 installer/mirror/command controls (command harness stubs withMeta), 20 moved-carve tests, five core-guard tests, three plugin-packager tests, manifest/skill lint/core guard, and independent sampling controls.
Trusting: exhaustive semantic equivalence of all deleted workflow knowledge, binary preset appearance, historical model/film judgments and real client upgrades. No full CLI/browser suite, marketplace install, paid call or model eval.

Measurement: independently verified the packaging count 21 → 7, and current entry text totals 39,619 bytes versus 487,120 bytes on this merge's main base. The linked HeyGenVerse numbers/films page requires sign-in here; I could not verify a claim from that private page or reproduce its quality/cost judgments. These source measurements do not certify the benchmark.

The six legacy hyperframes-* domain names can still be removed without a provenance lock, as deliberately documented and reviewed earlier; generic retired workflow names require our source attribution. The latest deletion allowlist addition matches a test inside the intentionally retired captions implementation.

Verdict: REQUEST CHANGES
Reasoning: The migration and knowledge-pack checks pass, but the merge reduces craft sampling coverage and silently misses brief unreadable text in longer films.

— hf-review

[jrusso1020]

Re-reviewed exact 6cf89bb93759f8c875c8db2c30473106a428d9b8. This resolves my craft-sampling request at 866babcb7 and corroborates the repair to Jerrai's finding.

packages/cli/src/utils/checkPipeline.ts:688 now iterates its own buildCraftSampleTimes, using 8 fps up to the prior 600-sample budget. The overlap grid, batching and hold-probe functions are unchanged. Craft still runs before the batch, preserving main's queued-span fix; range checks skip craft as before, and the actual collection excludes the film endpoint.

Parent and a fresh independent pass executed the exact sampler/collector plus the unchanged detector: the 60-second witness samples at 10.125/10.25, producing line_unread at about 10.102 with a 0.203-second reading window. Replacing the schedule with the previous overlap grid produces no finding. The new check.test.ts case exercises that scenario through runScenario; it is a discriminating regression. Additional invalid/short/long-duration controls retain ordered unique samples and the cap.

Audited: complete seven-file follow-up since 866babcb7: the craft repair/test, narrowly allowing project-generated REVIEW.md/STORYLINES.md citations, and comment trimming. Esbuild output confirms the other four production files are runtime-identical. The citation checker still resolves repository-qualified paths; its isolated tests produced 84 passes, while 19 CLI/self-check cases could not execute in the detached non-git tree. I have not counted that as a passing full checker suite.
Trusting: the unchanged inventory, installer, manifest and knowledge-migration surfaces covered in my preceding review and its 137 migration controls. No fresh exhaustive re-audit of 916 files, full CLI/browser suite, real-client upgrade or film/model benchmark. The private numbers-page limitation remains.

Miao's explicit authorization of the armed auto-merge is understood; I did not merge or enqueue anything myself. CI status is not asserted by this source review.

Verdict: APPROVE
Reasoning: The separate fine craft schedule restores the missed-line coverage without losing main's batched overlap behavior, and the remaining follow-up changes introduce no blocker.

— hf-review

[jerrai-bot-heygen]

The exact-head craft-sampling repair addresses my prior blocker. — Jerrai