shotkit

shotkit

From a brief to an on-brand storyboard, with prompts for every generator and every frame checked.

Five Claude Skills that turn a creative brief into a production-grade storyboard with model-specific image prompts, on-screen text specs, an HTML preview, and a versioned audit trail, plus a brand-lock extractor that onboards a brand from its existing assets. Built by WhyStrohm. Apache 2.0.

git clone https://github.com/whystrohm/shotkit.git
cd shotkit && ./install.sh

That installs all five skills into ~/.claude/skills/. Restart your Claude Code session and they're live.

The loop is one real Shotkit run: the brief, the brand lock, shots.json, the storyboard, and the generated frames with the critic's verdict on each. Two shots came back REVISE; you can watch their re-rolled frames replace them and land ACCEPT. A silent MP4 of the same loop is at docs/images/demo.mp4. The install film on whystrohm.com shows the same pipeline, from one sentence to every asset.

---

What it does

You describe a video. The kit produces a complete pre-production package:

output/
├── run.json                   # Run id + every input pinned by content hash
├── storyboard.md              # Human-readable, shot-by-shot
├── shots.json                 # Schema-validated, machine-readable
├── text-overlays.json         # On-screen text + timing
├── brand-lock.snapshot.md     # Frozen brand state at generation time
├── prompts/round-1/           # Per-generator prompts, copy-paste ready
│   ├── midjourney.txt
│   ├── flux.txt
│   ├── ideogram.txt
│   ├── gpt-image.txt
│   ├── nano-banana.txt
│   ├── seedream.txt
│   ├── kling.txt              # Motion video (default)
│   ├── veo.txt                # Motion: dialogue/lipsync + native audio
│   ├── seedance.txt           # Motion: multi-shot sequences
│   └── hailuo.txt             # Motion: budget iteration
├── frames/round-1/            # Your generated frames
├── critiques/round-1/         # One verdict per shot, hashing what it reviewed
└── preview.html               # Single file. Shareable. Printable. Brand-aware.

Files. Not panels. Not a SaaS dashboard. Files an editor, agency, or developer can act on without asking follow-up questions.

Everything is addressed by round and shot, so no two writes land on the same path. Two people can work one project without overwriting each other's verdicts, and round 2 never destroys the prompt that produced round 1's frames.

---

The five skills

Skill	What it does
brand-lock-extractor	Brand assets (URL / PDF / screenshots) → validate-ready brand-lock.md
storyboard-architect	Brief → structured storyboard (storyboard.md + shots.json)
visual-prompt-forge	Shot data → model-specific prompts for 10 generators (6 stills, 4 motion)
visual-asset-critic	Generated image + intent → markdown critique + machine-readable critique.json
storyboard-html-preview	Storyboard files → single-file shareable HTML

They work alone. They work better together, the critic writes a machine-readable verdict the prompt-forge can act on, so generate → critique → revise → re-critique runs as a closed loop. See docs/the-qa-loop.md. They work in Claude Code, Claude.ai, and the Claude API.

---

Why this exists

Every storyboard tool on the market is a SaaS app with a UI you log into. You upload a brief, you get illustrated panels, you export. The output never leaves the platform.

That's not how serious teams work. Serious teams want:

• Files, not cloud-locked panels
• Audit trail, not vibes. Every shot has rationale, every prompt is reproducible, every brand parameter is versioned.
• Brand lock, not "AI reads your URL". Explicit brand parameters that compose deterministically across every shot.
• Model agnosticism. Prompts adapt to whichever image generator you're using this month.
• No vendor lock-in. Markdown, JSON, HTML. Open formats only.

shotkit is the pre-production method WhyStrohm uses on its own work. We're publishing the methodology because the methodology isn't the moat. The operator is.

Read more in docs/why-this-exists.md.

---

Why this isn't another storyboard tool

The category isn't empty. It's full of tools that solve the wrong half.

• Provenance you can check, not just claim. Every run freezes brand state and records a content hash for every input, prompt, and reviewed frame. Six months later you can answer "what brand version was this built against" and prove the files have not moved since, because validate_provenance.py recomputes the hashes. A frame regenerated after its review fails that check instead of passing quietly on a stale ACCEPT.
• Ten generators, one spec. The same shot data adapts to six stills generators (Midjourney, Flux, Ideogram, GPT Image, Nano Banana, Seedream) and four motion-video models (Kling, Veo, Seedance, Hailuo). Every other storyboard skill on GitHub locks to one generator family.
• Files, not panels. The output is structured Markdown and JSON an editor, motion designer, or developer can act on. No dashboard, no export step, no platform.
• Methodology over pipeline. The pack stops at prompts and specs. Generator APIs churn monthly, the methodology stays stable. The pipeline lives where it belongs, in the operator's tooling.

---

60-second example

Drop this into a Claude Code session with the skills installed:

