motion-explainer: turn a finished script into a build-ready brief for HTML explainer videos

Without a fixed style, an AI builder guesses the look scene by scene. Colours can drift between scenes, text can get too small to read on a phone, and the render can go up without anyone checking it against the script.

motion-explainer is the station that sits between a finished script and the build. It's the method behind the chalkboard explainers on my two YouTube channels, cleaned up as a free skill so you can swap in your own look and keep the rules. It never renders or uploads anything. It writes the brief, the chapter jobs and the review checklist.

It's the first station in the aiwos-factory pack of AI Work OS. Why stations like this chain into a factory is in build a factory, not a shortcut.

When to use it

Use it when a long explainer or a Short already has a script that's been fact-checked, and you want it built as motion graphics in an HTML-to-video tool such as HyperFrames. Without a build tool the brief still works for a human motion designer.

If your 30 to 60 second piece doesn't have a script yet, run video-brief from the aiwos-video pack first. If you want a quick shot list for filming on your phone instead, the 用例库 entry 把口播稿变成一张分镜表 is the lighter version.

Install it

In your project folder, in Claude Code:

claude plugin marketplace add Rebelzxr/ai-work-os
claude plugin install aiwos-factory@ai-work-os --scope project

Codex users can point Codex at packs/factory/skills/motion-explainer/SKILL.md in the repo. There's also a copy-paste edition, PROMPT.md, for any AI chat.

What to give it

• The finished script, split into lines or beats. The skill doesn't check facts, so do that before.
• One sentence on what the viewer should understand or be able to do at the end.
• The format: a long (16:9) or a Short (9:16).
• The proof you're allowed to show: your own screenshots, recordings, numbers from your own receipts, or licensed clips with the licence noted.

On the first run, use a made-up script. Clean real material first: no client names, phone numbers, account IDs or anything you wouldn't show on screen.

What you get back

A folder with these files:

1. STYLE.md: the locked look. Colours, type sizes, pacing, logo and face rules. Builders never change it.
2. SCENES.md: one row per scene with the time span, narration, what's on screen, one motion verb, the on-screen text and the proof asset. Time spans come from the voice once it exists and are estimates until then.
3. briefs/chapter-<n>.md: one build brief per chapter, ready to hand to a sub-agent or a person. Each one carries the unchanged STYLE.md, its rows from SCENES.md, the exact narration with timings, the asset folder it may read, the one folder it may write and the gate it must pass.
4. REVIEW.md: the gates and a review prompt for someone who didn't build it.

The rules that make it readable

Colour means something. You pick a base colour and give every other colour one job. In my chalkboard look, white is plain text, orange is the keyword of the line, slate blue is a tool or the AI, brick red is a problem and mint is a pass. Nothing is coloured for decoration.

Text you can read on a phone. In a 16:9 long, any active text is at least 5% of the frame height, about 54 px at 1080. In a Short, active text is at least 60 px tall on the 1080x1920 frame. Small source labels are the only exception.

Show one thing at a time. A table or list reveals one group at a time with the rest dimmed. Proof goes big: a screenshot or clip fills at least 60% of the frame width, cropped to the part that matters, with a small source and date label.

Every number on screen has a source. If a number isn't in your receipts or a linked page, it becomes a plain sentence or comes out.

Pace. The screen changes every 2 to 4 seconds in a long and every 1.5 to 2.5 seconds in a Short. A chapter card stays up 2 seconds at most, and it's never a silent card right after the opening promise. The only exception is the ending hold of a long.

Shorts. Frame 1 shows a number or a visible result, never a logo or a title. Nothing important in the bottom 350 px or the right 150 px, where the app's buttons sit. Captions sit in one band in the lower middle. No end card, and the last frame loops back to frame 1.

Longs. The final frame holds at least 10 seconds with space for end-screen elements.

Logos and faces. Real tool logos come only from the brand's own assets, or as simple drawn tiles that follow the brand's rules. Never AI-generated logos, and never AI-generated faces of real people.

The review loop

Builders work one chapter at a time, write code only to their own folder and never change the style or another chapter. Each chapter passes its own gates before stitching:

• the build tool's lint and check report 0 errors
• captions match the voice word for word, with no overlapping cues
• a contact sheet with one still every 2 seconds, which the builder reads and fixes
• before a render, there's enough free memory and disk, and renders run one at a time.

Then a different model, or a fresh session with no build history, reviews the rendered video, the sound report, the contact sheets, the captions, the script, STYLE.md, SCENES.md and the proof behind every on-screen number. It never gets the builder's chat. If it can't play the video or measure the sound, those checks are marked UNVERIFIED, not passed. It returns PASS, PASS WITH FIXES or FAIL with exact fixes. The builder fixes, the changed parts get reviewed again, and after 3 rounds whatever is left goes to a person.

Sound is checked by measurement when nobody listens to the mix. While someone is speaking, effects sit at least 12 dB below the voice, measured as RMS on the separate voice and effects tracks in 1-second windows. The master lands around −14 LUFS integrated with true peak at −1.5 dBTP or lower, measured with a loudness meter such as ffmpeg's ebur128 filter. Any number you couldn't measure goes in the receipt as UNVERIFIED, never as a pass.

Test it in 5 minutes

The repo has a made-up test script at tests/packs/motion-explainer/input.md: a cafe owner, a weekly sales summary and a few traps. A pass means the output has the four parts, every scene row has a time span, a motion verb and a proof note, and the brief refuses the traps. Those are an AI-generated logo, a "number one" claim with no source, and a Short that opens on a title card.

What stays with you

The skill only writes briefs and checklists. Rendering is your build tool's job. Uploading, scheduling and publishing stay with a person, after the second-model review has passed.

The skill file is in the AI Work OS repo.