Vox Explainer Agent Skill

Plain-Sight Explainer (Gateway Workflow)

Build against the HyperFrames composition contract (clips, data-* timing,

and the #root schema). Install the upstream HyperFrames skills with

npx skills add heygen-com/hyperframes, or scaffold with

npx hyperframes init, and read the generated project documentation first.

Make a 60–90s explainer about something the viewer sees daily but has never

looked at. The film manufactures recognition first, then pays it off with a

causal history. Grammar measured from Vox's Cooper Black film; motion from the

same frame-by-frame calibration process.

This is a Vox-inspired design vocabulary, not an affiliation or endorsement.

Do not use Vox logos or imply that Vox produced the result.

Trust boundary and requirements

• Require Node.js 22 or newer for the bundled seam scripts. When they start a

preview server, npx may download the exact HyperFrames version pinned in

scripts/seam-gate.mjs from the npm registry.

• Read only the files and URLs the user supplies. Source mode may fetch public

citations and public-domain or openly licensed assets from declared sources.

Never send private documents, credentials, or private URLs to another

service.

• Ask before using any TTS or transcription API. State the provider, data sent,

required credential, and possible cost before the call.

• Write project source, downloaded assets, audio, contact sheets, and renders

only inside the user's chosen project directory. Do not publish or upload the

result automatically.

• The seam verifier starts a local preview server and an isolated Chrome

profile. Its --url and --comp-url inputs accept localhost only. A preview

may still load remote assets declared by the user's composition.

Reference map

Read only the references needed for the current stage:

• Topic selection: plain-sight-topics.md
• Script and captions: plain-sight-script.md
• Layout and assets: vox-collage-layout.md
• Text and highlights: vox-text-overlays.md
• Collage motion: vox-collage-motion.md
• Motion law and seam gate: motion-continuity.md
• Transition catalog and code: velocity-matched-transitions.md

and velocity-matched-transitions-gsap.md

• Multi-stage element motion: animation-overlap.md
• Render-safe seam mechanics: render-safe-seams.md
• Seam ledger and script usage: seam-gate.md

Pipeline (run in order; each gate blocks the next)

• Entry router — two modes, one gate. Read

plain-sight-topics.md.

• Topic mode (the user names a subject, or asks for ideas): the

four-part filter governs IDEATION and tie-breaking only. If a

user-chosen topic fails it, name which part fails and what the film

loses, offer passing alternatives — then build the film they asked for

if they confirm. The filter never refuses a chosen subject.

• Source mode (the user supplies material — documents: a memo,

strategy doc, report, paper, deck, transcript, PDF, or a folder of them;

or links: an article, docs page, repo, announcement): the filter does

not apply at all. After confirming the allowed network scope, read every

supplied file, fetch every supplied URL, and follow at most one public

citation hop when needed for a claim. When a citation is dead or truncated

(common in exported PDFs), do not guess the source — verify the claim

independently on the open web before it becomes a receipt, or cut it.

Then run the storyline mine. Person+date and PD-archive requirements are

waived; the mechanism beat is not. The audience is the

source's INTENDED audience, not "any viewer" — the FAMILIAR beat

calibrates to what they see daily. The VO never mentions the source —

see plain-sight-script.md.

The storyline mine (source mode). The source is ore, not an

outline — never film it section by section. Extract five things:

• The on-ramp — the recognition the intended audience already has, in

the source's own world (a habit, a number they see weekly, a thing on

their screen right now).

• The tension — the sharpest claim in the source that contradicts what

that audience assumes.

• The turn — the DIG's landing point: a person+date when the source

has one, otherwise the decision, number, or moment the story pivots on.

• The mechanism — the one claim the viewer can verify on screen

unaided. If the source only asserts, BUILD the demonstration (two-panel

compare, dots redistributed two ways, before/after at equal scale).

• The receipts — real artifacts from the source plus the open web

(charts, screenshots, filings, on-screen attributed quotes). Real-assets

rule still holds.

Map those onto the structural spine; beats the source can't fill honestly

get cut, not faked. Multiple sources — or ONE source carrying

several candidate storylines — mine each, then pick ONE spine: a film

gets one storyline; everything else demotes to receipts. Deliver the

beat map for approval before drafting script.

• Script — read plain-sight-script.md.

Draft VO + beat map. GATE: every line passes the deletion test;

opener/closer rules hold. If ghost-writing for a specific person, their

voice skill outranks this one.

• Design pass — read

vox-collage-layout.md. Build a contact

sheet (one frame per beat, 960×540 tiles, HTML → headless-Chrome screenshot)

from REAL assets. Deliver the sheet BEFORE building any comp. Iterate here

— it is 10x cheaper than comp notes.

LOOK GATE — check before delivering the sheet. Use this collage grammar

without implying Vox affiliation. Verify, don't assume:

• Palette is the measured set — ink #1a1a1a, yellow #FFE619, process blue

66CFFF, specimen blue #58BCEC, greys #F2F2F2 / #8d9399, ground #fbfaf8.

Treat bright blues as fills and accents. Use #3E87A8 or darker for small

text on white, and pass the renderer's contrast checks.

• Headlines are Archivo Black.
• Every frame is a named recipe from the layout reference (evidence stack,

zoom-isolation, two-panel compare, specimen grid, lower-third, newsprint

layering, circle reveal). Label each frame with its recipe on the sheet.

• The yellow circle appears as the recurring visual carrier.

The trap: when the source document belongs to a company with its own

design system — or the project folder already holds a brand capture,

frame.md, or an earlier build in that brand — the pull is to inherit

those tokens. Do not. brand-faithful is a DIFFERENT workflow for

product-launch films. A brand skin here is an explicit user decision, never

