---
name: ai-training-video
description: Produce a narrated 16:9 corporate training or software how-to video on any topic - script, local AI voice, step-by-step app screens with highlights and taps, an AI presenter lip-synced by HeyGen, animated scenes, motion-graphics recaps, word-by-word captions and a music bed. Use when someone wants to make a training video, how-to video, onboarding video, software walkthrough or explainer, or to set up the tools for one.
---

# AI Training Video

Turns source material (a user guide, a procedure, notes) and a few screenshots into a finished 1080p training video, the
way a small video team would: script, voice, edit, motion graphics, captions, music. Everything runs on the person's own
computer through `scripts/run.py`, except three paid AI steps (images and scene animation via OpenRouter, the talking
presenter via HeyGen), and every paid step keeps what it made so nothing is paid for twice.

You (Claude) do the thinking - script, edit plan, highlight positions, checks - and give the person one command at a time
to run, or run it yourself when you have a terminal. Read the reference file for a stage before starting that stage:

| Stage | Read |
|---|---|
| First time on this computer | `reference/setup.md` |
| Writing the script and planning the edit | `reference/workflow.md`, then `reference/project-format.md` |
| Choosing the look: screen modes, motion graphics, captions, music | `reference/design.md` |
| Something went wrong | `reference/troubleshooting.md` |

`examples/larkspur-expenses/` is a complete small project (a made-up company and app): copy its patterns.

## The process

1. **Setup (once).** Check `python scripts/run.py setup --test`. If anything is missing, walk the person through
   `reference/setup.md`: Python, ffmpeg, then `python scripts/run.py setup` (add `--chatterbox` for voice cloning), then
   the `.env` keys. Don't go further until the checks pass.
2. **Brief.** `python scripts/run.py new <project>` makes the folder. Collect what `templates/brief.md` lists - ask only
   for what you can't find in the material they've given you, in one short round of questions:
   title, audience and goal, source material, brand (logo, colour), screenshots (and recordings), presenter yes/no and who,
   voice and accent, screen mode, setting for the images. Fill in `project.json`.
3. **Script.** Write `script.txt` from the source material (format and writing rules in `reference/workflow.md`):
   an opening, numbered steps that match the real screens exactly, an optional halfway recap for videos over ~4 minutes,
   a closing recap and a closing line. Show it to the person and get a yes before any audio is made.
4. **Voice.** `voices` to audition, the person picks, then `narrate` and `pick`. Read pick's "CHECK THESE" list and fix
   each one (a respelling in `voice.say`, or a re-read with `--force`). Ask them to listen to `audio/narration_preview.wav`.
5. **Edit plan.** Write `shots.json`: which screen shows when, highlight boxes and taps anchored to spoken words, callouts,
   topic chips, recap graphics and the reel shots (`reference/project-format.md`). Use `locate` to get exact boxes from
   the screenshots, and look at the marked-up images it saves. Then `check` until it reports no problems.
6. **Preview stills (free).** `stills <project> --sheet`, then `--steps 1 2 ...` for the steps. Look at every still
   yourself before showing the person: boxes on the right element, nothing lingering after the screen changes, captions
   not covering what matters, text not clipped.
7. **Images (paid).** `refs` makes the presenter, scenes and plates; show the person `refs/contact.jpg` and remake any
   they don't like (`refs <project> <id> --force`). Plate mode: then `plates`, and check `plates/check_*.jpg`.
8. **The video.** `video <project>` animates the scenes, makes the presenter clips, renders, makes the music and mixes:
   `out/<title> - 1080p.mp4`, a 720p preview and an `.srt`. `video <project> --no-ai` makes a free version with stills
   and slow zooms in place of the paid clips - good for a first full review.
9. **Review loop.** The person watches and gives timestamps. Map each note to its fix (`reference/troubleshooting.md` has
   the common ones), re-run only what changed, and re-render.

## Rules that matter

- **Accuracy first.** Every step must match the real screens: button names exactly as written on screen, in the order the
  screens show. If the guide and the screenshots disagree, ask.
- **Privacy.** Real passwords, test credentials, other people's names and personal details must never reach a frame,
  caption or the narration. Use `redact` and check every cleaned screen yourself.
- **Consent and licences.** A cloned voice or a real person's face needs that person's permission. Kokoro (Apache-2.0),
  Chatterbox (MIT), Inter (OFL) and the generated music are free for commercial use; HeyGen and OpenRouter outputs follow
  those services' terms. Say so if the person asks to clone a voice or face they don't have rights to.
- **Spend.** Tell the person what a paid step will roughly cost before they run it (see `reference/setup.md`). Run the
  free `--no-ai` video and stills first so paid steps run once.
- **One command at a time.** Run commands yourself when you have a terminal; otherwise give ones they can paste. Always
  use full paths: `python3 <skill>/scripts/run.py <command> <full project path>`, where `<skill>` is this skill's base
  directory (Windows: `python` and backslashes). Say what each command does and how long it takes. When they paste output back, read it properly - especially "STOPPED", "CHECK THESE" and
  "SEVERE" lines - before moving on.
