| name | shot-specifier |
| description | Per-shot production specification workflow: takes a completed scene inventory (from scene-inventory-extractor-v2) and decomposes every scene into numbered shots with full directorial direction — actor position and movement, camera mount and motion, lens, lighting setup, practical effects, timing, and clip boundaries. Generates storyboard keyframe images via nanobanana, assembles video generation prompts with model routing, and maintains an asset pipeline with consistent file naming and a generation manifest. Use when a scene inventory exists and the workflow must move from scene descriptions to individual, generation-ready clips. Also trigger when the user mentions "shot list", "shot breakdown", "storyboard", "video prompt", "model routing", "clip generation", or "per-shot direction".
|
Shot Specifier
Takes a completed scene inventory and reference image set as input and produces
generation-ready shot specifications: numbered shots with full directorial direction,
storyboard keyframes, video prompts, model routing, and an asset pipeline.
This skill is explicitly expensive. Generating storyboard images for every shot in
every scene requires many image generation calls. Per-shot video generation is more
expensive still. This cost is the price of consistency and production quality — do not
skip shots or reduce keyframe coverage to save cost unless the user explicitly requests
it.
Input Requirements
Before beginning, verify the following inputs are available:
| Input | Location | Required? |
|---|
| Scene inventory document | {project}/scene-pack/{project}_scene_inventory.md | Required |
| Reference images | {project}/image_out/ or {project}/refs/ | Required |
| Prompt keyword library | {project}/{project}_prompt_keywords.md | Required |
| Continuity inventory | {project}/{project}_continuity_inventory.md | Strongly recommended |
| Video role manifest | Section in scene inventory | Required |
If the prompt keyword library or video role manifest are absent, run
scene-inventory-extractor-v2 phases 2.4 and 11.6 first before proceeding.
Execution Context
This skill requires:
- nanobanana image generation Model Context Protocol (MCP) (see
references/storyboard-generation.md), with every storyboard image call explicitly
using model: gemini-3-pro-image-preview
- Vision capabilities (for storyboard consistency verification)
- File system access (structured output directories)
Generation runs silently — no user confirmation gates during storyboard or prompt
phases. Halt only on consistency failures that require human judgement.
If gemini-3-pro-image-preview is unavailable through nanobanana, or if it cannot
accept the required reference images or character-consistency images for the current
storyboard operation, STOP and report the blocker. Do not continue with a fallback
image model.
Workflow Overview
| Phase | Name | Output |
|---|
| 1 | Input Audit | Verified inputs; flagged gaps |
| 2 | Shot Decomposition | Numbered shot list per scene with duration budgets |
| 3 | Frame Role Assignment | Video role mapping per shot from reference images |
| 4 | Shot Direction | Full directorial spec per shot |
| 5 | Storyboard Generation | Keyframe images via nanobanana |
| 6 | Storyboard Consistency Check | Vision QA; BLOCK/WARN report |
| 7 | Video Prompt Assembly | Full prompts with model routing |
| 8 | Asset Pipeline | File naming, generation manifest, tracking |
Read order: Before Phase 4, read references/shot-direction.md. Before Phase 5,
read references/storyboard-generation.md. Before Phase 7, read
references/model-routing.md. If Phase 7 routes any shot to seedance_2_0, also
load seedance-2-deep-dive before finalizing the prompt, reference plan, duration,
aspect ratio, and generation notes. If Phase 7 routes any shot to kling3_0, also
load kling-3-0-deep-dive before finalizing shot structure, camera motion, Elements
or Motion Control references, duration, aspect ratio, audio notes, and generation
notes. The asset pipeline conventions are in references/asset-pipeline.md.
Phase 1: Input Audit
- Locate and confirm the scene inventory document.
- Inventory all available reference images and note their categories (characters,
locations, props, style anchors).
- Load the video role manifest. If absent, halt and instruct the user to run
scene-inventory-extractor-v2 Phase 11.6 before proceeding; do not derive a
replacement manifest in this skill.
- Load the prompt keyword library. If absent, halt and instruct the user to run
scene-inventory-extractor-v2 Phase 2.4 before proceeding.
- Load the continuity inventory if present. Flag if absent — continuity gaps will be
carried forward as WARN items.
- Record the list of scenes to be processed and their target clip counts.
Phase 2: Shot Decomposition
For each scene in the scene inventory, decompose it into numbered shots.
Duration Budget
Before writing any shot rows, establish a duration budget:
* **Scene ID:** SC-{XX}
* **Scene description:** {brief}
* **Total duration target:** {N} seconds
* **Clip count:** {N} shots
* **Per-clip allocation:** SH001: {N}s, SH002: {N}s, ...
Budget rules:
- Clips must be 4, 6, or 8 seconds.
- One clip = one action in one location. If the action requires more than 8 seconds,
split it.
- Multi-beat scenes need multiple clips. A scene with setup + action + reaction is three
clips minimum.
- Establishing shots: 6–8 seconds. Insert/detail shots: 4 seconds. Dialogue beats: 6
seconds. Complex action: 8 seconds.
Shot Row Format
For each shot, record:
#### {S{XX}_SH{XXX}}
| Field | Value |
|-------|-------|
| Shot ID | S{XX}_SH{XXX} |
| Frame size | XW / W / M / CU / ECU / POV / INS / OTS |
| Lens | {focal length} mm {spherical/anamorphic} |
| Camera mount | {tripod / Steadicam / handheld / crane / gimbal / drone} |
| Camera motion | {static / pan / tilt / dolly / arc / zoom / rise} |
| Visual action | {Concrete, filmable description} |
| Duration | {4 / 6 / 8} seconds |
| Pacing | {slow / moderate / fast} |
| Clip boundary | {continuous / scene_cut} |
| Start frame ref | {Ref ID from video role manifest} |
| End frame ref | {Ref ID or "generate-new"} |
| Grain/grade override | {override or "global spec"} |
Phase 3: Frame Role Assignment
For each shot, assign specific reference images to video model input roles.
Use the video role manifest from the scene inventory as the primary source. Where a
reference image does not yet exist for the required role, flag it as MISSING and note
what needs to be generated.
### S{XX}_SH{XXX} Frame Roles
| Role | File | Notes |
|------|------|-------|
| start_image | refs/locations/launch-strip/low-pre-dawn-rain.png | Pre-launch state |
| end_image | MISSING — generate in Phase 5 | Gannet mid-lift |
| image (subject ref) | refs/props/gannet-uav/primary.png | Identity anchor |
| image (style ref) | refs/style/style_anchor_01.png | Global look |
Missing role resolution: If a start_image or end_image is missing from the
reference library, generate it in Phase 5 (Storyboard Generation) as a storyboard frame,
then promote that generated image to a reference role for the video generation call.
Phase 4: Shot Direction
For each shot, write full directorial direction covering:
4.1 Actor Direction
* **Actor(s):** {Who is in frame}
* **Position:** {Where in frame — left/centre/right; near/mid/far; above/below eyeline}
* **Posture/body state:** {Standing, seated, leaning; tension or ease in body}
* **Action:** {Exact physical action — what they do, in what order, at what speed}
* **Eyeline:** {Where they look — at camera, at another character, off-frame}
* **Expression:** {Named expression from character bible or described precisely}
* **Continuity state entering scene:** {Wardrobe, carried items, body state}
* **Continuity state exiting scene:** {Any changes to the above}
For shots with no human subjects (establishing shots, drone POV, inserts), mark
actor direction as N/A.
4.2 Camera Direction
* **Mount:** {Tripod / Steadicam / handheld / crane / drone gimbal}
* **Starting position:** {Physical location of camera at shot start}
* **Motion path:** {Exact description of camera movement — direction, speed, arc}
* **Ending position:** {Physical location at shot end}
* **Focal length:** {mm}
* **Depth of field:** {Shallow / moderate / deep; what is sharp, what is soft}
* **Shutter:** {180° default or override with reason}
4.3 Lighting Direction
* **Key source:** {Natural / artificial; direction; quality — hard/soft/diffused}
* **Fill:** {Fill source or none; ratio to key}
* **Practicals:** {Any visible light sources in frame — colour, position, intensity}
* **Colour temperature:** {Draw from prompt keyword library for this location type}
* **Grade note:** {Scene-specific override from global cinematography spec, if any}
4.4 Effects Direction
* **Practical effects:** {Rain, smoke, steam, dust, water, fire — present/absent}
* **Environmental motion:** {Wind in grasses, ripples on water, steam from vents}
* **Subject effects:** {Rotors spinning, droplets on fuselage, breath condensing}
4.5 Audio Direction
* **Bed:** {Constant ambient — wind, hum, traffic, crowd}
* **Punctuations:** {Specific sounds at specific moments in the clip}
* **Dialogue:** {Exact words if on-screen lip-sync required; "off-screen" otherwise}
* **Music:** {Diegetic / non-diegetic / none}
* **Audio generation preferences:** ambient={on/off}; sfx={on/off}; dialogue={on/off};
music=off; narration=off; preserve_silence={true/false}
Narration is always a separate process. Do not request generated narration, voice-over,
or off-screen explainer audio in the video model prompt. Non-diegetic music defaults to
off unless the user or scene explicitly requires it.
Phase 5: Storyboard Generation
Prerequisite: Read references/storyboard-generation.md.
Generate storyboard keyframe images for every shot. Use the nanobanana MCP tools with
model: gemini-3-pro-image-preview on every image call.
Pre-Generation Reference Check (per shot)
Before generating any frame for a shot, verify:
- A canonical reference image exists for every named character present in the shot.
- A canonical reference image exists for every named prop visible in the shot.
- A locked reference image exists for every recurring visual element visible in
the shot: fixtures, interfaces, machinery, furniture layouts, signage clusters, or
set dressing that appears in more than two shots and would be noticed if it changed.
- A canonical reference image exists for the specific location variant (angle ×
lighting condition) the shot requires.
If any is missing, generate it now before proceeding. This check is mandatory — a frame
generated without a prop, recurring visual element, or location reference will invent
the object or set dressing independently, producing different monitor layouts, fixture
arrangements, robots, cabinets, or prop designs across the sequence.
For any shot likely to route to Kling 3.0, treat the start and end storyboard frames as
the primary continuity carrier. The current Higgsfield MCP surface observed in S01 only
accepted start_image and end_image for Kling jobs, with no generic image role for
style, location, character, or prop references. Bake every continuity-critical
character, prop, recurring element, location variant, and style constraint into the
start/end frames now; do not assume video-generator can upload those refs later.
Generation Order
- Start frames for all shots in the sequence.
- End frames that require generation (not reused from scouting refs).
- Key frames for shots with intermediate states specified.
Start Frame Prompt Construction
Combine:
- Global style phrase from the prompt keyword library
- Location vocabulary for this shot's location type
- Lighting condition vocabulary for this shot's lighting condition
- Actor direction (position, action, expression, outfit)
- Camera direction (framing, angle, depth of field)
- Effects direction (rain, steam, etc.)
- Global negative constraints
Reference images to pass:
- For character-centric shots, use nanobanana MCP
character_consistency and set
referenceImagePaths to the character identity ref first, followed by the matching
location ref, significant prop refs, visible recurring visual element refs, and style
anchor when available.
- For environment or prop-led shots, use nanobanana MCP
generate_image and set
referenceImagePaths to the matching location ref plus the specific prop refs needed
in the frame plus any visible recurring visual element refs. Add the style anchor
when available; add character refs only for visible named characters whose identity
must be constrained.
Prompt ending: "no text, no watermarks, no logos, no labels, no annotations"
End Frame Prompt Construction
If the end frame shows the same subject in a significantly different state:
- Use
edit_image (edit from start frame)
- Set
referenceImagePaths to the start frame plus only the Phase 11 refs needed for
the described change
- Describe only what changes; do not repeat unchanged elements
- Prefer this path for any end frame derived from the start frame; character, location,
prop, and style consistency should inherit from the start frame naturally.
If the end frame shows a different composition, angle, or subject configuration:
- Use
generate_image (generate new)
- Set
referenceImagePaths to the start frame, matching location ref, required prop
refs, visible recurring visual element refs, and style anchor when available
- Full prompt as for start frame but with end-state description
File Naming
shots/{shot_id}/start.png
shots/{shot_id}/end.png
shots/{shot_id}/key{NN}.png
Phase 6: Storyboard Consistency Check
After generating all storyboard frames, run a vision-based consistency pass.
Checks
| Check | Method | Flag if |
|---|
| Start–end interpolatability | Compare start and end frames | Subject static; only lighting/bg changed; no interpolatable motion |
| Character consistency | Compare against character primary ref | Face, outfit, proportions diverge from reference |
| Location consistency | Compare against location ref | Architecture, layout, materials diverge |
| Prop consistency | Compare against prop ref | Shape, colour, detail diverge |
| Recurring visual element consistency | Compare against locked element refs and across all frames containing each element | Monitor layouts, screen colours, fixture arrays, robots, cabinets, cargo pods, signage, or workstation layouts drift |
| Cross-shot prop identity | For each named prop: gather all frames in the sequence that contain it; view them together | The prop looks like a different physical object across shots — different construction, silhouette, or type |
| Lighting continuity | Compare start and end frames | Light direction or colour-temp contradicts direction spec |
| Cross-shot continuity | Compare end of SH{N} with start of SH{N+1} (if continuous) | Subject position, outfit, or environment jumps |
| Style consistency | Compare against style anchor | Grain character, palette, or colour-temp departs from global spec |
Output
Write a storyboard consistency report:
reports/storyboard_consistency_report.md
BLOCK-level issues must be resolved before Phase 7. WARN-level issues are logged for
human review only when they cannot be fixed locally. The consistency pass is not
informational: fix clear WARN issues now, and convert remaining WARN items into explicit
constraints in the affected prompt and manifest row.
Phase 7: Video Prompt Assembly
Prerequisite: Read references/model-routing.md. Phase 6 complete with no
unresolved BLOCK issues.
For each shot, assemble a complete video generation prompt. This skill prepares the
handoff package for video-generator; it does not submit Higgsfield jobs itself.
If the recommended model is seedance_2_0, apply seedance-2-deep-dive before writing
the prompt. Record why Seedance is the right route, keep the clip short unless the shot
is a deliberate hero test, assign each reference file a clear purpose, and shape the
prompt as a Seedance-native multimodal direction rather than a generic video prompt.
If the recommended model is kling3_0, apply kling-3-0-deep-dive before writing the
prompt. Record why Kling is the right route, structure multi-beat work as labelled shots
with durations, specify camera behaviour and endpoint, identify any Elements or Motion
Control references, and treat critical text/UI as baked-frame or post-production work.
When the live Kling route has not been proven to accept generic references, mark
continuity refs in the Reference Audit as baked into start/end frames rather than as
upload requirements.
Prompt Template
# {S{XX}_SH{XXX}} — Video Prompt
## Metadata
- **Shot ID:** S{XX}_SH{XXX}
- **Scene:** SC-{XX} — {scene name}
- **Duration:** {4 / 6 / 8} seconds
- **Pacing:** {slow / moderate / fast}
- **Clip boundary (next):** {continuous / scene_cut}
- **Recommended model:** {model ID — see references/model-routing.md}
- **Model routing rationale:** {1 sentence explaining the routing choice}
- **Generation strategy:** {image_to_video / start_end_image / multi_shot / motion_control}
- **Aspect ratio:** {16:9 / 9:16 / 1:1 / 21:9}
- **Target resolution:** {pixel dimensions from cinematography spec}
- **Resolution parameter:** {720p / 1080p / model-specific equivalent; provider hint
only until video-generator verifies actual pixels}
- **Model overrides:** {key=value list for live MCP defaults; include audio,
quality/mode, cfg/guidance, genre, or "none"}
- **Count:** {1 by default; 2 only for review-gated hero/uncertain shots when
video-generator confirms the live schema supports it}
- **Audio generation:** ambient={on/off}; sfx={on/off}; dialogue={on/off};
music=off; narration=off; source={generated/none/supplied}
## Frames
- **Start frame:** shots/{shot_id}/start.png
- **End frame:** shots/{shot_id}/end.png
- **Key frames:** {paths or "None"}
## Reference Roles
- **start_image:** {file path}
- **end_image:** {file path}
- **image (subject):** {file path(s)}
- **image (style):** refs/style/style_anchor_01.png
## Reference Audit
- **Required refs:** {character/location/prop/recurring/style refs that must be uploaded}
- **Continuity-critical refs:** {refs named by continuity inventory or Phase 6 report}
- **Baked-frame refs:** {continuity-critical refs that cannot be uploaded to the chosen
video model and therefore must be present in the start/end frames}
- **Reference priority:** start,end,principal_character,hero_prop,recurring_element,
location,style
- **Missing or blocked refs:** {None or blocker}
## Prompt
[STYLE] {Global style phrase from keyword library}
[FILMSTOCK] {Filmstock phrase from keyword library}
[SCENE] {Location vocabulary + lighting condition vocabulary + global negative constraints}
[FRAMING] {Frame size, lens, camera mount, motion path}
[PACING] {slow / moderate / fast — with clip-specific meaning}
[ACTION] {transition_description — 2–4 sentences; subject appearance, movement trajectory,
state changes, existence statements}
[SUBJECT] {Subject key visual features for consistency}
[AUDIO] {Audio direction from Phase 4.5}
[DURATION] {4 / 6 / 8 seconds}
## Audio Generation Preferences
- **Ambient audio:** {on/off}
- **Sound effects:** {on/off}
- **On-screen dialogue/lip-sync:** {on/off; exact lines if on}
- **Music:** off unless diegetic music is visible in-frame
- **Narration:** off; narration is a separate process
- **Audio source:** {generated / none / supplied}
- **Preserve silence:** {true/false}
## Generation Prompt
{Model-native plain text assembled with the algorithm in `references/model-routing.md`.
This is the exact prompt `video-generator` submits to Higgsfield.}
## Consistency Notes
- {Any WARN items from storyboard consistency check}
- {Continuity flags from shot list}
- {Action taken for each WARN/continuity item: regenerated frame, added reference,
injected prompt constraint, or blocker}
Style Language Rule
Every [STYLE], [FILMSTOCK], and [SCENE] field copies from the project's prompt
keyword library. No ad hoc vocabulary.
Continuity Constraint Injection
Before finalizing each prompt, check:
- The location bible negative space rules for this location
- The continuity inventory for this scene
- Any WARN items from Phase 6
Inject all applicable constraints into [SCENE] or [ACTION]. The consistency pass is
not informational: action its output now. Fix clear WARN items by regenerating frames or
adding references, and convert any remaining WARN/continuity item into an explicit
prompt constraint, Reference Audit entry, or blocker.
Manifest
After writing all prompt files, produce:
prompts/manifest.md
# Shot Generation Manifest
| Shot ID | Scene | Duration | Model | Strategy | Aspect | Target Resolution | Resolution Param | Overrides | Count | Audio | Required Refs | Review Gate | Clip Boundary | Transition Type | Transition Duration | Continuity Flags | Start | End | Keys | Prompt File |
|---------|-------|----------|-------|----------|--------|-------------------|------------------|-----------|-------|-------|---------------|-------------|---------------|-----------------|---------------------|------------------|-------|-----|------|-------------|
| S11_SH001 | SC-11 | 8s | seedance_2_0 | start_end_image | 16:9 | 1920x1080 | 1080p | generate_audio=true;quality=standard;genre=auto | 1 | ambient=on;sfx=on;dialogue=off;music=off;narration=off;source=generated | refs/characters/maeve/front.png;refs/props/gannet/primary.png | required | continuous | cut | 0 | eyeline;prop reset | shots/S11_SH001/start.png | shots/S11_SH001/end.png | None | prompts/S11_SH001_prompt.md |
Phase 8: Asset Pipeline
Downstream handoff: Once Phase 8 has produced prompts/manifest.md, prompt files,
storyboard frames, model routing, generation strategy, aspect ratio, target
resolution, resolution parameter, model overrides, count, required-reference audit,
audio-generation preferences, review-gate metadata, and clip-boundary metadata, hand
off to video-generator for Higgsfield MCP media upload, job submission, polling,
resume handling, and assembly-order output.
video-generator is the sole owner of runtime generation logging and Higgsfield job
interactions. It must verify required references, apply audio and model overrides,
handle resumable job logging, submit and poll jobs, and write assembly order before
marking a shot complete.
Prerequisite: Read references/asset-pipeline.md.
Maintain a consistent asset pipeline so generated clips can be traced back to their
source shots, retaken efficiently, and assembled in the correct order.
File Naming Convention
shots/{shot_id}/start.png — start frame image
shots/{shot_id}/end.png — end frame image
shots/{shot_id}/key{NN}.png — key frame(s)
prompts/{shot_id}_prompt.md — video generation prompt
generated/{shot_id}/v{N}.mp4 — generated video clip (v1 = first take, v2 = retake)
generated/{shot_id}/selected.mp4 — symlink or copy of the selected take
Runtime Generation Log
Do not write runtime generation logs in this skill. shot-specifier prepares
prompts/manifest.md, prompt files, storyboard frames, model routing, aspect ratio,
resolution parameters, model overrides, count, required-reference audit,
audio-generation preferences, review-gate metadata, and clip-boundary metadata.
video-generator owns runtime logging after generation begins.
Reference Files
| File | Read Before | Contents |
|---|
references/shot-direction.md | Phase 4 | Full directorial notation guide: actor, camera, lighting, effects, audio |
references/storyboard-generation.md | Phase 5 | nanobanana usage for storyboards, prompt construction, reference-role assignment |
references/model-routing.md | Phase 7 | Video model selection by shot type; routing criteria; known model characteristics |
references/asset-pipeline.md | Phase 8 | File naming conventions, generation log format, retake workflow |
Related Skills
| Skill | Use When |
|---|
scene-inventory-extractor-v2 | Upstream scene inventory, continuity inventory, and reference library are missing |
nanobanana | Generating or editing storyboard frames and locked references |
seedance-2-deep-dive | A shot is routed to seedance_2_0 and needs Seedance-specific duration, reference, prompt, or troubleshooting guidance |
kling-3-0-deep-dive | A shot is routed to kling3_0 and needs Kling-specific shot structure, camera, Elements, Motion Control, audio, product, or troubleshooting guidance |
video-generator | Prompt manifest, frames, and model routing are ready for Higgsfield MCP submission |
Templates
| File | Used In |
|---|
templates/shot-spec-template.md | Phases 2–4 |
Best Practices
One Shot, One Action. Every clip contains one action in one location. If a scene
description contains "and then", split it.
Budget First, Decompose Second. Never start writing shot rows without a clip-duration
budget. The budget prevents scene collapse.
Direction is Concrete. Actor direction specifies position, action, and eyeline.
"Looks concerned" is not direction. "Holds gaze on the empty screen, jaw still, for
two seconds then turns toward Iain" is direction.
Storyboards are a Consistency Investment. Generating storyboard frames before video
generation catches reference drift early. One regenerated storyboard frame costs far
less than one regenerated video clip.
Copy Keyword Library, Do Not Paraphrase. Every [STYLE], [FILMSTOCK], and
[SCENE] field copies from the prompt keyword library verbatim. Paraphrasing introduces
vocabulary drift.
Inject Negative Constraints on Every Prompt. The location bible's negative space
rules (no trees, no US road markings, no blue sky) must appear in every exterior prompt.
The model does not remember previous prompts.
Log Every Generation Call. Job IDs are the only way to retrieve or retake a specific
clip. Log them immediately. An unlogged job is a lost job.
Retakes Are Part of the Pipeline. Not every first take is the right take. The asset
pipeline distinguishes v1 from v2 from selected. Budget for at least one retake per
complex shot.
Machine Vision Shots Get Machine Vision Prompts. Drone POV, surveillance feed,
and telemetry-screen shots must suppress grain, filmstock, and organic movement. Apply
the POV override vocabulary from the keyword library — do not accidentally apply the
film-emulation spec to a shot that is supposed to look like a camera drone.
