Skip to content

Commit 6882293

Browse files
feat(skills)!: publish seven knowledge skills aligned with Studio and retire the workflow skills (#5651)
* refactor(skills): fold six domain skills into hyperframes and media-use guides hyperframes-core, -animation, -keyframes, -creative and -studio move to skills/hyperframes/{core,animation,keyframes,creative,studio}/, and hyperframes-audio moves to skills/media-use/mix/. Each moved SKILL.md becomes a frontmatter-free GUIDE.md so installers that scan recursively for SKILL.md no longer see them as skills; the published list goes from 21 to 15. Relative links, code paths and skill-name mentions are rewritten to the new locations, the catalog surfaces, marketplace core-skills list, fallback core set, module-copy targets and skills-manifest.json follow, and `hyperframes skills update` now removes the retired skills (RETIRED_SKILLS) when they are still installed. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(skills): slim the core entries and give media-use a HeyGen and a free path The four entries every run opens are rewritten to what an agent cannot infer: hyperframes 21.8 KB to 7.7 KB, hyperframes-cli 24.8 KB to 6.9 KB, hyperframes-registry 9.9 KB to 4.3 KB, media-use 9.7 KB to 4.9 KB. Detail moved whole into references (routing close calls and creator edits, CLI pin upgrades, catalog search tiers, CLI conventions and feedback reports). - hyperframes: state table, routing, the render contract, a terminal work loop (check, snapshot, preview before render), the desktop-app hand-off, and a table of the folded guides. - media-use: one table of HeyGen versus free local tools per need; HeyGen sign-in, credits and the CLI's video-agent, avatar, clone, lipsync, translate and clipping commands; every free path works with no account. - scripts/check-core-skills.mjs holds entries and descriptions to budget and checks every taught `npx hyperframes` command and path; runs in lint. - Core entries are exempt from the formatter: its table padding cost ~1.5 KB per entry on every run. - Content tests follow the text to its new home. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): plugin runs skip skills update; media-use explains HeyGen sign-in and TTS setup The smoke eval showed a presenter request never reaching media-use and the free voiceover failing on a missing kokoro-onnx; plugin runs also ran the skills update the plugin rules forbid. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * chore(skills): drop a committed Python bytecode file and ignore bytecode Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(skills): align the entry with the Studio skills and keep the workflows' measured facts The entry drops routing and the intent interview and carries the contract, the editable-project rules and the work loop. Studio's format, runtimes, motion, look and captions references come over for terminal use, frame presets move to assets/, media-use gains Studio's mixing and local-command references, and film.md and overlays.md keep what the workflow skills measured. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(skills)!: retire the workflow skills and folded guides; publish seven knowledge skills The skill pack now publishes exactly seven skills - hyperframes, hyperframes-cli, hyperframes-registry, media-use, figma, slideshow and remotion-to-hyperframes - carrying knowledge, not process. The eight workflow skills, the folded domain guides and the routing/interview references are deleted; their measured facts already live in the hyperframes references (format, runtimes, motion, look, captions, film, overlays) and media-use's mixing reference. - bake-basemap.mjs and locate.mjs move to skills/hyperframes/scripts/ (bake-basemap gains --help); extract-audio-data.py moves to media-use/audio/scripts/ for the caption motion reference. - skills update: the eight workflows join RETIRED_SKILLS so existing installs prune them (by lock attribution only, since their names are generic); naming a retired skill reports where its knowledge went and succeeds instead of failing as unknown. - Capture prompts point at the hyperframes skill's references/film.md; the live-map warning names the new bake-basemap path. - Content tests that pinned knowledge are retargeted to the kept references; tests of deleted workflows, scripts and process go. - Catalog surfaces, templates and docs describe the seven skills. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): resolve the local.md captions link and allow capture's output files in citations Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): regenerate the skills manifest from tracked files only The committed media-use hash included an ignored __pycache__ bytecode file present in the local checkout, so CI's clean checkout hashed differently. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(docs): restore generated catalog pages and docs navigation to main Catalog PRs commit item sources only; CI regenerates the pages from the edited registry sources. docs/docs.json is catalog navigation, so its Workflows group rename is left for a non-catalog PR. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * build(cli): raise the CLI size budget for the skill references it bundles The CLI bundles skills/hyperframes, which now carries the folded domain guides and frame presets (155 KB to 1.08 MB in git). Budgets are the CI-measured size plus 5%: packed 7526634, unpacked 22593213. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * test: keep repo-sweep guards meaningful after the workflow skills left The last shell ffprobe caller and most root index.html examples lived in retired skills. The shell detector is now pinned on a literal command line, and the structure-rule sweep needs more than 5 roots (11 remain) rather than 30. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(skills): slim figma, slideshow and remotion to the Studio shape; restore the storyboard board slideshow 33.5 KB to 4.9, figma 18.2 to 6.2, remotion-to-hyperframes 11.0 to 4.9, each keeping the facts only it holds (the figma motion helpers, verify gate, storyboard decoding and usage beacons; present and hand-off; the Remotion lint, SSIM check and API map). The board page format from the storyboard recipe comes back as hyperframes/references/storyboard.md: the desktop app's Storyboard tab reads boards/storyboard.html by its frame, title and time classes. The entry and the init template now say to snapshot the moments an edit changed before replying, which the terminal eval found skipped in 22 of 38 runs. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): manifest without local bytecode; Studio's edit prompt names kept files Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): render when the person asks for the file or for no stops, not only after approval Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): keep the voiceover carve in media-use; presets stage their own fonts Review follow-ups on #5651: - carve.mjs and its tests move to skills/media-use/audio/scripts; the audio docs, mixing.md and two Studio comments point there. - code-editorial's FRAME.md says to copy its bundled WOFF2s and add the @font-face blocks, instead of promising the retired build-frame.mjs. - media-use states the host rule before the HeyGen sign-in steps. - storyboard-format marks transition_in as a note the agent builds itself. - Two stale citations (creator-editing-recipes.md, sub-compositions.md). Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * chore(skills): regenerate the manifest without local bytecode Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): the CLI render step follows step 4's rule, not approval alone Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(ci): run the core-skills check from lint again after the main merge Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(skills): films that tell a story start from three storylines; maps use real imagery Opus 5.5 arm D read motion.md and applied it, but its launch film was a feature list (pain, three feature cards, proof, logo): film.md left story to the model. And the map case never opened film.md, so it drew Natural Earth outlines instead of baking satellite tiles. - references/story.md: the generic half of Studio's moment-film story and craft (one thing, three storylines with world and device, the hook, beats, worlds, copy, brand, tells of a generated film). The person picks a storyline, or the agent takes its recommendation when asked for the file or for no stops. - The entry's work loop names the storyline step for films over ~15 s; the references table routes stories to story.md and maps to film.md. - film.md points at story.md and gives maps and real places a section. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): story.md follows the entry: no voiceover unless asked Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): bake-basemap starts from a globe and stops waiting out its idle timeout The Opus 5.5 map run spent 13 of its 38 minutes on parallel bakes that stalled and 15 more recording 300 frames, after rewriting the script because it could only start on a flat map. - PROJECTION=globe with a seeded starfield and atmosphere, and FROM/PAN to turn the globe to CENTER before the dive. - Each frame polls for loaded tiles instead of waiting for an "idle" event that had often already fired: 30 frames went from 198-219 s to 10-13 s locally with byte-identical frames. - Progress prints seconds a frame and minutes left; film.md shows the globe call and says to run one bake at a time. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): render in the foreground; wait on a detached render's log, never pgrep -f Both Opus 5.5 explainer runs started a detached render, then waited with `until ! pgrep -f "hyperframes render"`, which matches its own loop: each render took 88-117 s and the wait sat for the tool's full 10 minutes. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(skills): route each kind of film; storylines carry look and sound; add review and sound The entry routes by request (launch, explainer, music, data, vertical, 3D, character) to a self-contained file under references/types/, and a film over ~15 s now gets music and sounds on its visible actions unless the person asked for silence. Each storyline names its look and its sound, so picking one picks both; STORYBOARD.md frames carry `reads` and `sound`. review.md is the whole-film pass: the check warnings, the review sheets, seven questions to look for, P0/P1/P2 notes and REVIEW.md. motion.md gains eases by role, six title entrances, a reading-time rule and nine measured transitions; look.md a design plan before the first scene, with presets kept for decks and named picks. story.md adds the second default that generated design falls into, with what to do instead. The blank template and format.md no longer teach the fade-and-slide-up entrance on a dark canvas. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(cli): check warns on unread lines, dead stretches, small type, empty frame 0 and silence A coding agent cannot watch its film, so check now measures what a viewer notices over time. A new `craft` section holds warnings only (exit 0 unless --strict), sampled on the dense 8 fps grid the overlap pass already seeks, skipped for --range checks: - line_unread: a reading-size line (>= 30 px tall at 1080) on screen under 0.4 s for 1-2 words, else under 3/4 of 0.5 s + 0.3 s a word; the film's last line needs 2 s. Short lines are re-measured between samples to ~0.01 s before judging. Captions-track and data-layout-ignore text are exempt. - dead_stretch: more than 3 s where the keepsMoving liveness signature does not change, outside the final 3 s and any data-hold element; quiet when sweep_static fires or a whole-composition keepsMoving assertion owns the limit. - text_below_floor: text under 2.6% of the short side (28 px on 1080) held 0.5 s, one finding per file listing every element. - first_frame_empty: frame 0 paints only the background. - film_silent: over 15 s with no unmuted audio or audible video. Each message names the fix and the skill reference to read. keepsMoving now also leaves the film's last 3 s (a still end card) out of its static runs, so the two agree. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(cli): snapshot --review captures a beat sheet, seam strips and a phone sheet snapshot --review picks the frames that show a film over time instead of evenly spaced ones, in the same single browser session: - review-beats.jpg: one settled frame per scene at its start + 0.3 s, plus one per timed data-beat="name" element, labelled time and id. Scenes are the composition's top-level timed clips and sub-composition hosts, read like `timeline` reads rows (captions and audio excluded) and timed by the runtime's start resolver over the live page. - review-seam-NN.jpg: frames at -0.2, -0.1, 0, +0.1, +0.2 s around every cut (each scene start, and any scene end no scene starts at). - review-phone.jpg: the beat frames at 360 px wide. --composition scopes the review to one sub-composition; with fewer than two scenes the beats spread evenly and a note says so. snapshot also gains --json: one envelope with every frame's path and time and, under --review, the scenes, beats and seams behind the sheets; progress moves to stderr. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(cli): craft warnings stay out of --strict; a hold gets a real next action, not a caret Craft findings (unread lines, dead stretches, small type, an empty first frame, silence) are judgment calls a film may break on purpose, so --strict keeps gating defects only. The check reference no longer suggests a blinking caret to keep a still frame moving. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(cli): review spreads beats when every scene starts together; map credits skip the type floor A map film whose basemap and overlay both start at 0 s got one beat frame; the even spread now keys on distinct scene starts. film.md tells agents to mark the imagery credit data-layout-ignore and back it, since the new type floor flagged it on the first real run. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(cli): review frames each scene at its middle too, not only 0.3 s in On the first real explainer, 0.3 s into a scene showed a bare colour field before its title entered. Each scene longer than about a second and a half now adds a frame at its middle, so the sheet shows what the scene builds. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * feat(skills): a film is built from a numeric SPEC.md, with defaults banned by name and a look test Studied in full: flxrnc's Motion Lab (vague vs directed prompt), 0xMovez's course, EianLu's riso skill, agentchengfeng's style samples and the two Opus 5.5 guides. Their common point: adjectives are where the default look lives, so the agent now writes SPEC.md before any scene (GOAL, OUTPUT, TIME, LOOK, MOTION, SHOTS, BANNED, QA), with a number for every adjective. spec.md bans the defaults by name, unless the brand or reference uses them (a dark void with small things floating, glow and particles, the cream-serif-mono-label look, fade-and-slide-up, corner brackets), and grows that list after the first render. Each storyline gets a 3 s test of its hero shot before the pick; a look is written as the rules of one medium. Composition numbers: the hero fills 40% of the frame, one hero move per shot, the shot's information in within 2.5 s then a held poster. motion.md adds springs by damping ratio, shorter exits, overlap, stagger and the beat grid; review.md reviews as a harsh director and grows BANNED; vertical.md takes the riso skill's measured safe band; explainer.md the shapes of information. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): story before look; every object reads as itself; posters only for info cards The first spec-driven C02 swapped the dark default for a flat Swiss poster, and the story went with it: two black bars nobody read as mirrors, slogans instead of cause and effect, a storyline picked for its picture. The spec now serves the story: a storyline is picked for the story a stranger would follow, the look test asks first whether a stranger understands what they see, and SPEC.md gains an OBJECTS line giving each thing the material and details that make it read without a label. The 2.5 s held-poster rule is limited to information cards; in a story film every shot causes the next. Explainers start from a person or situation the viewer knows. Review names every object as a stranger would and treats one that needs explaining as a P0. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(skills): storylines are three films in words, each with a device and a form The three storylines are pitched as text and the person picks from them; nothing is built for a storyline before the pick, so the 3 s hero-shot look test is gone. Ideas pair a device with a form, five or more first, keeping the three that differ most, and the one stop states the rest in an assumption line that names every paid item beside its free option. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * ci: list main's new embedded-captions hf-cli test among the retired workflow files The merge with main removed it with the rest of the retired skill, and the deletion guard rejects any removal it has not been told about. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(core): keep the audio preset comment within core's size budget The comment's new citation to media-use's mixing reference made the published package 14 bytes larger than its budget, which sits at main's exact size. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(cli): craft keeps its own 8 fps grid; comments back within the checks Review on #5651 found that the merge moved craft onto the overlap pass's times, which main caps at 180, so a brief line in a long film fell between samples and line_unread missed it. Craft now builds its own grid at 8 fps up to 600 samples, as before the merge, and a 60 s film with a line shown for 0.2 s pins it. The Comments check passes again: REVIEW.md and STORYLINES.md join the files a skill writes into a project, the comment lines this branch added come back under each file's share at the merge-base, and the audio preset comment drops a word the check reads as history. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 207c8a4 commit 6882293

