repo_demo_video_kit v1.0.0

name: "repo_demo_video_kit" description: "Turn a codebase into demo video preparation assets before any recording starts: mine the repo for what is actually true, build an evidence backed claims list, write a demo script and storyboard, plan safe demo commands, and generate static review frames. Use when a repo, CLI, library, or agent project needs a demo and the team wants every line in the video checked against the code first. Ships a claims verifier, a repo miner, a storyboard builder, and a worked kit for a small CSV tool."

Repo Demo Video Kit

Purpose

Most bad demo videos fail before recording starts. The script says the tool does things the code does not do, the commands were never run in order, and nobody looked at the frames until the edit. This skill is the prep stage only: mine the repo, prove every claim, write the script and storyboard, plan the exact commands, and review static frames. Recording, editing, and publishing belong to demo video production skills. This kit hands them a plan that is already true.

Unlike a single CLI plugin that only renders a terminal GIF, this kit works for any repo shape, CLI, GUI, library, or agent project, and it gates the whole plan on a claims check that runs against the real code.

Workflow

1. Mine the repo, read only

• Run python3 scripts/mine_repo.py <repo> --out inventory.md from this skill folder, with the target repo path filled in.
• Read the inventory for what it is: README intro and headings, entry point candidates, test files, README code blocks, and recent commits from git log.
• Treat every inventory line as a lead, not a fact for the script. A README can be out of date. A code block can name a flag that was renamed.
• Note what is missing as plainly as what is present. No tests, no help text, and no sample data are findings, and they shape what the demo can honestly show.

2. Build the claims list and verify it

• Write claims.csv with the header id,claim,evidence_type,evidence. One row per checkable sentence that might end up in narration or on screen.
• Use the evidence types in references/claims-and-evidence.md: file_exists, file_contains, command, and output_contains. Quote patterns narrowly, at the argument definition or function that does the work, not at a comment that mentions it.
• Run python3 scripts/verify_claims.py --repo <repo> --claims claims.csv. It prints PASS, FAIL, or BLOCKED per claim and exits non zero unless every claim passes.
• Fix a failed claim in one of three ways: fix the code, fix the claim to match the code, or cut the line. Re-run the verifier after any change. Blocked commands are not run at all, by design.
• Put no number, count, speed, or percentage in the script unless a command in this session produced it and a claims row points to that output.

3. Write the script as scenes

• Write scenes.csv with the header scene,seconds,visual,narration,claim_id,command. Quote any field that contains a comma. See references/storyboard-template.md for field rules.
• Use the default order for a developer tool: Problem, Install check, Smallest example, Result, Next step. The smallest example is the core of the video and should be its largest scene.
• Keep narration to exact spoken lines, short sentences, written at about 130 words per minute. Every factual line carries the claim_id that passed in step 2.
• Answer the questions a developer viewer is actually asking: how do I install it, what is the smallest thing that works, what does the output look like, what does it replace. Skip lines that answer none of them.

4. Plan the safe demo commands

• Write the command plan following references/safe-demo-commands.md: a named start commit, setup commands listed separately and kept off screen, on-screen commands in playback order with an expected result per command, and a never-on-screen list.
• Keep on-screen commands read only by default, short enough to read in a small player, and run only against sample data made for the demo. No real customer files, no production data, no tokens or personal paths in any frame.
• Run the whole plan once in a fresh shell before approving it. A command that fails in the dry run is a finding about the repo. Fix the plan, the sample data, or the claim, then run the verifier again.

5. Generate the storyboard and static review frames

• Run python3 scripts/storyboard.py --scenes scenes.csv --out-dir kit-out. It writes storyboard.md with per scene timing and word budgets, and frames.html with one static 16:9 frame per scene.
• Fix every warning before recording. Over budget narration means cut words or add time. A checkable line with no claim_id means add the claim and verify it, or soften the line.
• Open frames.html and do the review pass in the template: the story reads with the sound off, text is readable at small size, every factual line is claimed, no frame leaks private data, and the last frame gives one next step.
• Approve the kit only when the verifier passes clean, the command plan dry run passes clean, and the frames pass review. Any one failure holds the recording.

Output Contract

Deliver a demo prep kit folder containing: inventory.md from the repo miner, claims.csv with a passing verifier run and its output saved, scenes.csv, storyboard.md, frames.html for static review, and a safe command plan with setup, on-screen, and never-on-screen sections. Add a one paragraph note naming the start commit, the total planned runtime, and any claim that was cut and why. No recording files are part of this contract.

The worked example in references/worked-kit.md shows the full shape for a small tool, using the sample repo, claims, and scenes in examples/. Its verifier run passes 6 of 6 claims and its storyboard totals 72 seconds across 5 scenes with 0 warnings.

Operating Rules

1. No claim without evidence in the repo today. Opinion and plans are labelled as such or cut. Never invent numbers, dates, features, or output.
2. Prep ends before recording. If a request wants capture, editing, or publishing, hand the approved kit to a demo production skill instead of expanding this one.
3. Read only mining. The miner, the verifier, and the command plan dry run never edit the target repo, install from the network, push, deploy, or delete anything.
4. Sample data only on screen. Build a small fixture that shows the real behaviour, including one messy or edge case, and keep real data out of every frame.
5. One source of truth per asset. claims.csv drives narration, scenes.csv drives the storyboard and frames. Never hand edit generated files, regenerate them.
6. A failed check holds the kit. Quality beats schedule here: report the failing claim or command plainly, leave the kit unpublished as a demo plan, and fix the underlying repo or the line.