Faceless Explainer

media-use: Before sourcing audio/images, call /media-use to resolve BGM/SFX/images from the HeyGen catalog. Run --adopt first to register existing assets. See /media-use skill.

Faceless Explainer to HyperFrames

Use this skill to turn a body of text into an explainer video: pick a design system, plan a teaching story, and build it frame by frame in HyperFrames. Faceless means every visual is invented downstream — there is no capture step and no real asset inventory.

Confirm the route before Step 0. You are the orchestrator. Run each step, verify its gate, and only then continue. This skill is for explaining a topic from text, with no product and no website to capture. Route other intents elsewhere: a product launch/promo → /product-launch-video; a tour of a real site → /website-to-video; a GitHub PR → /pr-to-video; captions on existing footage → /embedded-captions; a short unnarrated motion graphic → /motion-graphics. If the user says only "make a video" or the route is uncertain, read /hyperframes first.

You are the orchestrator. Work in videos/<project>/. Run steps in order and pass each gate before continuing. User-gated steps are Step 0, Step 3, and Step 6. Do every step yourself except Step 5, where you dispatch one sub-agent per frame. Do not put design or motion rules here; those live in the frame-worker sub-agent, hyperframes-creative, and hyperframes-animation.

Workflow: Step 0 setup → hyperframes.json; Step 1 brief → capture/extracted/; Step 2 design system → frame.md; Step 3 storyboard/script → STORYBOARD.md and SCRIPT.md; Step 3.1 audio → audio_meta.json; Step 4 visual design → enriched STORYBOARD.md; Step 5 frames → compositions/frames/NN-*.html and index.html; Step 6 final render → renders/video.mp4.

Step 0: Setup and Brief

Goal: Lock the core video brief and create the HyperFrames project if needed.

Initialize only if hyperframes.json is missing. Name <project> from the topic in kebab-case, such as compound-interest-explained; never use workspace name or timestamp.

npx hyperframes init "videos/<project>" --non-interactive --skip-skills --example=blank

Show sign-in status before the brief — run npx hyperframes auth status and relay its output verbatim (don't paraphrase or rewrite it). It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else. Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo .env. (In autonomous mode, note the status and continue offline.) See ../hyperframes-media → Preflight for the canonical guidance.

Gate: hyperframes.json exists, and angle, length, aspect ratio, and language are locked; sign-in status was shown (signed in, or continuing offline).

Step 1: Brief (no capture)

Goal: Fold the user's text into the project as the source of information. There is no website capture and no real assets — this is a faceless explainer.

Save the user's full input verbatim, then create the synthetic capture package by hand:

• capture/extracted/visible-text.txt — the full article / notes / topic / brief, verbatim. This is the source of information, not a story template (Step 3 reshapes it).
• capture/extracted/tokens.json — { "title": "", "description": "", "colors": [], "fonts": [] }. Fill title/description from the brief. Leave colors/fonts empty unless the user explicitly gave brand colors or fonts — then add them (the design preset supplies a complete palette regardless).

Do not run npx hyperframes capture (there is no URL). Do not create asset-descriptions.md or populate capture/assets/ — faceless visuals are invented in Steps 4-5, not captured. The one exception: if the user supplied a real image, place it under public/<basename> and note it for Step 3.

Gate: capture/extracted/visible-text.txt and capture/extracted/tokens.json exist; you can state the explainer's topic and audience in one clear sentence.

Step 2: Design System

Goal: Choose one shipped frame preset; a script turns it into this video's frame.md + caption skin.

You make the one judgment call — which preset. Read ../hyperframes-creative/references/design-spec.md and browse ../hyperframes-creative/frame-presets/; pick the preset whose look best fits the topic, tone, and audience. Then run:

node <SKILL_DIR>/scripts/build-frame.mjs --preset <name> --hyperframes .

The script does the rest deterministically: copies the preset's FRAME.md → frame.md and remixes it onto any brand tokens in capture/extracted/tokens.json (brand colors mapped onto the preset's color keys by role; the preset's display + body fonts swapped for the brand's), copies the preset's caption skin to .hyperframes/caption-skin.html, and self-validates (exits 1 on a broken mapping). Proceed as soon as it exits 0 — no hand-editing of the spec.