916 files changed

Lines changed: 5839 additions & 97685 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/captions-overlay/SKILL.md‎

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
---
22
name: captions-overlay
3-
description: Overlay doctrine for the embedded-captions workflow — the caption MODEL (drop / rail / embed) and the rule that captions are an OVERLAY composited on top of the film, never a reserved bottom band you shift content up to avoid. Load when adding captions/subtitles to a talking-head or launch video, when deciding whether a phrase should be dropped, ride the verbatim rail, or be promoted to a scarce embedded climax, when laying out a composition that will carry captions (do NOT reserve a keep-out band), or when centering a composition on the true frame center under captions. Quotes the rail+embed model from embedded-captions and constraint #13 (captions overlay, keep-out band retired) from the product-launch-video scene agent. Applies ON TOP of embedded-captions.
3+
description: Overlay doctrine for captions in HyperFrames videos — the caption MODEL (drop / rail / embed) and the rule that captions are an OVERLAY composited on top of the film, never a reserved bottom band you shift content up to avoid. Load when adding captions/subtitles to a talking-head or launch video, when deciding whether a phrase should be dropped, ride the verbatim rail, or be promoted to a scarce embedded climax, when laying out a composition that will carry captions (do NOT reserve a keep-out band), or when centering a composition on the true frame center under captions. Applies ON TOP of the `/hyperframes` skill's references/captions.md.
44
metadata:
55
internal: true
66
---
77

