| name | video-script |
| description | 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 |
| metadata | {"title":"Video Script","category":"basics","var":"","tags":["content"]} |
${var} — Selector: <source> [--minutes N].
repo:<owner/repo> → script about that repo's latest update wave (README + recent releases/commits decide what "the update" is).<url> → script about that product page / doc / announcement.<topic> (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
- 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.
- 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.
- 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:
# <project> — "<Working Title>" — Video Script
**Runtime target:** ~M:SS
**Framing:** receipts-first (open on <the artifact>)
**Byline:** <the project's public handle>
**One-line pitch:** <one sentence, no hype>
**Rev:** v1, ${today} — plain-language pass baked in; every technical term explained in one line or cut.
Chapters, each with a time range:
## <Chapter name> — 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
-
Write the script to output/video-scripts/${today}-<slug>.md (shell redirection; mkdir -p first).
-
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:
SCRIPT_URL="${GITHUB_SERVER_URL:-https://github.com}/${GITHUB_REPOSITORY}/blob/main/output/video-scripts/<file>.md"
-
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.