A faceless explainer usually has no brand colors/fonts (tokens.json colors/fonts empty) → the script keeps the preset's own palette, a complete shippable design. Only when the user named brand colors/fonts add them to tokens.json before running, and only adjust frame.md by hand afterward if a mapping truly needs it.

Gate: build-frame.mjs exited 0 — frame.md exists from a named preset, and (when the preset ships one) .hyperframes/caption-skin.html exists as the caption skin source.

Step 3: Storyboard and Script

Goal: Turn the text into an approved frame-by-frame teaching plan.

Read references/story-design.md, ../hyperframes-core/references/storyboard-format.md, and ../hyperframes-core/references/script-format.md. Use them to write STORYBOARD.md and, when narration is needed, SCRIPT.md.

Use story-design.md for the explainer structure (concept / how-to / listicle / story), hook strategy, clarity techniques, emotional beats, the type-enum mapping, and VO_MODE. The video's sequence comes from narrative design, not the input text's paragraph order — reorder, merge, omit, compress. Faceless visuals are invented downstream, so frames do not carry an asset inventory: leave asset_candidates empty unless the user supplied a real public/<basename> image. Use the exact required fields from the storyboard and script references.

After drafting, show a frame-by-frame summary. In that same message ask the user two things: (a) to approve or request changes, and (b) whether they want a live preview of the storyboard scaffold (npx hyperframes preview) — open it only on a yes. Iterate until approved, and carry the preview choice to Step 6.

Gate: STORYBOARD.md exists, every frame has the required narrative fields, SCRIPT.md exists when narration is needed, and the user approved the frame-by-frame plan.

Step 3.1: Audio

Goal: Generate narration, word timings, music, and audio metadata from the approved script.

Start audio after Step 3 approval. Run it in the background, then continue to Step 4. (Sign-in status was already shown in Step 0; the engine falls back automatically.)

node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &

The audio script handles narration, word timings, BGM lookup from HeyGen's music library, and timing metadata. BGM mood comes from the storyboard's music: field. This uses the HeyGen Audio API for retrieval, not generation, and the same ~/.heygen credential as TTS. For provider details, read ../hyperframes-media/references/tts.md.

If there is no narration and no SCRIPT.md, skip voice generation. BGM may still run if the storyboard has a music mood.

Gate: audio job has started, or the project is marked silent.

Step 4: Frame Visual Design

Goal: Add the visual direction, layout intent, and motion choices to each storyboard frame.

Edit STORYBOARD.md in place. Do not create another storyboard. Use frame.md as the source of truth for color, type, layout feel, and style.

Read references/visual-design.md, references/composition.md, references/motion-language.md, and ../hyperframes-animation/. Use visual-design.md for required frame fields and the required ## Video direction block. Use composition.md for layout, hierarchy, focal points, and the invented-visual treatment. Use motion-language.md and ../hyperframes-animation/ for valid effects and blueprint IDs. Do not invent effect names or blueprint IDs.

For every frame, add required visual and motion fields, including effects and focal and/or roles. Because the explainer is faceless, focal/roles describe invented visual elements (a hero word, a diagram node, a data-viz series), not captured assets. Add one video-wide ## Video direction block for overall visual direction, motion style, pacing, and design rules.

Do not change story, script, transition_in, or the source text. Do not write HTML in this step. There is no asset-staging step — faceless visuals are built by the workers in Step 5. If the user supplied a real public/<basename> image, reference it by path in the relevant frame's focal/roles; otherwise nothing to stage.

Gate: every frame has effects plus focal and/or roles; ## Video direction exists.