88
# Captions Overlay Doctrine
99

10-
> **Overlay doctrine — supplements the upstream `embedded-captions` skill. Applies ON TOP of it; do not expect it folded into the upstream skill.**
10+
> **Overlay doctrine — supplements the upstream `/hyperframes` skill's `references/captions.md`. Applies ON TOP of it; do not expect it folded into the upstream skill.**
1111
1212
Two ideas combine here. First, the **caption model** — every spoken phrase is `drop`,
1313
`rail`, or `embed`, and embed is the scarce earned peak, not the default. Second, the
@@ -19,7 +19,7 @@ frame and centers on the true vertical center.
1919

2020
## The caption model — drop / rail / embed
2121

22-
Every spoken phrase is one of three things (verbatim from `embedded-captions`):
22+
Every spoken phrase is one of three things:
2323

2424
| | What | How it's shown |
2525
| --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -31,15 +31,13 @@ Every spoken phrase is one of three things (verbatim from `embedded-captions`):
3131
never two adjacent/co-visible, spaced ≥ a beat apart. A short clip → usually one embed;
3232
a long explainer → ~one per section. Embedding every word is the common mistake.
3333

34-
This is the **Standard** mode shape (rail = the verbatim lower-third; embed = the climax
35-
composited behind the subject). **Cinematic** mode drops the rail and makes everything
36-
embed-style — use it only for pure-cinematic asks, never for explainer / voiceover where
37-
the words must read.
34+
This is the default shape (rail = the verbatim lower-third; embed = the climax
35+
composited behind the subject). A pure-cinematic treatment drops the rail and makes
36+
everything embed-style — use it only for pure-cinematic asks, never for explainer /
37+
voiceover where the words must read.
3838

