Communitygithub.com

Cinematic Storyboard & Unit Segmentation Skill

Converts a script into a cinematic storyboard, segmented into 'units' (paragraphs) corresponding to ≤15-second video clips. Each unit includes scene blocking descriptions, and each shot uses a professional shot size code (WS/MS/MCU/CU/ECU) + camera movement + foreground + [visual action] + [sound design] + dialogue — designed specifically for storyboard planning and segmentation prior to short-form video generation. Output format aligns with 'storyboard.txt'.

What is Cinematic Storyboard & Unit Segmentation Skill?

This AI skill transforms one or more episodes of a script into a detailed, cinematic storyboard optimized for short-form video production. It automatically segments the storyboard into 'units,' each representing a video clip ≤15 seconds long. For each unit, it provides a scene blocking description detailing character positions and spatial relationships. For each individual shot within a unit, the skill generates a structured line containing a professional shot size code (WS/MS/MCU/CU/ECU), a specific camera movement, a foreground element (or 'none'), a bracketed visual action description, a bracketed sound design note, and the dialogue line. The entire output follows a strict three-level hierarchy (Episode → Unit → Shot) and is formatted as plain text, ready to be saved as a `.txt` file. This skill is particularly useful for developers, content creators, and AI agent users working with AI coding assistants like Claude Code, Cursor, or Codex to pre-visualize and plan short video productions, ensuring every script element is translated into a precise, actionable shot list.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nian-pangolin/wan3-drama-skills/tree/HEAD/cinematic-storyboard

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does Cinematic Storyboard & Unit Segmentation Skill do?

Converts a script (one or more episodes) into a "cinematic storyboard script," then segments the storyboard into individual "units" (paragraphs), each corresponding to a video clip ≤15 seconds.

Trigger Conditions

Use this skill when a user provides script text (including scene headings, characters, △ action descriptions, dialogue, VO/OS, etc.) and wants to:

  • Generate a "cinematic storyboard," "camera script," or "shot list," or
  • Segment the storyboard into "parts/units/15-second clips," or
  • Explicitly requests an output format "like storyboard.txt."

Input Format

The input is one or more episodes of a script, typically structured as follows:

Episode X
X-X Scene Name Time (Day/Night) INT/EXT
Characters: Character 1, Character 2 ...
Subtitle: (Optional, e.g., Republic Era · Shanghai · The Bund)
△ Action description (storyboarding hint, often starting with △ or [Close Up])
Character Name (emotion/action note): Dialogue content
Character Name (VO): Inner monologue
Character Name (OS): Voice-over/memory audio
(Flashback shot) / (Cut to) / (Transition) … etc.

Output Format (Three-Level Structure)

Output is plain text, using a three-level structure: Episode → Unit → Shot.

Level 1: Episode Title

Episode X Storyboard

Level 2: Unit (Storyboard Segments)

Each unit corresponds to a ≤15-second video clip. Format:

Unit N: X-X Scene Name Time INT/EXT Scene Blocking Description: <Spatial positioning, distances, and movement of characters within this clip>
  • Unit N: Numbered sequentially from 1 within each episode.
  • Followed by the original scene heading (X-X Scene Name Time INT/EXT), with optional states like (Flashback), (Transition), (End Hook).
  • Scene Blocking Description: Describes the physical positions, distances, facing directions, cover, etc., of characters within this unit, providing a spatial reference for camera staging.

Level 3: Shot Line

Shots within each unit are numbered from 1. One shot per line. Format:

N. Shot Size Code (Camera Movement) Foreground: <Foreground description or "none">.[Visual Action Description][Sound Design Description]<Dialogue Part>
  • <Dialogue Part>: If dialogue exists: Character Name: Dialogue (VO/OS: Character Name (VO): Dialogue). If no dialogue: :(No dialogue)

Complete Shot Line Example:

