Visual Explainer Production Studio — Shorts + Long Form

Purpose

Turn a topic into a research-backed, editor-ready visual explainer package. This skill supports two distinct production modes:

Short-form: a tightly timed vertical explainer, usually 48–59 seconds.
Long-form: an 8–12 minute, usually 16:9 explainer that deliberately combines AI-generated video with motion graphics, animated diagrams, charts, kinetic typography, maps, archival/stock footage, screen recordings, stills, and carefully chosen visual pauses.

The skill is not a video generator alone. It is the story, visual-design, prompt-compilation, and editing-handoff planner. It must deliver a single consolidated prompt pack plus a separate Director's Note that an editing skill can follow without needing to infer the creative intent from scattered prompts.

Single-File Compilation & Telegram Delivery Rules

Unified Text Compilation: When requested to compile hook prompts or an episode pack into a text file, compile BOTH the master voiceover with exact timestamps AND the complete scene-by-scene video prompts (including master prompt, second-by-second timeline progression, technical camera/lighting specs, and negative prompts) into ONE dedicated .txt file in the vault (/home/john/kos-obsidian-omni/<slug>.txt).
Telegram Message Safeguard (<3,000 chars): Never dump thousands of lines of raw prompts directly into Telegram when a .txt file has been written. Output the complete voiceover script with timestamps in a clean ```text block, summarize the scene titles/focal points, and point directly to the saved .txt file path. This preserves markdown formatting and the 1-tap Copy button.

For The Pop-Up Ledger (papercraft / 3D pop-up macroeconomics and history), refer to references/the_pop_up_ledger.md. For long-form pacing and mixed-media workflow, read references/long-form-explainer.md and references/directors-note-template.md before production.

Mode Routing — Decide This First

If the user explicitly asks for a format, obey it.
Otherwise, a video under 60 seconds is short-form; a target of 8–12 minutes is long-form.
Never apply Shorts-only limits (6-second scenes, 115–130-word narration, vertical framing) to long-form work.
Never stretch a Short into long-form by adding filler. Long-form needs a deeper question, multiple explanatory steps, evidence, a midpoint re-engagement, and a meaningful synthesis.
If the user requests a long-form video without a topic, ask one concise topic question. Do not ask for details that can be sensibly defaulted.

Non-Negotiable Production Rules

1. Research before claims

Verify material facts, dates, names, quantities, mechanisms, comparisons, and causal claims using credible sources; prefer primary sources and expert institutions where suitable.
Keep a fact ledger with each claim, source URL/title, publication or access date where relevant, confidence, caveat, and what visual could honestly demonstrate it.
Separate established fact, estimate, disputed interpretation, and illustrative metaphor. Never let a cinematic visual imply more certainty than the evidence supports.
Do not invent sources, statistics, quotations, footage provenance, or exact visual data. If a claim cannot be verified, say so in the production package and either remove it or label it appropriately.

2. Story before shots

State the central question, central answer/thesis, target audience, intended takeaway, and why the viewer should care.
Build the causal chain or narrative spine first. Each chapter and visual beat must explain, prove, compare, contextualize, or emotionally reinforce something specific.
Map every major narration beat to a primary visual approach. Do not generate visuals merely to decorate narration.

3. Hybrid visuals by default for long form

Do not make the whole long-form video AI-generated. Choose the medium that best explains each idea. AI video is one tool among several, not the default answer to every line.
Use motion graphics for readable labels, arrows, counters, timelines, callouts, diagrams, and staged concept reveals. Use deterministic graphics for exact numbers, source-linked charts, maps, and technical labels.
Use AI-generated footage for atmosphere, illustrative reconstruction, visual metaphor, impossible camera moves, or scenes that are expensive/impossible to film. Clearly distinguish illustrative reconstruction from authentic evidence.
Use real stock/archival footage, screenshots, product footage, or screen recordings when authenticity, proof, UI detail, or real-world context matters. Record source/license/credit information when applicable.
Use kinetic typography selectively for key phrases, contrast, chapter turns, and memorable summaries—not as a substitute for explaining complex ideas.
Avoid relying on generative video to render critical readable text, equations, UI copy, chart values, exact borders, maps, labels, or source data. Composite these in post-production.
No fixed visual-media percentages. Choose the medium for clarity, trust, cost, production time, and visual variety. State why each major shot or graphic uses its selected asset type.

4. Audio is planned separately

Never place the voiceover script inside an AI video generation prompt.
Unless the user explicitly requests generated dialogue, video prompts must specify visual action, camera, continuity, and diegetic sound / Foley / ambience only, ending with: Sound effects: [specific ambience/Foley]. No voice over, no talking, no intelligible dialogue.
Voiceover, music, sound effects, and graphic timing must be separate fields in the spec and explicit in the Director's Note.
Do not assume an AI clip's generated audio will be used in the final edit. Treat it as optional reference unless the editor deliberately selects it.

5. Continuity and truth

Lock recurring subjects, material, camera geography, lighting, palette, and visual treatment when shots need to match.
For segmented continuous scenes (Google Flow / Omni or another tool supporting reference frames), use the exact last usable frame of shot N as the reference for shot N+1 and specify the continued camera vector and action. This rule is optional for cut-based edits.
Label diagrams/maps as schematic when exact geometry is not sourced. Never present a generated map, chart, archive-style image, or reconstruction as authentic evidence.

6. Delivery must include an editor handoff

Always compile all AI video prompts and visual-generation prompts into one clean <slug>_prompts.txt file, grouped by scene/asset ID and copy-ready.
Always create <slug>_directors_note.md, a standalone editing handoff with an overall creative brief, story/chapter map, provisional or locked timeline, narration sync cues, motion-graphics build instructions, transition and sound design, asset references, continuity rules, and final checks. This is a required output, not an optional summary.
Include <slug>_production_spec.yaml as the structured source of truth and <slug>_voiceover.txt as a clean narration copy. Include <slug>_research_ledger.md when the project makes factual claims; include an asset manifest where source/license tracking is useful.
Use a configured project/vault location when it is actually available. Otherwise create a project folder inside the current writable workspace (for example visual-explainer-output/<slug>/). Do not assume a machine-specific home directory exists. Never report a file as saved unless it was actually written and verified.

7. Respect actual renderer limits

Check the chosen AI model's available duration, aspect ratio, reference-image, and audio controls before finalizing prompts.
Do not write a requested duration into a prompt as if the model supports it when it does not. Generate supported segments and plan trimming, extension, or compositing in post.
The planned edit timeline is provisional until the final voiceover/audio duration is known. Mark provisional timings honestly; update the final timeline after audio is measured whenever that asset is available.

Short-Form Mode — Under 60 Seconds

Runtime and scene rules

Default target: 48–54 seconds, normally 8–9 visual beats.
Preferred generated-scene unit: 6 seconds when the chosen model supports it. If it does not, use a supported duration and plan the cut/trim in post; do not falsely request an unsupported duration.
Keep the final video under 60 seconds unless the platform/user target differs.
A starting narration target for 48–54 seconds is about 115–130 words at approximately 130–145 words per minute. Count the words and, when generated narration is available, time the actual audio before locking scene timings.

Short-form story recipe

0–2 seconds: visual hook. Start with a paradox, striking fact, tension, scale contrast, or impossible-looking proof—not a generic greeting.
2–8 seconds: promise the answer. Make the specific question obvious.
Middle: explain one causal chain. Each shot should add a distinct step, comparison, consequence, or piece of evidence.
Payoff: resolve the opening question. Do not end with a vague summary.
Close: use a concise audience prompt only if it fits naturally; never sacrifice the answer for a CTA.

Short-form visual/audio checks

Keep one dominant visual idea per shot and short on-screen text.
Plan the hook, captions, safe-area placement, sound design, and final payoff for mobile viewing.
Keep exact labels/data as post-production overlays, not AI-rendered text.
For maps and continuous-scene explainers, preserve the persistent scene/camera path and tie every overlay to narration triggers.
For an excerpt repurposed from long form, rebuild the hook and payoff so it works independently; do not just crop a random middle section.

Long-Form Mode — 8–12 Minutes

Read references/long-form-explainer.md in full. The long-form mode is a deliberate mix of cinematic visuals, diagrams, kinetic typography, evidence visuals, charts/maps, real assets, and restrained pauses.

Runtime and narration planning

Default target: 8–12 minutes, normally 16:9. Use the user's requested platform/aspect ratio if different.
Initial narration estimate: approximately 1,150–1,600 words at a natural documentary pace around 130–145 words per minute, depending on pauses, emphasis, and visual-only moments. This is a planning band, not a blind rule; estimate runtime from the selected delivery rate, then use the actual voiceover duration before locking the edit.
Do not pad to hit a word count. A strong 8-minute video is better than a diluted 12-minute one.
Break narration into chapters and short meaning units. Keep a separate clean narration file, while preserving paragraph/beat IDs that map to the timeline.

Long-form story structure

Open on a strong visual question, surprising result, contradiction, mystery, or consequential example.
Tell the viewer what question the video will answer and why it matters, without a long channel intro.
Establish a useful mental model before introducing too many terms.
Build through distinct chapters: context, mechanism/evidence, complication or counterpoint, implications, and synthesis. Adapt the order to the topic.
Include a midpoint attention reset—such as a new scale, case study, unexpected comparison, diagram transformation, or reveal—roughly halfway through. Do not manufacture a twist if the evidence does not support one.
Close by answering the opening question, connecting the parts, naming uncertainty where relevant, and offering one memorable takeaway.
See the reference guide for a suggested 8–12 minute chapter map. Treat it as a scaffold, not a rigid timestamp mandate.

Long-form visual planning

For every chapter, specify:

The viewer's question at this moment.
The narration beat / key claim.
The primary visual medium and why it is the best fit.
The visual proof, mechanism, comparison, or metaphor.
The editorial action: hold, reveal, label, track, compare, zoom, pause, or transition.
Required exact assets/data and their source status.
Whether the visual is authentic footage, sourced footage, a schematic, an AI reconstruction, or a metaphor.

Use flexible shot/graphic durations. Simple illustrative inserts may be short; a well-paced diagram may remain on screen for 10–25 seconds while layers build in response to narration. Change the visual when the idea changes, not merely to force constant cuts. Avoid long unchanging wallpaper, but allow evidence and complex diagrams enough time to be understood.

Long-form Director's Note is mandatory

The Director's Note is the editing skill's primary operational guide. It must explain the intended viewing experience and how to assemble the entire video. It must reference prompt IDs/assets instead of duplicating their full prompt text. Every timeline event must point to narration/beat IDs, and every generated/sourced asset must map to a shot or graphic. If exact timings depend on ungenerated voiceover, mark them PROVISIONAL — sync to final VO.

Visual Modes

Choose the visual mode from the subject. Blend modes deliberately when it improves explanation.

Geology / Continuous Globe: Continuous orbital-to-ground trajectories, sourced plate boundaries, cross-sections, terrain highlights, and world-space callouts.
Papercraft Stop-Motion / Tactile Pop-Up Diorama: Layered cardstock, foldouts, sliding tabs, cutaway ledgers, tactile shadow, subtle stepped motion, and diegetic paper/cardboard Foley.
Timeline / History Flashpoints: Timeline states, maps, period objects, archival evidence, migration/trade routes, and clearly labeled reconstructions.
Process / How-It-Works: Inputs → mechanism → outputs; exploded views, arrows, component layers, signal/material/energy flows, and step-by-step diagrams.
Data / Finance / Economics: Correctly sourced charts, cash/commodity flows, counters, supply chains, scale comparisons, and explicit causal diagrams.
Anatomy / Health: Evidence-based anatomical layers and physiological sequences; conservative language and no claims beyond the source evidence.
Network / Technology: Node maps, packet/signal flows, network architecture, device footage, screen recordings, and animated system diagrams.
Science & Extreme Phenomena: Controlled simulations, micro-to-macro scale shifts, measured overlays, cross-sections, and evidence-backed visualizations.
Comparison: Split-screen, proportionally accurate scale bars, aligned silhouettes, before/after states, and a named comparison metric.
Kinetic Typography: Selectively animate a key phrase, number, contradiction, definition, or summary—not every sentence.
Mixed-Media Documentary: Deliberate combination of sourced footage, AI illustrative shots, stills, motion graphics, diagrams, and text.

Production Procedure

1. Intake and mode selection

Resolve topic, format/mode, central question, audience, language, platform, visual style, and any required channel branding.
Default short form to English, 9:16, 48–54 seconds unless the user says otherwise.
Default long form to English, 16:9, 8–12 minutes unless the user says otherwise.
Treat logos, channel badges, narrator names, font families, exact model choice, and output directories as configuration; never assume JAN CLIPS or any channel badge unless requested/configured.
If an available persistent topic registry exists, consult it before suggesting topics; do not pretend a local vault is available when it is not.

2. Research + fact ledger

Verify the thesis and supporting claims.
Record source details and uncertainty.
Identify what can be proven with data/real footage and what is only illustrative.

3. Story + narration

Draft the hook, question, thesis, causal chain, chapter/beat map, open loops, payoff, and close.
Estimate timing from actual word count and intended delivery rate. For long form, identify midpoint re-engagement and any counterpoint/caveat.
Assign stable beat IDs before building visuals.

4. Visual decision pass

For each beat, decide whether it needs AI video, AI still, stock/archival footage, screen recording, motion graphics, a deterministic diagram/chart/map, typography, or a hybrid composition.
State the purpose of the medium choice. Avoid redundant generated clips where one precise graphic would explain more clearly.
Specify all exact labels/data for post, staging and reveal order, transition logic, aspect ratio, safe areas, continuity, and SFX.

5. Prompt writing and compilation

Write copy-ready generation prompts with scene/asset IDs, intended role, subject, action, camera, visual style, lighting, continuity, negative constraints, target aspect ratio, and supported duration.
Keep VO separate from prompt text. Keep critical facts/text in post-production fields.
Compile all visual generation prompts into one file: video, still/image, thumbnail, and any other prompts actually needed. Add a clear table of contents and preserve asset IDs.

6. Director's Note construction

Build the editing guide only after the script, visual plan, and prompt/asset IDs are stable.
Include an overview, timeline/chapter structure, beat-to-visual mapping, graphics animation recipes, VO sync cues, transition rules, sound and music, accessibility/captions, continuity, source-sensitive cautions, and fallback options.
Distinguish provisional from locked timecodes. Reference generated prompt/asset IDs so the editing skill can find each asset without guesswork.

7. Save + audit + deliver

Save the production spec, prompt pack, Director's Note, clean voiceover, and research ledger when relevant.
Run scripts/validate_skill.py after skill edits or if the tool environment permits.
Run audits/pre-build-audit.md before creating a production package and audits/post-build-audit.md afterward.
Deliver clear links/paths to each created output. If file creation is unavailable, provide copy-ready content and state that no file was saved.

Required Output Contract

For each finished project, produce or explicitly mark as unavailable:

<slug>_production_spec.yaml — source of truth for the project, facts, script beats, shot/graphic IDs, prompt references, voice, and assembly requirements.
<slug>_prompts.txt — all AI video/image/thumbnail prompts in a single clean file, grouped by ID and intended use.
<slug>_directors_note.md — mandatory instructions for the editing skill.
<slug>_voiceover.txt — clean narration with beat IDs/paragraph breaks; no production chatter embedded in lines to be spoken.
<slug>_research_ledger.md — claims and sources when the video contains factual assertions.
<slug>_asset_manifest.csv or an equivalent table when sourced assets, licenses, credits, or many generated files need tracking.

These outputs must agree on the same scene/beat IDs, filenames, runtime, platform, and creative rules. Run a cross-file consistency check before delivery.

Ask in your favorite AI

Documentation