3939
### Rail-first, embed-scarce (the load-bearing rules)
4040

41-
Quoted from the `embedded-captions` non-negotiables:
42-
4341
- **Rail-first for talking-head / explainer.** Don't embed the whole transcript — most
4442
text is the rail; embed only peaks. Embedding everything is the default mistake.
4543
- **Embed is scarce + spaced.** ≤1 embed per sentence/beat, never two adjacent or
@@ -48,11 +46,10 @@ Quoted from the `embedded-captions` non-negotiables:
4846

4947
## The overlay law — captions are NOT a reserved band
5048

51-
In a generated launch composition, when captions are enabled, finalize composites a
52-
**small, minimal word-by-word caption line** as an overlay layer ON TOP of the whole
53-
film (a single text line, bottom-centered, roughly the bottom ~5-8% of canvas height).
54-
It is an overlay, not a reserved zone (verbatim from constraint #13 of the
55-
product-launch-video scene agent):
49+
In a composed video with captions enabled, the caption line is a **small, minimal
50+
word-by-word line** composited as an overlay layer ON TOP of the whole film (a single
51+
text line, bottom-centered, roughly the bottom ~5-8% of canvas height). It is an
52+
overlay, not a reserved zone:
5653

5754
- **Center the composition on the TRUE vertical center — y = H / 2** (landscape 540,
5855
portrait 960). Do not shift content up to "make room" for captions; a composition
@@ -64,7 +61,7 @@ product-launch-video scene agent):
6461
line sits — the overlay would fight it. Large imagery / cards / ambient content under
6562
the captions is fine; the caption skin is designed to read over content.
6663
- There is no machine keep-out gate (the old `captions.mjs keepout` check is retired).
67-
Finalize snapshot QA judges caption-over-content legibility visually.
64+
Snapshot review judges caption-over-content legibility visually.
6865

