animated-explainer

Files (6)

• SKILL.md
• reference.md
• check-page.js · scripts/
• export-film.js · scripts/
• shoot-beats.js · scripts/
• voice-film.py · scripts/

SKILL.md (first lines)

# Animated Explainer

> ℹ️ **First, set expectations:** before anything else, print one short line with this skill's version and its most recent change — the top entry of `metadata.changelog` above — e.g. `animated-explainer vX.Y — recent: <summary>`. Then proceed.

ultrathink

## Purpose

Build an **animated explainer of how a real system works** — rendered live to a `<canvas>`
from the system's **own data**, so it regenerates on every publish and can never drift from
what the product reports.

**The thesis: a data-driven film, not a video.** An exported MP4 is stale the day the data
moves, and it quietly becomes a lie. A film that reads `data/*.json` at render time changes
when the system changes. (This is testable: on the forecasting build, a data refresh landed
mid-deploy and the calibration curve visibly redrew.)

**Use this when** someone wants to *show a mechanism* — how a system works, why it's
trustworthy, what happens to one item as it moves through.

**Don't use this for** static diagrams or illustrations — a diagram skill (if your
workspace has one) is the right tool there. This skill is specifically **time-based motion
driven by live data**.

## State Dependencies

| Source | Location | Read | Write |
|---|---|---|---|
| The system's real data | product repo `data/*.json` (or equivalent) | ✅ | ❌ never |
| The system's source of truth | `ARCHITECTURE.md`, papers, specs — **not** published artifacts | ✅ | ❌ |
| Brand tokens | the product's `globals.css` / theme file | ✅ | ❌ |
| Working film | `<scratch>/film.html` (standalone, no build) | ✅ | ✅ |
| Shipped component | product repo `components/**/explainer.tsx` | ✅ | ✅ |
| Verification rigs | `scripts/shoot-beats.js`, `scripts/check-page.js` (this skill) | ✅ | ❌ |
| Export rigs | `scripts/export-film.js`, `scripts/voice-film.py` (this skill) | ✅ | ❌ |
| Narration script | `<film dir>/narration.json` (timed lines, next to the film) | ✅ | ✅ |
| Voiced export | `<film dir>/export/` — MP4 stamp + `vo_clips/` TTS cache | ✅ | ✅ |

## Composes

| Skill | When |
|---|---|
| a site-publishing skill | Final step, only if the film ships to a live site and the user has asked for a deploy. Optional — this skill never requires it. |

## Credentials & cold start

Building, verifying, and shipping a film needs **no credentials at all**. Only the optional
voiced export (Step 11) reads any:

| Key | Needed for | Missing → |
|---|---|---|
| `ELEVENLABS_API_KEY` | Step 11 TTS narration | Fail fast with `ELEVENLABS_API_KEY not set — add it to this agent's credentials`; every earlier step still runs, and the silent MP4 export is unaffected. |
| `ELEVENLABS_VOICE_ID` | default voice for Step 11 | Optional — `voice_id` in `narration.json` or `--voice` overrides it. Absent with no override → the tool stops and names the three ways to supply it. |
| `PLAYWRIGHT_DIR` | pointing the render scripts at an existing playwright install | Optional — the scripts resolve playwright from the caller's cwd first, then this variable, then the skill directory. |

Script paths below are relative to **this skill's directory**; run them from there, or
prefix with the directory the skill was injected into.

---

## Core principles

These are load-bearing. Each one was paid for.

### 1. The data is the story's boss — interrogate it before you design the arc

Decide what's **true** before you decide what's **compelling**. Concepts must die here; that
is the step working, not failing.

Two died on the forecasting build, both after the storyboard felt great:
- *"watch it get better over time"* — the metric was **flat** (0.217 → 0.188 → 0.210). Noise,
  not learning. Animating it would have faked the one number the brand rests on.
- *"performance improving"* curve — the sample was **back-loaded** (Q1 spanned 3 months, Q4
  spanned 1 day), so the apparent decline was a **sampling artifact**, not improvement.

Run the numbers yourself. Check the **shape and the sampling**, not just the headline.
Finding this at storyboard costs an hour; finding it after a render costs a week; not finding
it costs your credibility.

### 2. Read the source of truth, not the published artifacts

Published data dirs are a *curated snapshot* of a system, not the system. On that build the whole
first film was built from the website's `data/` and got the architecture **wrong** — the real
mechanism was in `ARCHITECTURE.md` and an unpublished paper. Find the design docs.

### 3. One concrete worked example beats any amount of abstraction

Follow **one real item end to end**. The film only worked once it became a single real
forecast — *said 88%, world said no* — traced from question to consequence.

**Prefer a failure.** A miss shows the machine doing its job, is impossible to read as
cherry-picking, and gives every downstream loop something real to react to.

### 4. Explainer, not advertisement

Assume the viewer knows nothing. It must read **with** a voiceover on top and **without** one.
Open on the **problem**, not the architecture — state what's broken, then reveal the machine
as the answer. A hook is not a flourish; it's the reason to keep watching.

### 5. Separate the mechanism from the numbers

Statistics clutter an explanation. Carry the mechanism with **symbolic marks**, then put real
figures at the very end — or nowhere. If a mark is not 1:1 with a thing, **say so on screen**
(`1 dot ≈ 30 beliefs`). If something is too rare to be field scale (17 of 44,510 = 0.6 of a
dot), draw it 1:1 as an annotated callout and label it — never silently mix scales.

### 6. Nothing teleports

If a thing appears somewhere new, **animate it getting there**. A chart that materialises is a
cut; a chart that dots visibly *fall onto* is an explanation. This was the single biggest
"it doesn't explain it better" complaint on that build, and fixing it changed the film.

### 7. Lock the layout

One circuit. Nothing crosses anything. Spaghetti beziers read as *complexity*, not as a
system. A horizontal spine + a return rail + entities sitting **on** the rail reads instantly.

### 8. Show the part that doesn't work

From Abilityai/trinity-skills, Apache-2.0.

More from Abilityai/trinity-skills