"30-second founder explainer for WhyStrohm. We help founder-led brands build content infrastructure instead of running content like a hobby. Pain-reframe-promise. Use brand-packs/whystrohm.md as the brand lock. Aspect 9:16."

Claude produces the full output/ set. Open output/preview.html in any browser. Print it. Share it. Hand it to an editor.

A complete worked example lives at skills/storyboard-architect/examples/30s-pain-proof-promise/. Clone the repo and open preview.html in that folder to see what the deliverable looks like.

---

Round-trip workflow

The complete loop, idea to revised image:

1. Brief describes the video.
2. storyboard-architect produces run.json, storyboard.md, shots.json, text-overlays.json, brand-lock.snapshot.md.
3. visual-prompt-forge writes a prompt file per generator under output/prompts/round-1/.
4. tools/copy-prompt.py pipes one shot's prompt to the clipboard. Paste into the generator UI.
5. The generator returns an image. It goes in output/frames/round-1/shot_NN.png.
6. visual-asset-critic scores the frame against the shot spec and brand-lock, writing critiques/round-1/shot_NN.critique.json with the hash of the frame, the prompt, and the brand-lock it judged.
7. tools/validate_provenance.py re-checks every hash and reports which shots are still open.
8. On REVISE, visual-prompt-forge revision mode re-emits prompts for only those shots into round-2/. On REJECT, it stops and asks: a REJECT means no fix path exists.
9. Repeat from 5 until --require-accept exits 0. It exits 0 only when every shot in shots.json has a critique and every latest verdict is ACCEPT.

python ~/.claude/shotkit-tools/validate_provenance.py output/ --require-accept || echo "work remains"
# from a repo clone: python tools/validate_provenance.py output/ --require-accept

Files at every step. See docs/the-qa-loop.md for the full loop and skills/visual-asset-critic/examples/worked-run/ for a worked two-round example: every file and hash in place, with stand-in frames.

---

The methodology

Four ideas. None negotiable.

1. Five-layer prompt anatomy. Every image prompt is composed from locked layers: Brand Lock, Series Lock, Shot Spec, Text Layer, Generator Adapter. Change a brand color once. Every prompt updates. See docs/the-five-layer-prompt.md.

2. Versioned brand state, pinned by hash. Every run snapshots the brand-lock it was built against and records its SHA-256 in run.json. Brand changes later? The snapshot stays frozen, and if someone overwrites it, the hash mismatch says so. A filename alone never proved anything, which is the whole reason the hashes are there. See docs/audit-trail-pattern.md.

3. Text never gets baked into images. On-screen copy is a separate layer with its own timing, font, and animation spec. Always composited after generation. AI text rendering is not production-ready in 2026; treat text as a separate compositing pass.

4. Per-shot rationale. Every shot has a rationale field. Why this beat. Why this duration. Why this framing. Why this on-screen text. Decisions are logged so they can be challenged.

---

Brand packs

A brand pack is a single Markdown file that locks palette, typography, voice, and visual rules for a project. Three live in this repo:

• brand-packs/_template.md. Empty starter.
• brand-packs/whystrohm.md. Flagship example, the real WhyStrohm brand: dark ground, one accent, Archivo and IBM Plex Mono.
• brand-packs/examples/saas-clean.md. Neutral B2B SaaS reference.

Roll your own from the template. Or generate one from a site, a brand book or screenshots with the brand-lock-extractor skill in this repo.

See brand-packs/README.md for the full pattern.

---

Where this stops, where the pipeline starts

shotkit produces specs and prompts, not rendered images or videos. The boundary is deliberate:

• In scope. The methodology, the structure, the prompts, the audit trail.
• Out of scope. API integrations to image generators or voice tools, the video render pipeline, publishing.

If you want the version where this is wired into a video render pipeline and publishing across multiple brands: whystrohm.com. The methodology is open. The operator is paid.

See docs/connecting-to-generators.md for how teams typically wire it up themselves, and docs/connecting-to-video-pipelines.md for how shots.json maps to programmatic video frameworks.

---

What comes after shotkit

shotkit is one stage in a longer content infrastructure pipeline:

1. Brief captured from the founder
2. shotkit turns the brief into structured pre-production files
3. Image generators consume the per-generator prompt files
4. visual-asset-critic reviews each generated frame against its shot spec
5. Approved frames feed into a programmatic video framework
6. The framework renders the final video
7. Publishing tools post per-platform copy from text-overlays.json

shotkit owns step 2. Steps 3 through 7 are file boundaries, not API integrations. Each downstream tool reads files. Nothing is coupled beyond the schema.

For wiring it up yourself, see docs/connecting-to-generators.md and docs/connecting-to-video-pipelines.md. For the operated version, whystrohm.com.

---

Companion tools

shotkit is part of a broader WhyStrohm open-source ecosystem of brand-infrastructure tools:

• media-tsunami brand voice extraction. Writes a CLAUDE.md and a brand-config.json from a site.