6966
**When captions are disabled:** identical positioning freedom — the overlay simply
7067
doesn't exist.
@@ -74,8 +71,8 @@ doesn't exist.
7471
The model says the rail rides **in front** and an embed is a rare word composited
7572
**behind the subject** — both are layers added to footage that ships untouched. The
7673
overlay law says the caption line is a layer composited **on top** of the whole film,
77-
not a band carved out of the layout. So in both the captioning pipeline and the
78-
launch-video pipeline, captions are an overlay you add, not a zone you reserve:
74+
not a band carved out of the layout. So whether captions go over footage or over a
75+
composed film, they are an overlay you add, not a zone you reserve:
7976

8077
- Keep the full frame; center on true center; let content run to the edges.
8178
- Make the rail (or the small overlay caption line) carry the verbatim words.

‎.claude-plugin/marketplace.json‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,26 +9,20 @@
99
{
1010
"name": "hyperframes",
1111
"source": "./",
12-
"description": "Recommended: all published HyperFrames skills in one versioned bundle. Create and render videos from HTML; load workflows on demand without installing newer standalone skills.",
12+
"description": "Recommended: all published HyperFrames skills in one versioned bundle. Create and render videos from HTML: the contract, film, captions, overlays, motion and look references, the CLI, the registry, media, Figma, slideshows and Remotion ports.",
1313
"homepage": "https://hyperframes.heygen.com",
1414
"license": "Apache-2.0"
1515
},
1616
{
1717
"name": "core-skills",
1818
"source": "./",
19-
"description": "Legacy core-only installation. For release-managed bundled workflows, install hyperframes@hyperframes and then uninstall core-skills@hyperframes.",
19+
"description": "Legacy core-only installation. For the release-managed bundle of every skill, install hyperframes@hyperframes and then uninstall core-skills@hyperframes.",
2020
"homepage": "https://hyperframes.heygen.com",
2121
"license": "Apache-2.0",
2222
"skills": [
2323
"./skills/hyperframes",
24-
"./skills/hyperframes-animation",
25-
"./skills/hyperframes-audio",
2624
"./skills/hyperframes-cli",
27-
"./skills/hyperframes-core",
28-
"./skills/hyperframes-creative",
29-
"./skills/hyperframes-keyframes",
3025
"./skills/hyperframes-registry",
31-
"./skills/hyperframes-studio",
3226
"./skills/media-use"
3327
]
3428
}

