Faceless Explainer

<!-- Public portability adaptation, 2026-09-26. -->

Install this skill with its sibling skills. See runtime setup and capability boundaries before executing commands. User instructions and the requested production stage take precedence over workflow defaults.

media-use: Music and SFX must be individually reviewed and frozen under the project before use. Run /media-use with --adopt to register those local files; it does not search, download, or generate media.

Faceless Explainer to HyperFrames

Studio route: for long-form narration, mixed generated footage/UI/relational canvases, reference-led production, or repeated scene review, use /hyperframes and its references/review-driven-production.md instead of this short synthetic-frame route. “Faceless” does not require every film to be asset-free. Explicit requests to preserve the complete script override this route's editorial compression; existing full discretion overrides routine confirmation steps. Requested review-before-assembly remains a real stage boundary.

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 the chosen project directory (videos/<project>/ is an example). Run steps in order and pass each gate before continuing. Honor requested review boundaries; existing authorization supersedes routine confirmation steps. 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 --yes hyperframes@0.7.17 init "videos/<project>" --non-interactive --skip-skills --example=blank

The bundled audio adapter uses Fish via hyperframes-media; configure the selected transport and voice. For another requested provider or supplied audio, use the recorded-VO route. Do not silently switch providers after an error or include credentials in storyboards/manifests.

Gate: hyperframes.json exists, and angle, length, aspect ratio, and language are locked.

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 a shipped text/HTML frame preset; a script turns it into this video's frame.md + caption skin. These presets contain no font, image or audio binaries; supply required project assets and verify their availability.

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.

If the brief or emerging story arc needs a bounded momentum, temporal-compression, overwhelm, or panic/rupture passage, read ../hyperframes-creative/references/fast-paced-editing.md now. Step 3 owns cross-frame seams: choose each participating frame's transition_in and add the fast_passage / role / focal-handoff / root-mix metadata defined in story-design.md before approval. Step 4 may enrich the visuals but does not repair a seam that was never planned.

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.

If several consecutive teaching beats require one stable relationship geography and exact overview→detail→return continuity, consolidate them into one compound Spatial Canvas frame per story-design.md; do not distribute its regions across independent frame workers.

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/import the selected narration and real word timings, and attach any already-reviewed local music to the approved script.

Before starting, decide whether the explainer needs music. If it does, choose one already-reviewed local track, freeze it under assets/bgm/, register it with /media-use --adopt, and pass that exact project-local path with --bgm. The workflow never searches for or generates a track. If no reviewed track is available, proceed without BGM or stop clearly to obtain one; do not substitute a runtime music engine.

Start audio after Step 3 approval. Run it in the background, then continue to Step 4:

node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md \
  --hyperframes . --out ./audio_meta.json \
  --bgm ./assets/bgm/reviewed-track.mp3 & # omit this final flag when there is no music

This adapter implements the shared Fish route, transcribes it for word timing, validates/freezes the optional local BGM, and writes timing metadata. Fish credentials and defaults remain owned by /fish-audio-api. If there is no narration and no SCRIPT.md, voice generation is skipped; an explicit --bgm may still be attached. With neither narration nor BGM, mark the project silent.

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.

If any frame carries canvas_id, also read ../hyperframes-creative/references/spatial-canvas.md, instantiate ../hyperframes/templates/SPATIAL_CANVAS.example.json once as project-root SPATIAL_CANVAS.json, and use the spatial-canvas blueprint. Add/adapt exactly one scope: "scene" canvas entry per distinct canvas_id, each pointing to that frame's exact src; never overwrite an earlier frame's entry. Faceless compound frames keep excursions as fixed in-composition overlays owned by the same worker—omit cutawayComposition; every excursion still declares its own local at / duration / reviewAt, exact/reorient return ticket, and mutation. After timing sync, the worker gives each excursion one direct-root native clip marker with that exact local window, per the core contract. Also create project-root DIRECTION.md from ../hyperframes/templates/DIRECTION.md so route review has a ledger. The draft timing locks route proportions; Step 5 reconciles absolute times after narration sync.

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.

If Step 3 admitted a fast passage, use ../hyperframes-creative/references/fast-paced-editing.md to complete its shared visual direction. Mark the consecutive frame IDs and provisional within-frame proportions, baseline/escalation roles, peak, release/reorientation, eye-trace, primary edit family, and sound/legibility plan in ## Video direction; give every participating frame its exact visual arc role. Preserve Step 3's transition_in and marker fields. Do not add a second timing manifest—the storyboard's durations become authoritative after sync.

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; every admitted fast passage names a contiguous span, baseline/escalation/peak/release, primary family + optional accent, eye-trace, sound/legibility plan, and each participating frame has its role plus entry/exit handoff and Step-3-owned seam.