Communitygithub.com

storyboard-director

Builds production storyboards where every beat records text, position, visuals, motion, sound, timing, and its link to the script.

What is storyboard-director?

storyboard-director is a Claude Code agent skill that builds production storyboards where every beat records text, position, visuals, motion, sound, timing, and its link to the script.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/achmdfzn/motionforge-atelier/tree/HEAD/.claude/skills/storyboard-director

Ask in your favorite AI

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

Documentation

STORYBOARD DIRECTOR

Mandatory

A storyboard is not just a list of pictures. Every scene and beat must state: text/narration, visuals, position/layout, motion, sound, and time. Use the template docs/templates/STORYBOARD_TEMPLATE.md.

Workflow

  1. Lock the brief, the 1080×1920 vertical format, 60 FPS, duration, audience, style bible, and main message.
  2. Break the script into atomic sentences/beats; give them stable IDs (S01-B01, etc.). Do not merge different sentences without a reason.
  3. For every beat, write the exact VO text, exact on-screen text, what is visible, the subject/asset, and the action.
  4. Set positions with normalized 0..1 coordinates (x, y, w, h), anchor, alignment, layer/z-order, safe area, and reading direction. Include pixel sizes/positions when needed.
  5. Define framing, camera, transitions, entrance/exit motion, duration, start/end frame, and overlap.
  6. Record audio: VO clip, music, ambience, SFX, cue frame, duration, relative gain, fade, and pauses/silence.
  7. Match each VO sentence to one or more visuals/shots that clarify its meaning. Avoid repetitive literal visuals; use metaphor when it works better.
  8. Validate continuity, mobile readability, safe area, timing, and that the total duration matches.

Mandatory output per beat

  • ID, scene, start/end frame, duration in frames and seconds.
  • VO sentence ID + text.
  • On-screen text + position.
  • Visual/asset + composition and position.
  • Motion/camera + easing.
  • Audio cue: type, file/placeholder, start/end, relative level, fade.
  • Transition in/out and continuity notes.

Rules

  • All visible text must be written verbatim, not "add a title".
  • All positions must be explicit, not "roughly in the middle".
  • All sound must be recorded, including the decision to have no sound/silence.
  • Do not invent assets that do not exist yet; mark them PLACEHOLDER and list the asset requirements.
  • Beat duration at 60 FPS: durationInFrames = endFrame - startFrame with an exclusive end boundary.
  • A closing logo + CTA is mandatory and must be specific to the video, not generic.

ID and time conventions

  • Beat ID: S<scene>-B<beat> with two digits (S01-B01). IDs do not change when a beat moves; an inserted beat gets a new ID (S02-B03) instead of renumbering everything.
  • Half-open interval [startFrame, endFrame): frame endFrame already belongs to the next beat.
  • Convert from seconds only once, in one place: frame = round(seconds × fps). After that, every number in the storyboard is an integer frame.
  • Consecutive beats must be contiguous: beat N's endFrame = beat N+1's startFrame. Overlap is only allowed for transition windows recorded in the Transition column.
  • Total: the last beat's endFrame = the composition's durationInFrames.

Output format

  • Header: project ID, canvas, FPS, duration (seconds + frames), paths to the style bible and audio plan.
  • Beat table following docs/templates/STORYBOARD_TEMPLATE.md.
  • Per-beat notes for complex beats (multi-stage motion, characters, 3D).
  • Sentence-to-shot map when there is VO, or a single line "not applicable — no VO".
  • Audio cue sheet, including intentional silence.
  • Bespoke end-card spec.
  • List of PLACEHOLDER assets with requirements and license status.

QA checklist

  • Every beat has an ID, frame in/out, verbatim text (or "—"), visual, normalized position, motion, sound, and transition.
  • Beats are contiguous from frame 0; the sum of durations = durationInFrames.
  • Important text sits in the safe area and reads on a phone screen (size, contrast, time on screen).
  • Text stays on screen long enough to read; long sentences are split or given more time.
  • Every VO sentence has a paired shot; every shot has an editorial purpose.
  • Silence is written explicitly, not left blank.
  • Motion is described as a function of frame (from/to, frame range, easing), ready to be translated by frame-time-engineering.
  • The end card continues the video's motif and its CTA is verbatim.
  • Every asset that does not exist yet is marked PLACEHOLDER.

Mini example

A 2-second text hook beat:

Beat IDFramesVOOn-screen textVisualPositionMotionSoundTransition
S01-B010–120—Why does your video feel generic?Plain dark backgroundx .08, y .40, w .84; left-aligned; z 2Each word enters every 10 frames, slide-up 24 px, 14-frame duration, ease-outSilence 0–30, SFX-001 whoosh at 30cut

Motion ready to code: word i starts at frame i × 10; opacity 0→1 and translateY 24→0 over [i×10, i×10+14].

Failure modes

  • "Text appears in the middle" → cannot be coded; write x/y/w/h, anchor, and alignment.
  • Beats off by one frame (0–119 then 120–240) → the exclusive convention was not used; switch everything to half-open.
  • Text changed in code but not in the storyboard → the storyboard is the source of truth for copy; update the storyboard first.
  • Total duration misses the composition → recompute from the table; do not patch it in code.
  • Visuals too literal per sentence → use a demonstration, diagram, or metaphor; record the reason.
  • End card is a logo + "Follow us" → not bespoke; build a visual bridge from the video's motif.

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

Related Skills