‎.claude/skills/captions-overlay/SKILL.md‎

Lines changed: 14 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
---
22
name: captions-overlay
3-
description: Overlay doctrine for the embedded-captions workflow — the caption MODEL (drop / rail / embed) and the rule that captions are an OVERLAY composited on top of the film, never a reserved bottom band you shift content up to avoid. Load when adding captions/subtitles to a talking-head or launch video, when deciding whether a phrase should be dropped, ride the verbatim rail, or be promoted to a scarce embedded climax, when laying out a composition that will carry captions (do NOT reserve a keep-out band), or when centering a composition on the true frame center under captions. Quotes the rail+embed model from embedded-captions and constraint #13 (captions overlay, keep-out band retired) from the product-launch-video scene agent. Applies ON TOP of embedded-captions.
3+
description: Overlay doctrine for captions in HyperFrames videos — the caption MODEL (drop / rail / embed) and the rule that captions are an OVERLAY composited on top of the film, never a reserved bottom band you shift content up to avoid. Load when adding captions/subtitles to a talking-head or launch video, when deciding whether a phrase should be dropped, ride the verbatim rail, or be promoted to a scarce embedded climax, when laying out a composition that will carry captions (do NOT reserve a keep-out band), or when centering a composition on the true frame center under captions. Applies ON TOP of the `/hyperframes` skill's references/captions.md.
44
metadata:
55
internal: true
66
---
77

88
# Captions Overlay Doctrine
99

10-
> **Overlay doctrine — supplements the upstream `embedded-captions` skill. Applies ON TOP of it; do not expect it folded into the upstream skill.**
10+
> **Overlay doctrine — supplements the upstream `/hyperframes` skill's `references/captions.md`. Applies ON TOP of it; do not expect it folded into the upstream skill.**
1111
1212
Two ideas combine here. First, the **caption model** — every spoken phrase is `drop`,
1313
`rail`, or `embed`, and embed is the scarce earned peak, not the default. Second, the
@@ -19,7 +19,7 @@ frame and centers on the true vertical center.
1919

2020
## The caption model — drop / rail / embed
2121

22-
Every spoken phrase is one of three things (verbatim from `embedded-captions`):
22+
Every spoken phrase is one of three things:
2323

