/storyboard-architect

name: storyboard-architect
description: Turn a video brief into a storyboard and shot list with shot specs, timing, on-screen text and per-shot rationale. Use when the user asks for a storyboard, a shot list, shot-by-shot beats or structured pre-production for a video, or hands over a script or concept to break into shots. Produces run.json, storyboard.md, shots.json, text-overlays.json and brand-lock.snapshot.md. It plans the video; it does not render it. Pairs with visual-prompt-forge, visual-asset-critic and storyboard-html-preview.

Storyboard Architect

You are turning a creative brief into a deterministic storyboard. The output is a set of files an editor, agency, or developer can act on without asking follow-up questions.

This is not a creative-writing exercise. The output is a spec.

When to use

Trigger this skill when the user:

• Asks for a storyboard or shot list for a video ("storyboard a 30-second explainer for...", "shot list for a TikTok ad about...")
• Asks to plan shots, break out beats, or write a shot list
• Hands over a script, brief, or concept document expecting structured pre-production output
• Mentions a beat framework by name (Hero Trilogy, Pain-Proof-Promise, etc.)
• References an existing brand-lock file or pack

If the user only wants prompts for an image generator (no narrative structure), use `visual-prompt-forge` directly instead.

What you produce

For every storyboard run, create this exact set of files in the working output directory:

output/
├── run.json                   # Run identity + every input pinned by content hash
├── storyboard.md              # Human-readable, structured per shot
├── shots.json                 # Machine-readable, schema in templates/shots.schema.json
├── text-overlays.json         # On-screen text + timing
└── brand-lock.snapshot.md     # Frozen copy of the brand-lock used (audit trail)

`run.json` is what makes the rest of the tree auditable later. A filename says nothing about the bytes behind it, so the snapshot sitting next to a set of frames is not proof that it is the snapshot they were built from. The hashes in `run.json` are that proof. Write it once, as the last step, after the other four files are final. Everything in `run.json` except `rounds` is written once and never edited. `rounds` is append-only: `visual-prompt-forge` adds one entry per prompt round and never changes an earlier one.

If the user asks for image prompts or HTML preview, hand off to `visual-prompt-forge` or `storyboard-html-preview`, those skills consume `shots.json` directly. Don't try to do their job here.

Where the tools and packs are

After `./install.sh`, the validators and helpers are in `~/.claude/shotkit-tools/` and the brand packs are in `~/.claude/shotkit-brand-packs/`. A `--project` install puts both under `./.claude/` instead. From a repo clone they are `tools/` and `brand-packs/`. The commands below give the installed path first and the clone path second. The tools need `pip install pyyaml jsonschema`.

Inputs

You need these. If any are missing, ask before drafting.

| Input | Required? | Default if absent | |---|---|---| | Brief (problem, audience, goal) | Yes | Ask | | Total duration | Yes | Ask | | Aspect ratio | Yes | Ask (16:9, 9:16, 1:1) | | Beat framework | No | Suggest based on brief | | Brand-lock file path | No | Use `~/.claude/shotkit-brand-packs/_template.md` (clone: `brand-packs/_template.md`) and flag the gap | | Voiceover style (VO present, on-screen only, captions) | No | Ask if unclear | | Target generator(s) for downstream prompts | No | Note as "to be specified" | | Audit findings, `brand/audit-findings.json` from whystrohm-audit | No | Skip Step 1b |

Workflow

Follow this sequence. Don't skip steps even if the brief seems simple.

Step 1. Read the brand-lock

If a brand-lock file path is provided, read it first. Extract:

• Palette (hex)
• Typography
• Mood descriptors
• "Never" list (what this brand will never do visually)
• Motion language
• Voice tone
• Aspect-ratio preferences

If no brand-lock is provided, copy `~/.claude/shotkit-brand-packs/_template.md` (from a clone, `brand-packs/_template.md`) into the output as `brand-lock.snapshot.md` with a note: `# UNCONFIGURED, using template defaults. Recommend providing a real brand-lock for production work.`

Step 1b. Read the audit findings, if there are any

If the user points at `brand/audit-findings.json`, or it sits in the project's `brand/` folder and the brief is for the same company, read it. Its format is `contracts/audit-findings.v1.schema.json` in this repo. Check `contract` is `audit-findings` and `version` is `"1"` before using it.

• The first of `top_gaps` is a candidate for the pain or world beat: the problem the film

answers.

• `rewrite.after` is a candidate overlay line. Use it only as written. A bracketed

placeholder in it means the proof is missing, so leave that line out rather than filling it.

• Name the file and its `audited_at` in the Brief section of `storyboard.md`.

The brief still decides. Findings inform the beats; they never replace what the user asked for.

Step 2. Pick the beat framework

Read `references/beat-frameworks.md`. Pick the one that matches the brief. Common cases:

• Pain-reframe-promise → conversion content
• Hero Trilogy → product hero films
• Founder Explainer → personal-brand content
• Content Spiral → kinetic typography / opinion pieces

If none fit cleanly, build a custom beat structure but document why in `storyboard.md` rationale section.

Step 3. Block out timing

Read `references/timing-rules.md` for the math. Default cadence:

• Hook beat: 0–2 seconds
• Pain/setup: 2–4 seconds (for 15s), 2–6 seconds (for 30s) or 2–10 seconds (for 60s)
• Proof/reframe: middle third
• Promise/CTA: final 3–4 seconds (for 15s), 4–6 seconds (for 30s), 6–10 seconds (for 60s)

Don't fight the framework. If the brief and the duration disagree, surface the disagreement before