# Video Script > Turn a repo, product page, or update into a recording-ready video script in a receipts-first format - verifies every claim against live sources, then writes timestamped VO + on-screen direction with a plain-language glossary, assets checklist, anti-tells, and a verify-before-recording list - Skill: `aaronjmars/video-script` (Agent Skill) - Install (CLI): `npx skillmds@latest add aaronjmars/video-script` - Raw SKILL.md: https://api.skillmd.com/api/skills/aaronjmars/video-script/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: aaronjmars (https://skillmd.com/u/aaronjmars) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/aaronjmars/video-script --- > **${var}** — Selector: ` [--minutes N]`. > > - **`repo:`** → script about that repo's latest update wave (README + recent releases/commits decide what "the update" is). > - **``** → script about that product page / doc / announcement. > - **``** (anything else non-empty) → script about that topic; research it first. > - **empty** → pick the most script-worthy update from the last 7 days of `memory/logs/` (a shipped feature, a release, a milestone with receipts). If nothing qualifies, log `VIDEO_SCRIPT_NO_SOURCE`, send no notification, and exit clean. > - **`--minutes N`** anywhere → runtime target (default 4; ~150 spoken words per minute). > > Examples: `"repo:aeonfun/aeon --minutes 6"`, `"https://example.com/launch"`, `"our new payments integration --minutes 3"`. Today is ${today}. Write a recording-ready video script. No placeholders — every number, address, and date in it must be verified this run. ## Shared preamble 1. Read `memory/MEMORY.md` and the last 7 days of `memory/logs/` — know what has already been covered, and don't script the same story twice. 2. If a `soul/` directory exists, read `soul/SOUL.md` and `soul/STYLE.md` for voice calibration. The script is *the operator talking to a smart friend* — if `soul/` is empty, default to terse, direct, first-person. 3. Parse `${var}` per the selector above into `source` + `minutes`. ## Step 1 — Research and verify (never skip) The format is called receipts-first because the receipts are real: - Fetch the live source **now** (WebFetch / `gh api` for repos — README **and** recent releases/commits). Do not write numbers, counts, addresses, or dates from memory. - Collect concrete verifiable artifacts: contract addresses, live dashboards, version numbers, dollar figures, dates. These become the cold open and the Receipts section. - Every claim you could NOT verify either gets cut or becomes a checkbox in "Verify before recording". ## Step 2 — Find the angle The cold open is never the pitch. It is the single most concrete, verifiable, surprising fact — shown, not claimed (a live dashboard, a list of on-chain addresses, a terminal). Test: could a skeptic check it in 30 seconds? The flex is usually the *credibility mechanism* (immutability, safety gates, audit trail, reproducible tests), not the feature list. ## Step 3 — Write the script Header block: ```markdown # — "" — Video Script **Runtime target:** ~M:SS **Framing:** receipts-first (open on ) **Byline:** **One-line pitch:** **Rev:** v1, ${today} — plain-language pass baked in; every technical term explained in one line or cut. ``` Chapters, each with a time range: ```markdown ## — 0:00 – 0:25 **VO:** > Spoken text as blockquote. Short sentences. Operator voice. **On screen:** - Concrete shot list: screencaps, terminals, motion graphics, captions in `backticks`. ``` Canonical arc (adapt, don't force): **cold open** (the receipt, no greeting) → **context/problem** (one plain-language line for the underlying tech) → **how it works** (the mechanism, credibility story first) → **what's new** or **the demo** → **straight talk** (limits, flat delivery — every script has this section; it is a feature, not a concession) → **close + CTA** (one action). After the chapters, ALWAYS: - **Plain-language glossary** — jargon → the phrasing used on screen, plus terms deliberately cut. - **Assets checklist** — everything to capture or build; mark what must be captured day-of. - **Anti-tells checklist** — the voice rules below plus per-video specifics (what not to oversell, whose failures not to dunk on). - **Verify before recording** — dated checkboxes for every volatile fact, each with where to re-check it. - **Receipts** — the verified facts with sources and the date verified (mandatory when the video makes on-chain or factual claims). ## Voice rules (the anti-tells) - Banned: "In this video", "Let's dive in", "game-changer", "insane", "mind-blowing", "revolutionary", "trustless" (name what enforces it instead). - Short declaratives; read VO lines aloud mentally before keeping them. - Numbers stay conservative — round down; "tens of millions" beats a precise figure that might drift. - Incidents and competitors are stakes, not villains — flat delivery, no dunking. - The safety/verification story outranks the feature list. - Every technical term gets one plain-language line or gets cut. - On-screen text must NOT mirror the VO verbatim — reword it so the viewer isn't reading what they're hearing. - Never reference private forks or internal accounts — point at the upstream/public repo. ## Step 4 — Deliver 1. Write the script to `output/video-scripts/${today}-.md` (shell redirection; `mkdir -p` first). 2. Notify with `./notify -f /tmp/video-script-notify.md` (write the body under `/tmp/`, never `memory/` or `output/`): the working title, runtime, the chosen angle in one line, one thing deliberately left out, and a **clickable** link to the script built from the run's environment: ```bash SCRIPT_URL="${GITHUB_SERVER_URL:-https://github.com}/${GITHUB_REPOSITORY}/blob/main/output/video-scripts/.md" ``` 3. Log to `memory/logs/${today}.md` under a `### video-script` heading: source, angle, runtime, output path, and any claims deferred to day-of verification. Status codes: `VIDEO_SCRIPT_OK` on success, `VIDEO_SCRIPT_NO_SOURCE` when `${var}` was empty and the logs offered nothing script-worthy. ## Limits - This writes the script; it does not record, edit, or generate footage. The assets checklist is a to-do list for a human (or other skills). - Verification is only as fresh as this run — volatile facts must still be re-checked day-of; that is what the "Verify before recording" section is for. - If the source is private or unreachable, say so and stop — a script built on unverifiable claims defeats the format.