2424
| | What | How it's shown |
2525
| --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -31,15 +31,13 @@ Every spoken phrase is one of three things (verbatim from `embedded-captions`):
3131
never two adjacent/co-visible, spaced ≥ a beat apart. A short clip → usually one embed;
3232
a long explainer → ~one per section. Embedding every word is the common mistake.
3333

34-
This is the **Standard** mode shape (rail = the verbatim lower-third; embed = the climax
35-
composited behind the subject). **Cinematic** mode drops the rail and makes everything
36-
embed-style — use it only for pure-cinematic asks, never for explainer / voiceover where
37-
the words must read.
34+
This is the default shape (rail = the verbatim lower-third; embed = the climax
35+
composited behind the subject). A pure-cinematic treatment drops the rail and makes
36+
everything embed-style — use it only for pure-cinematic asks, never for explainer /
37+
voiceover where the words must read.
3838

3939
### Rail-first, embed-scarce (the load-bearing rules)
4040

41-
Quoted from the `embedded-captions` non-negotiables:
42-
4341
- **Rail-first for talking-head / explainer.** Don't embed the whole transcript — most
4442
text is the rail; embed only peaks. Embedding everything is the default mistake.
4543
- **Embed is scarce + spaced.** ≤1 embed per sentence/beat, never two adjacent or
@@ -48,11 +46,10 @@ Quoted from the `embedded-captions` non-negotiables:
4846

4947
## The overlay law — captions are NOT a reserved band
5048

51-
In a generated launch composition, when captions are enabled, finalize composites a
52-
**small, minimal word-by-word caption line** as an overlay layer ON TOP of the whole
53-
film (a single text line, bottom-centered, roughly the bottom ~5-8% of canvas height).
54-
It is an overlay, not a reserved zone (verbatim from constraint #13 of the
55-
product-launch-video scene agent):
49+
In a composed video with captions enabled, the caption line is a **small, minimal
50+
word-by-word line** composited as an overlay layer ON TOP of the whole film (a single
51+
text line, bottom-centered, roughly the bottom ~5-8% of canvas height). It is an
52+
overlay, not a reserved zone:
5653

5754
- **Center the composition on the TRUE vertical center — y = H / 2** (landscape 540,
5855
portrait 960). Do not shift content up to "make room" for captions; a composition
@@ -64,7 +61,7 @@ product-launch-video scene agent):
6461
line sits — the overlay would fight it. Large imagery / cards / ambient content under
6562
the captions is fine; the caption skin is designed to read over content.
6663
- There is no machine keep-out gate (the old `captions.mjs keepout` check is retired).
67-
Finalize snapshot QA judges caption-over-content legibility visually.
64+
Snapshot review judges caption-over-content legibility visually.
6865

6966
**When captions are disabled:** identical positioning freedom — the overlay simply
7067
doesn't exist.
@@ -74,8 +71,8 @@ doesn't exist.
7471
The model says the rail rides **in front** and an embed is a rare word composited
7572
**behind the subject** — both are layers added to footage that ships untouched. The
7673
overlay law says the caption line is a layer composited **on top** of the whole film,
77-
not a band carved out of the layout. So in both the captioning pipeline and the
78-
launch-video pipeline, captions are an overlay you add, not a zone you reserve:
74+
not a band carved out of the layout. So whether captions go over footage or over a
75+
composed film, they are an overlay you add, not a zone you reserve:
7976

8077
- Keep the full frame; center on true center; let content run to the edges.
8178
- Make the rail (or the small overlay caption line) carry the verbatim words.