a default. Ask; don't substitute.

• VO — record or TTS. The TTS input file is a PRONUNCIATION script:

numbers written out ("eighteen thirty-nine"), names spelled as spoken.

Transcribe the result for word timestamps — audio is the clock; every cut,

pop, and highlight keys to a word time. A replacement VO = a full retime.

Captions transcribe the PERFORMED read verbatim, not the script doc.

TTS playbook: npx hyperframes tts first; if its bundled speech

stack fails (old Python, espeakng-loader abort), install espeak-ng and

call the Kokoro model directly with the CLI's cached model files. Use a

TTS API only after the user approves its provider, data sharing, credentials,

and cost. Then transcribe whatever produced the audio; the

timestamps are the clock regardless of the engine.

• Build — one HyperFrames comp, one clip group per beat, quiet caption

rail (suppress cues wherever promoted on-screen text carries the words).

Read vox-text-overlays.md and

vox-collage-motion.md before writing timelines.

• QC gates (all numeric, all mandatory)
• lint/check: 0 errors.
• Dead-time sweep: MAD every consecutive frame pair of the RENDER; any

still run >3s is a planning bug — add a staged reveal, not wobble.

• Seam measurement: for any zoom-isolation cut, render the last pre-swap

and first post-swap frames, detect the carrier in both, verify centers

within ~30px and sizes within ~10%. Fix by measuring, not eyeballing.

• Event-density: per beat, largest gap between authored timeline events

≤3.0s (the motion reference explains why the MAD sweep cannot see

creep-only holds).

• Composition integrity: audit the final keyframe sheet against the layout

reference's hard rules, item by item, logged.

• Keyframe sheet: screenshot one frame per beat; look at it.

Technique floor (anti-slideshow gate — declare at beat-map time)

Passing the defect gates does not make a film. A build that resolves every

beat to cards, side-by-sides, and lower-third text passes lint, seams, and

dead-time and still reads as a slideshow — the collage idiom lives in

techniques a cautious agent will never volunteer. So techniques are DECLARED

in the beat map, not improvised at build time: every beat names its layout

recipe AND its motion treatment from the motion reference's catalog, and the

film's distribution must clear this floor:

• ≥1 zoom-isolation swap — the camera pushes INTO a photograph, isolates the

carrier, and cuts through it (numerically aligned per the motion reference).

• ≥1 inverse zoom-through arrival, spent on a payoff beat.
• ≥2 drive-pasts or scale traversals that exit at/through frame-fill.
• ≥1 background-dropped cutout (subject lifted off its plate) doing motion a

flat card cannot — docking into a grid, riding a drive-past, anchoring an

iso swap.

• ≥1 newsprint layering moment; the circle reveal (the brand carrier).
• CAPS: static-card / side-by-side layouts ≤ one third of beats; no two

consecutive beats share the same layout recipe or the same treatment.

• When a photograph with interior depth is on frame, the camera enters it

rather than drifting over the card row — flat drift over cards is the

slideshow tell. Entering is governed by the zoom-in contract below.

The zoom-in contract. Pushing into a photograph promises the viewer the

payoff is INSIDE the image. Exactly two legal continuations:

• Background dropout — the subject lifts off its plate and becomes the

carrier (iso swap, dock, drive-past);

• Full-frame hold + callouts — the image holds at/near full-bleed while

annotations draw ON it (labels, arrows, attention windows).

A push into a photo that then cuts to an unrelated composition is banned —

that is a transition wearing a technique's clothes. If neither payoff serves

the beat, do not enter the photo.

Contract boundaries (what counts as "entering"): a sustained push whose

origin sits inside the image and that reaches near-full-bleed. Seam-scale

zooms (~0.2s whole-scene mechanics) and sub-10% camera creeps are different

categories and are not entries. An element driving AT the camera is the

mirror of an entry and obeys the same contract (it must already be a

dropped-out carrier, never a flat card flying at the lens). A traversal may

exit through frame-fill only into the same image or into the beat its own

motion caused — never into an unrelated composition.

QC: the beat map logs the treatment distribution table; the final keyframe

audit verifies each declared treatment actually appears on screen (the seam

verifier already measures the zoom-isolation numerically). A film that

cannot clear the floor honestly is a planning bug: re-plan the beats, do not

pad with decoration. When the floor's minimums and the zoom-in contract

conflict, the contract wins and the technique is cut — a missing technique is

a smaller defect than an unmotivated one.

Structural spine (weights of a 60s cut)

This weighted spine is authoritative. THE FAMILY (see the script reference) is

the back half of FAMILIAR — more instances of the recognition, not a new beat.

THE ARTIFACT BEAT sits between STORY and MECHANISM in the script reference's

spine too; when the two references seem to disagree, this list wins. In source

mode, spine beats the source cannot fill honestly (SECOND WIND, the person in

DIG) are CUT and their weight redistributed — the cut-don't-fake rule outranks

the spine's completeness.

FAMILIAR 15% → DIG (person + date named) 5% → STORY 15% → THE ARTIFACT BEAT

10% → MECHANISM the viewer verifies on screen 20% → SECOND WIND (a technology

removes a constraint) 15% → THESIS in the yellow circle 10% → CLOSE mirrors

the open 10%.

Non-negotiables inherited from the motion layer

• motion-continuity.md governs seams. Make

hard-looking swaps land inside a verified continuation seam; a literal

static-to-static cut is not exempt from the seam gate.

• Real assets only — PD archives (Wikimedia Commons API, LOC), flagged

recreations when a scan is missing. Recreating artifacts with shapes reads

as slop.

• Highlights always animate on per the text-overlay reference.
• Elements step at 12fps over smooth eases; camera moves stay smooth

per the collage-motion reference.