4. CU (Fixed Shot) Foreground: none.[Close-up of Qin Shuyao's face, from neck to top of head. Her eyes sparkle, her expression proud yet slightly languid][Soft voice, with a hint of wistfulness, slow pace]Qin Shuyao: The Bund tonight is too quiet.
1. WS (Low-Angle Dolly Shot) Foreground: Blurred, rain-speckled antique car window.[Qin Shuyao, in a fitted cheongsam, stands in the doorway's glow. The camera, close to the wet cobblestone, slowly pushes in][Ambient: Faint jazz mixed with distant carriage wheels]:(No dialogue)

Shot Line Field Breakdown

1. Shot Size Code (Required – placed first)

CodeMeaningUse
WSWide ShotEstablish scene, environment relationships, group staging, large-scale action
MSMedium ShotCharacter waist-up, action, two-person relationship, movement
MCUMedium Close-UpChest-up, emotional progression, primary dialogue shot
CUClose-Up"Face, from neck to top of head", emotional outburst, key prop
ECUExtreme Close-UpEye, finger, bloodstain, extreme detail emphasis
  • Facial close-ups should be uniformly described as "Close-up of XXX's face, from neck to top of head" to ensure generation consistency.

2. Camera Movement (Required – follows shot size, in English parentheses within the surrounding Chinese text)

Written inside ( ), describing the camera position and movement. Common vocabulary (can combine Chinese and English terms):

  • Fixed: Fixed Shot, Fixed Wide Angle, Top-Down Fixed
  • Dolly/Push-Pull: Dolly Shot, Slow Push-In, Snap Zoom, Extreme Close Push-In, Track Out
  • Pan/Tilt: Pan Shot, Panning Follow, Whip Pan, Tilt Down, Slow Tilt Up
  • Angle: Low-Angle Shot, High-Angle Shot, Over-the-Shoulder Reverse Shot, Dutch Angle
  • Handheld/Follow: Slight Handheld, Handheld Shake, Steadicam Follow, Ground-Level Handheld Follow, Dolly Zoom
  • Special Effects: Slow-mo, Match Cut, Crane Down, Rack Focus, Snap Focus, POV
  • Transition: Dissolve, Wipe, Hard Cut, Snap Zoom Transition

3. Foreground (Required)

After Foreground:, write a specific foreground obstruction or none. Foreground creates depth and a sense of voyeurism. Examples:

  • Foreground: Blurred, rain-speckled antique car window.
  • Foreground: Blurred shoulder of Qin Shuyao. (Overs/OTS must include blurred shoulder)
  • Foreground: Assassin's gun barrel. / Foreground: Out-of-focus, burning red phoenix wedding candle.
  • If no foreground: Foreground: none.

4. [Visual Action Description] (First bracket, required)

Describes the specific visuals within the shot: character actions, movement, expressions, camera movement endpoint, environmental changes. Must be concrete and executable, with spatial and directional information.

5. [Sound Design Description] (Second bracket, required)

Every shot must have an independent sound/performance layer annotation, choosing one or combining from the following dimensions:

  • Ambient: [Sound effect: Crisp footsteps of high heels], [Horse whinny tearing through the night], [Intense gunfire]
  • Breath/Gasps: [Intake: Sharp gasp 0.8s], [Breath: Steady breathing pause 1.0s] (can include duration)
  • Silence/Pause: [Silent pause 2.0s]
  • Micro-Expression/Performance Note: [Micro-expression: Jaw tenses], [Movement slow and silent]
  • Dialogue Tone (when dialogue present): [Low and slow voice, with a hint of wistfulness], [Bellowing, very loud], [Inner VO, voice extremely desperate and hoarse]

6. Dialogue Part (Required, at end of line)

  • With dialogue: Character Name: Dialogue content
  • Inner monologue: Character Name (VO): Dialogue content
  • Off-screen/memory audio: Character Name (OS): Dialogue content
  • No dialogue: :(No dialogue)

Unit Segmentation Rules (Core: Segmenting the Storyboard)

  1. Duration Priority: Each unit corresponds to a video clip ≤15 seconds. Estimate based on shot count and pacing; typically 3-6 shots per unit.
  2. Segmentation Basis: New units are created at these points:
    • Significant change in space/staging (character movement, new character enters frame, encirclement forms)
    • Scene/time transition (entering flashback, transition, return to reality)
    • Change in dramatic beat (e.g., from tender→conflict, from standoff→explosion)
  3. Scene Blocking Description: The beginning of each unit must describe the characters' physical positions, relative distances, facing directions, and cover, serving as the spatial foundation for all shots in that segment.
  4. Unit Coherence: Shots within the same unit share the same space and time; shots represent a decomposition of continuous action.
  5. End Hook: The last unit of each episode adds a note to the scene description: (End Hook) or (End Climax Hook). The final shot fades to black, leaving a suspense hook.

Shot Splitting Rules (Core: Storyboarding)

  1. Cut Density First: Every semantic pause (comma, semicolon, interjection), every emotional shift, and every person/object mentioned should be considered for a cut. Better to cut more than to cut too few.
  2. At least 2-3 shots per line of dialogue: Speaker → Listener's reaction; dialogue with commas should be split at commas, inserting listener/mentioned object shots in between.
  3. No consecutive same character, same angle: If two adjacent shots have the same character and same angle, they should be merged or the angle/shot size should be changed, or a reaction shot inserted. For long monologues, insert bystander reaction shots between clauses.
  4. VO/OS as independent shots: Inner monologues, off-screen audio, and memory audio should be standalone shots, often paired with a close-up or subjective POV.
  5. Significant △ Actions as independent shots: Key actions with no dialogue (drawing a gun, falling off a horse, pushing open a door, pressing a bloodstain) should be standalone shots with :(No dialogue).
  6. OTS/Overs must include blurred foreground: For two-person dialogue/confrontation, prioritize over-the-shoulder reverse shots. Foreground: Blurred shoulder of XXX.
  7. Foreground Depth: Use foreground elements (raindrops, smoke, gun barrel, doorframe, candle flames) effectively in key shots to build depth and emotion.
  8. No Dialogue Repetition: When splitting a single dialogue line across multiple shots, distribute the fragments sequentially by meaning. Adjacent shots must not repeat dialogue.

Shot Size / Camera Movement / Sound Selection Suggestions

  • Establishing shots: Use WS + dolly/top-down + ambient sound; Emotional explosion: Use CU/ECU + snap zoom + gasp; Action scenes: Use MS + handheld/steadicam + dense sound effects; Transitions: Use Match Cut / Dissolve / Wipe / Whip Pan.
  • Sound design must match the visual mood: quiet scenes use [Silent pause / Gasp], conflict uses [Bellow / Intense gunfire], dying/despair uses [Wispy breath / Ethereal memory].

Transitions and Special Markers

  • In-script markers like (Flashback shot), (Cut to), (Transition) appear in the unit scene annotation as (Flashback), (Transition), etc.
  • Cross-scene/time transitions should use a dedicated transition shot (Match Cut / Dissolve / Wipe / Hard Cut), and the [Visual Action] should explain the transition logic (e.g., "mirrored action on axis", "shape and momentum match").

Output Requirements

  1. Begin with the episode title Episode X Storyboard.
  2. Output in order: Unit → Shot. Number shots consecutively from 1 within each unit; numbers reset for each new unit.
  3. Each shot occupies one line. Strict field order: N. Shot Size (Movement) Foreground: X.[Visual][Sound]Dialogue.
  4. Every shot must include: shot size code, camera movement, foreground, [Visual], [Sound], and dialogue part (write :(No dialogue) if silent) — no omissions.
  5. For multi-episode processing, output each episode sequentially. Separate episodes with a new Episode X Storyboard title.
  6. Final output is plain text, ready to be saved as a .txt file. Suggested filename: storyboard.txt or {episode}_storyboard.txt.
  7. Coverage: Ensure every line of dialogue and every key △ action in the script has a corresponding shot. Do not miss hooks or transitions.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Related Skills