‎.fallowrc.jsonc‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -94,14 +94,6 @@
9494
// The relocated media-use .mjs files are agent-invoked scripts outside the
9595
// import graph; keep the exemption scoped to that shipped script type.
9696
"packages/cli/src/media-use/**/*.mjs",
97-
// Agent-invoked motion-graphics tools co-located with their docs (run via
98-
// `node <path>` per grounding/PROTOCOL.md / categories/maps/module.md
99-
// prose), not import-graph reachable.
100-
"skills/motion-graphics/grounding/**",
101-
"skills/motion-graphics/categories/**",
102-
// Agent-invoked reference materials (template + motion-primitive HTML, catalogs),
103-
// forked by path by the frame-worker per SKILL.md prose, not import-graph reachable.
104-
"skills/music-to-video/references/**",
10597
// Bundled @font-face data (read at runtime via fs.readFileSync, invisible
10698
// to the import graph) + its manual rebuild tool.
10799
"skills/**/fonts/**",

‎.github/workflows/ci.yml‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -170,7 +170,6 @@ jobs:
170170
- "skills/gsap/**"
171171
- "skills/media-use/**"
172172
skills:
173-
- "scripts/generate-captured-font-copies.mjs"
174173
- "packages/cli/src/media-use/**"
175174
- "scripts/check-media-use-copy-parity.test.mjs"
176175
- "scripts/check-skill-import-boundaries.test.mjs"
@@ -192,7 +191,6 @@ jobs:
192191
- ".claude-plugin/**"
193192
- ".cursor-plugin/**"
194193
- "scripts/package-agent-plugin*"
195-
- "scripts/agent-plugin-captions.test.mjs"
196194
- "scripts/set-version*"
197195
- "LICENSE"
198196
- ".codex-plugin/**"
@@ -716,8 +714,6 @@ jobs:
716714
- name: Exercise npm-cli bootstrap command
717715
run: >-
718716
node --test
719-
skills/hyperframes-animation/scripts/package-loader.test.mjs
720-
skills/hyperframes-creative/scripts/package-loader.test.mjs
721717
skills/hyperframes/scripts/plugin-cli.test.mjs
722718
723719
# Guards that skills-manifest.json (the published freshness fingerprint read
@@ -787,8 +783,6 @@ jobs:
787783
run: node --test scripts/package-agent-plugin.test.mjs
788784
- name: Build portable agent plugin
789785
run: node scripts/package-agent-plugin.mjs
790-
- name: Exercise captions from the extracted portable bundle
791-
run: node --test scripts/agent-plugin-captions.test.mjs
792786
- name: Build upload-ready Codex plugin
793787
run: node scripts/package-codex-plugin.mjs
794788

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -197,3 +197,7 @@ chrome/
197197
# Hosted catalog item files are generated output the docs host serves; the rules above match their folder names
198198
!docs/public/catalog/items/**/compositions/
199199
!docs/public/catalog/items/*-ad/
200+
201+
# Python bytecode from running skill scripts
202+
__pycache__/
203+
*.pyc

‎.prettierignore‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,6 @@ registry/blocks/orbit-card/assets/three.module.min.js
3737
registry/blocks/orbit-card/assets/gsap-3.14.2.min.js
3838
# generated Lottie data: pretty-printing multiplies its size
3939
registry/blocks/lottie-character-walk/assets/mascot.json
40-
# reference snippets with intentional pseudo-markup (literal "..." attributes)
41-
skills/talking-head-recut/references/frames/polaroid.html
4240
# repo-native skill examples with intentional pseudo-markup placeholders
4341
# (e.g. <RANGE>, <TOTAL> tokens the agent replaces at build time — not real HTML)
4442
.claude/skills/**/examples/**/*.html
@@ -49,3 +47,12 @@ skills/talking-head-recut/references/frames/polaroid.html
4947
# explicitly (not registry/examples/**/*.html) so hand-authored example HTML still
5048
# gets formatted.
5149
registry/examples/warm-grain/compositions/captions.html
50+
51+
# Skill entries: agents read each one whole when it opens, so table padding costs tokens every time.
52+
skills/hyperframes/SKILL.md
53+
skills/hyperframes-cli/SKILL.md
54+
skills/hyperframes-registry/SKILL.md
55+
skills/media-use/SKILL.md
56+
skills/figma/SKILL.md
57+
skills/slideshow/SKILL.md
58+
skills/remotion-to-hyperframes/SKILL.md

0 commit comments

Comments
 (0)