feat(skills)!: publish seven knowledge skills aligned with Studio and retire the workflow skills

[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 160 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 (1)

• nudge-tween-px-r0-nested-z100: tracking 0.02, pressJump -, drop 0, reload 0, render 0.02, renderKey -, undo true, teleport true / tracking 0.02, pressJump -, drop 0, reload 0, render 0.02, renderKey -, undo true, teleport true / tracking 0.02, pressJump -, drop 0, reload 0, 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.

[jrusso1020]

Approved at bcc0e653a5. This resolves my request for changes at 8366864f.

Both blockers are fixed.

• Carve. carve.mjs, carve.test.mjs and lib/main-module.mjs moved into skills/media-use/audio/scripts/, byte-identical to the originals on main. audio-effects.mdx now points at <SKILL_DIR>/audio/scripts/carve.mjs and says which skill it ships with. mixing.md teaches the carve again, including --dry-run (a real flag) and the double-quoted-attribute caveat. The new test lands under skills/**/*.test.mjs, so test:skills picks it up. The two Studio comments now cite the new path.
• FRAME.md. It now says to copy the preset's six WOFF2s into assets/fonts/ and add the @font-face blocks, and that nothing stages them for you. All six files are in code-editorial/fonts/.

Should-fix items, also handled.

• storyboard-format.md now marks transition_in as a note only and says to overlap the clips yourself.
• The limitations.md:125 citation and the composition.ts comment are updated.
• The media-use host rule now sits ahead of the HeyGen setup paragraph.
• The registry sub-compositions.md comments are still there, which is fine; they were cosmetic.

7bf91c1c (new since my review). It lets the agent render when the person asks for the file or to work without stops, as well as after approval. It still renders only after its own check and snapshots pass. The three places that state the rule now agree. Nit: step 5 in hyperframes-cli/SKILL.md still opens "After approval:", which reads narrower than step 4 just above it.

generate-skill-module-copies.mjs --check is in sync at this head. Required CI is green here. I didn't install the plugin in a real agent profile.

— Rames

[miguel-heygen]

Re-reviewed current exact head 5de395a5307c76d2cfe888b8eb7494780d5476b0 (successor to requested bcc0e653a5cc2423c67124e50dc1a81c8616292e). Both original code blockers are fixed.

Audited: complete follow-up delta since my 8366864f review: carve implementation/test relocation and callers, explicit font staging, storyboard/citation/host guidance repairs, render-rule changes, and regenerated manifest. carve.mjs and its 20 tests are byte-identical to the original retained implementation; all 20 run successfully from the new path. All six preset font assets exist. Module-copy/core-skill checks and the seven-skill manifest check pass. The latest two-file successor fixes the remaining CLI step-5 approval-only wording and changes its manifest hash only.
Trusting: original review's installer/archive evidence remains applicable to unchanged implementation. No new real-client profile install, marketplace upgrade, model eval or exhaustive re-audit of all retired content. I have not independently reproduced the benchmark. The four absent frame-judge pairs are now explained (plan-only/render ×2 produced no frames); command grading still includes them, so the frame-pair denominator is 34, not 38.

skills/hyperframes-cli/SKILL.md:35, the router and preview/render reference now agree: explicit file/no-stops requests permit rendering after check and snapshots. Consider pinning this shared rule in a content-contract test as it stabilizes.

Current gate: GitHub reports mergeable:false, mergeable_state:dirty at this exact head. Only Graphite/WIP and a skipped Mintlify deployment are reported, and gh pr checks --required reports no required checks. The 79-check green result belongs to bcc0e653, not this successor. Resolve the main conflict and obtain the actual required checks on the resulting full head; I cannot give the final approval against absent current-head validation. No new code defect found in this follow-up delta.

— Magi (desktop-review)

Verdict: COMMENT
Reasoning: The requested script/font contract repairs are verified. Final approval remains pending a mergeable successor and executed current-head required CI; earlier green checks are not a substitute.

[jrusso1020]

Requesting changes at 0dc8978ee for one problem: the merge from main dropped the core-skills check from lint.

At bcc0e653, which I approved, package.json ran node scripts/check-core-skills.mjs from both lint and lint:skills. At this head, both scripts match main's, which doesn't have it. Nothing else in the repo calls check-core-skills.mjs; the only references are its unit test in test:scripts. So the size budgets and the command and path checks on the core skills no longer run in CI. That check is this PR's own guard. It still passes when run by hand at this head (✓ core skills within budget; commands and paths resolve), so the fix is to put the two && node scripts/check-core-skills.mjs lines back.

Otherwise this head is fine:

• Apart from the two package.json lines, the PR's patch matches bcc0e653 (I compared the merge base with bcc0e653, then main with this head).
• The one intended change is 5de395a5: step 5 of hyperframes-cli/SKILL.md now reads "When it is time to render (step 4):", which resolves my nit.
• generate-skill-module-copies.mjs --check is in sync. Required CI is green.

— Rames

[WaterrrForever]

Restored both && node scripts/check-core-skills.mjs lines (lint and lint:skills) in 0e82757. My conflict resolution took main's scripts wholesale and dropped them. Against main, package.json now differs only where it did at bcc0e65 (lint, lint:skills, test:scripts), and bun run lint prints the core-skills pass again.

[miguel-heygen]

Re-reviewed current exact head 0e827572f8da63cb46c140dc41bc10e263cb6508, including its main merge at 0dc8978ee. No remaining code blocker found within the reviewed scope; current-head CI is still running.

Audited: actual own-patch comparison before/after main integration, conflict resolution in package.json, complete two-line successor restoring check-core-skills.mjs to both lint commands, and previously requested script/font/render-rule repairs. All non-package own patches are unchanged across the merge. The script resolution preserves main's edit-accuracy retry test and this branch's core-skills test. Current module-copy, core-skills, seven-skill manifest checks and all 20 moved carve tests pass. Restored bun run lint:skills passes too.
Trusting: unchanged installer/archive surfaces covered in my earlier reviews; historical model evals, binary assets and exhaustive equivalence of every removed workflow. No real-client plugin/profile install, upgrade or model run was performed.

On Rames's lint concern: the previous head did execute checkCoreSkills() through scripts/check-core-skills.test.mjs:14; I confirmed the actual hosted Test (support) log and independently made that test fail with a nonexistent CLI command. However .github/workflows/ci.yml:151 excludes skill-only edits from the code job, so keeping the check in the skills lint path matters. The successor correctly restores both calls, and the probe skill text has been restored.

The 83 successful checks belong to 0dc8978ee. This exact successor has fresh pending jobs, so final approval must wait for its required CI. Original carve/font blockers are resolved; no additional product changes requested.

— Magi (desktop-review)

Verdict: COMMENT
Reasoning: The reviewed code and restored lint wiring are satisfactory. Required validation is not yet complete at the latest full head, so this is not a current-head approval.

[jrusso1020]

Approved at 2ebaf6f64e. This resolves my request for changes at 0dc8978e.

• Core-skills check: both lint and lint:skills still end in && node scripts/check-core-skills.mjs at this head, so the check runs in CI.
• The main merge: 2ebaf6f64e merges main, which brings in #5654 and #5657. Apart from skills-manifest.json, the PR's diff against its merge base is line-for-line the same as at 0e827572f8, and that is the same 881 files. So outside the manifest, this is the code I reviewed.
• The manifest: it is generated, and "Skills: manifest in sync" passes at this head.

All CI is green at this head, with nothing pending or failing. That includes the Windows test and render jobs.

— Rames

[miguel-heygen]

Approved exact head 2ebaf6f64e308578f41575cab3e4df8687d63492, completing my previous CI-pending review5538278786. No remaining blocker within the reviewed scope.

Audited: main-merge resolution and current own patch against merge base cea8aa8a. Added/deleted lines match the previously reviewed 0e827572f patch after excluding generated manifest hashes; the remaining diff is surrounding context from main. Both package.json lint commands retain node scripts/check-core-skills.mjs, and the support-test wiring remains intact. The exact current source regenerates the committed seven-skill manifest. Direct core-skills validation and 25 core-guard/moved-carve tests pass without installing dependencies.

Original deleted-script/font pointers and render-rule fixes remain present. My earlier installer/archive/migration review evidence applies to the unchanged own patch. Trusting: historical model evals and unchanged installer/client integration surfaces; no real Claude/Cursor/Codex profile install or upgrade, live agent, native Desktop, or exhaustive quality eval was performed.

Verified current-head CI: 83 successful, 2 skipped, none failing or pending. Read executed skills lint/manifest logs and verified their workflow run's head SHA matches this review. The Windows rerun is green; this does not certify absence of timing variability. No worktree/install/owned background process, merge, enqueue, release or deployment.

Verdict: APPROVE
Reasoning: The merge preserves the reviewed fixes and required lint wiring, the generated manifest matches source, and current-head validation is complete.

— Magi (desktop-review)