C4KEBX/motionexplainers

Make a 60-second explainer

Turn a topic into a finished 1080x1920 video with this repo's pipeline. It costs nothing: you do the research, writing and repair; the scripts check and render. Work from the repo root. Read .claude/skills/make-explainer/rules.md before writing a storyboard.

Hard rules

• Every number, date, name and quote on screen comes from a fact in facts.json whose source you actually opened with WebFetch. Never type a figure from memory. If you cannot source a claim, cut it. Narration states only what a page you opened says; do not pad with background claims you did not read.
• Never edit src/, tests/, the validators or this skill to make a storyboard pass. Fix the storyboard or the facts. Never change a fact's data to match a storyboard, or the reverse, without re-reading the source.
• STOP at the review gate (step 6). Do not run npm run produce until the user approves the review sheet.
• Finance and investing are educational and historical: no advice, no predictions, no "you should". Name the period and the source for every figure.

Workflow

Everything for a video lives in videos/<slug>/ (lowercase letters, digits, hyphens): facts.json, storyboard.json, review/.

1. Brief. Settle the topic, a one-sentence claim the video proves, and the audience. Ask one question only if the claim is unclear. Default voice en-US-AndrewNeural, music null.
2. Research. WebSearch, then WebFetch primary sources (BLS, Federal Reserve, SEC, company filings; Wikipedia or museum and library pages for history dates). Copy numbers from the page. Write 5 to 8 facts: id, claim (a full sentence with units and period, as the source states it), value for one number or dataset for the exact data a chart or list will show, and source with name and url. Never leave "demo data" wording in a claim.
3. Verify. npm run verify-facts -- --facts videos/<slug>/facts.json --out videos/<slug>/verify.json. For every not-found, partial or unreachable: reopen the source, fix or drop the fact. The tool is advisory; you own accuracy. A small whole number (8, 9, 27) appears on almost any page, so supported proves little for it: read the source line yourself. After you edit facts.json for any reason, run verify-facts again; the review sheet marks a stale result.
4. Script and storyboard. About 155 words of narration in total (55 to 60 seconds), 6 to 10 scenes, a hook in scene 1, one idea per scene, scene types varied (never three alike in a row). Use storyboard.schema.json for exact fields and limits and copy the shape of fixtures/finance.storyboard.json, fixtures/history.storyboard.json and fixtures/ancient.storyboard.json. Write videos/<slug>/storyboard.json.
5. Check and repair. npm run check -- --storyboard videos/<slug>/storyboard.json --facts videos/<slug>/facts.json. Fix every issue (each message names the scene and the fix) and re-run, at most 6 rounds; if something still blocks, report exactly what. Treat warnings (length, advice phrasing, untraced text) as things to fix or justify. The length estimate is good to about 10 percent (real words per second ranged 2.5 to 3.2), so aim for 55 to 60 s; produce is the authority and a rejected length just means adjust the narration and run again.
6. Review gate. npm run sheet -- --storyboard videos/<slug>/storyboard.json --facts videos/<slug>/facts.json --verify videos/<slug>/verify.json --out videos/<slug>/review. Tell the user to open videos/<slug>/review/review.html. Summarize: the claim, scene list, word count and estimated length, each fact with its source check, and every warning. Ask for approval or edits. STOP and wait.
7. Produce. After approval: npm run produce -- --storyboard videos/<slug>/storyboard.json --facts videos/<slug>/facts.json --out out/<slug>. It takes about two minutes. If it rejects the length or a scene is too short, change the narration, re-run check, produce again (voice audio is cached by text). Report the file path, length and loudness. Say plainly what you did not judge: voice quality, pronunciation, pacing and taste. Ask the user to watch it.

When something goes wrong

• A check message you do not understand: it names a scene id; open that scene in rules.md for its limits. Do not guess the fix.
• The fact and the scene disagree: reopen the source. Correct whichever is wrong from the source, never by copying one onto the other.
• A map region is not found: use the atlas spelling the message suggests ("United States of America"); regions must overlap the focus box.
• Voice problems (network): npm run produce needs internet for Edge TTS; --voice standin gives silent-ish placeholder audio for a dry run only.
• Setup missing: run npm install and npm run setup:tts once.

Output to the user

Keep it short: the file path, what the video claims, length, loudness, the facts and sources used, and any warning you accepted and why.