Shotkit / Docs / Quickstart
Your first run, in ten steps.
Shotkit writes the plan, the prompts and the critiques. It does not make images or video. You make each frame in the generator you already use, and Shotkit checks it against the brief. The tool output below comes from one real run, the WhyStrohm launch film.
- Step 01Terminal
Install the skills.
Clone and install git clone https://github.com/whystrohm/shotkit.git cd shotkit && ./install.shIt printed (first lines) Installing shotkit scope: user skills: ~/.claude/skills tools: ~/.claude/shotkit-tools packs: ~/.claude/shotkit-brand-packs
The install page has the full output and every option.
- Step 02Terminal
Give the validators Python packages.
A venv for Shotkit python3 -m venv ~/.venvs/shotkit ~/.venvs/shotkit/bin/pip install pyyaml jsonschemaIt printed Successfully installed attrs-26.1.0 jsonschema-4.26.0 jsonschema-specifications-2025.9.1 pyyaml-6.0.3 referencing-0.37.0 rpds-py-2026.6.3
- Step 03Terminal
Check the install.
Run every check PYTHON=~/.venvs/shotkit/bin/python ~/.claude/shotkit-tools/check.sh --quietIt printed (last lines) PASS prompt helper: selftest ───────────────────────────────────────── 23 passed, 0 failed
- Step 04Terminal
Restart Claude Code and confirm the skills.
Claude Code loads skills when a session starts. Restart it, then check the five folders:
List the skills ls ~/.claude/skills/ | grep -E "storyboard|visual|brand-lock"It printed brand-lock-extractor storyboard-architect storyboard-html-preview visual-asset-critic visual-prompt-forge
- Step 05Claude Code
Type the brief.
Open Claude Code in the folder where you want the files, and describe the video in one or two sentences: length, aspect, the feel, and which brand lock to use. This is the brief typed on the example run:
Type in Claude Code 15-second launch film for WhyStrohm. Dark ground, one accent. 16:9. Use the whystrohm brand pack.
storyboard-architecttakes it. It writesstoryboard.md,shots.json,text-overlays.jsonandbrand-lock.snapshot.mdinto./output/, andrun.json, which pins each of those files by SHA-256. If the brief leaves out something it needs, such as the length or the brand, it asks. To use your own brand, copy~/.claude/shotkit-brand-packs/_template.mdand fill it in, or askbrand-lock-extractorto write one from your site.Check the shot plan it wrote:
Validate shots.json ~/.venvs/shotkit/bin/python ~/.claude/shotkit-tools/validate_shots.py output/It printed Validating 1 storyboard set(s) ok output/shots.json All storyboard sets valid (0 warning(s)).
- Step 06Claude Code
Ask for prompts for your generator.
Type in Claude Code Generate Flux prompts for ./output/shots.json.
visual-prompt-forgewritesoutput/prompts/round-1/flux.txt: one block per shot, shaped for that generator. It has adapters for ten: Midjourney, Flux, Ideogram, GPT Image, Nano Banana and Seedream for stills, and Kling, Veo, Seedance and Hailuo for motion. Name as many as you use. - Step 07Terminal
Copy one shot's prompt.
List the shots in a prompt file ~/.venvs/shotkit/bin/python ~/.claude/shotkit-tools/copy-prompt.py output/prompts/round-1/flux.txt --listIt printed 1. # shot_01, world, 0.0-3.5s, EWS high static [1 params line] (904 chars) # params: aspect_ratio=16:9, output_format=png, prompt_upsampling=false, seed=707080 2. # shot_02, hero, 3.5-6.5s, MS eye-level push [1 params line] (894 chars) # params: aspect_ratio=16:9, output_format=png, prompt_upsampling=false, seed=707080 3. # shot_03, hero, 6.5-9.5s, WS overhead push [1 params line] (866 chars) # params: aspect_ratio=16:9, output_format=png, prompt_upsampling=false, seed=707080 4. # shot_04, transformation, 9.5-12.0s, EWS eye-level push [1 params line] (871 chars) # params: aspect_ratio=16:9, output_format=png, prompt_upsampling=false, seed=707080 5. # shot_05, transformation-cta, 12.0-15.0s, EWS eye-level static [1 params line] (882 chars) # params: aspect_ratio=16:9, output_format=png, prompt_upsampling=false, seed=707080Copy shot_03 to the clipboard ~/.venvs/shotkit/bin/python ~/.claude/shotkit-tools/copy-prompt.py output/prompts/round-1/flux.txt --shot shot_03It printed Copied shot_03 prompt to clipboard (866 chars). # params: aspect_ratio=16:9, output_format=png, prompt_upsampling=false, seed=707080
The params line is shown, not copied. Set those values in the generator yourself.
- Step 08Your generator
Make the frame in your generator.
Paste the prompt into the generator, with the params from the line above. Save the image as
output/frames/round-1/shot_03.png: the round, then the shot id. That path is how the critic and the validators find it. This step is the only one that leaves Shotkit. - Step 09Claude Code
Have the critic check the frame.
Type in Claude Code Critique this image against shot_03 in ./output/shots.json.
visual-asset-criticcompares the frame with the shot spec and the brand-lock snapshot and writesoutput/critiques/round-1/shot_03.critique.jsonwith a readable.critique.mdbeside it. The verdict is ACCEPT, REVISE or REJECT, and every issue carries a fix. The file also records the SHA-256 of the frame, the prompt and the brand lock it judged.Validate the critiques ~/.venvs/shotkit/bin/python ~/.claude/shotkit-tools/validate_critique.py output/It printed Validating 8 critique file(s) ok output/critiques/round-1/shot_01.critique.json ok output/critiques/round-1/shot_02.critique.json ok output/critiques/round-1/shot_03.critique.json ok output/critiques/round-1/shot_04.critique.json ok output/critiques/round-1/shot_05.critique.json ok output/critiques/round-2/shot_02.critique.json ok output/critiques/round-2/shot_03.critique.json ok output/critiques/round-3/shot_02.critique.json All critiques valid (0 warning(s)).
- Step 10Terminal
Check what is still open, and build the preview.
The stop condition ~/.venvs/shotkit/bin/python ~/.claude/shotkit-tools/validate_provenance.py output/ --require-acceptIt printed, and exited 0 Validating provenance for 1 output tree(s) ok output (5 shot(s), 5 reviewed, rounds [1, 2, 3]) shot_01: ACCEPT (round 1) shot_02: ACCEPT (round 3) shot_03: ACCEPT (round 2) shot_04: ACCEPT (round 1) shot_05: ACCEPT (round 1) Provenance chain intact.It recomputes every hash, then lists each shot’s latest verdict. It exits 0 only when every shot has a critique and every latest verdict is ACCEPT; otherwise it names the shots still open and exits 1. On REVISE, ask for revised prompts (“Revise the prompts for the shots that came back REVISE”) and the forge writes them to
prompts/round-2/for those shots only. Then repeat steps 7 to 10.Build the preview ~/.venvs/shotkit/bin/python ~/.claude/shotkit-tools/shots-to-html.py output/It printed wrote output/preview.html
preview.htmlis one file with every shot, its frame, its on-screen text and its verdict. Open it in a browser, print it, or send it.
Next
Want it built and run for you? Apply for a free reel