STOP. READ THIS ENTIRE SKILL.MD BEFORE CALLING ANY ENDPOINT.

create-storyboard

Transform screenplays into animatics through a collaborative creative dialogue.

Philosophy: The skill acts as your cinematographer - it doesn't just execute, it thinks with you. It makes suggestions, explains rationale, asks for your input, and learns from completed projects.

Quick Start

# Start a new storyboard session (will ask questions)
./run.sh start screenplay.md --json

# Continue with answers to questions
./run.sh continue --session <ID> --answers '{"camera_s1": "sounds good"}'

# Auto-approve all suggestions (non-collaborative mode)
./run.sh start screenplay.md --auto-approve

Collaboration Loop

The skill operates in a question-answer loop with the calling agent:

┌─────────────────────────────────────────────────────────────┐
│                    COLLABORATION LOOP                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Agent calls: ./run.sh start screenplay.md --json         │
│                         ↓                                    │
│  2. Skill returns: {                                         │
│       status: "needs_input",                                 │
│       suggestions: [                                         │
│         "For Scene 3 where Sarah confronts the villain,      │
│          I'm thinking a Panaflex with low-key lighting       │
│          would enhance the tension. A slow pan from her      │
│          face to the window would build suspense.            │
│          What do you think?"                                 │
│       ],                                                     │
│       session_id: "storyboard-20260129-abc123"               │
│     }                                                        │
│                         ↓                                    │
│  3. Agent/User reviews suggestions, provides feedback        │
│                         ↓                                    │
│  4. Agent calls: ./run.sh continue --session ID --answers    │
│                         ↓                                    │
│  5. Skill proceeds or asks more questions                    │
│                         ↓                                    │
│  6. Repeat until status: "complete"                          │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Creative Suggestions

Instead of dry questions like "What emotion for Scene 3?", the skill offers filmmaker suggestions:

💡 Scene 3 - Camera Suggestion

"In Scene 3 where Sarah confronts the villain, I'm thinking we should use a slow push-in as the tension builds. It would really draw the audience into the character's anxiety."

Rationale: The cautious movement and sparse dialogue suggest building dread - a push-in amplifies this without words.

Alternatives: locked-off static for uncomfortable stillness, handheld for visceral unease

→ sounds good / prefer static / let's try handheld / suggest something else

Memory Integration

The skill queries /memory to recall learned techniques:

# When screenplay references "Blade Runner 2049"
techniques = recall_film_reference("Blade Runner 2049")
# Returns learned techniques from /ingest-movie

# The skill incorporates this into suggestions:
"I see you've referenced 'Blade Runner 2049' for Scene 1.
 From my memory of that film:
 • 2049 Minimal Composition: Desolate, geometric framing...
 • 2049 Hologram Lighting: Magenta/cyan holographic glow...
 Should I apply these techniques?"

Memory scopes used:

• horus-storyboarding - Storyboard-specific learnings
• horus-movies - Techniques from ingested films

Commands

start

Start a new storyboard session.

./run.sh start screenplay.md [options]

Options:
  --output-dir, -o   Output directory (default: ./output)
  --fidelity, -f     Panel fidelity: sketch|reference (default: sketch)
  --format           Output format: mp4|html|panels (default: mp4)
  --auto-approve, -y Skip all questions, use defaults
  --json, -j         Output structured JSON for agent consumption

continue

Continue an existing session with answers.

./run.sh continue --session <ID> --answers '<JSON>' [options]

Options:
  --search-dir       Directory to search for session files
  --json, -j         Output structured JSON

status

Check status of an existing session.

./run.sh status --session <ID>

demo

Run a demo with sample screenplay showing the collaboration loop.

./run.sh demo           # Interactive with questions
./run.sh demo -y        # Auto-approve, skip questions
./run.sh demo --json    # JSON output for agents

Output Formats

Format	Description	Use Case
mp4	Video animatic with timed panels	Preview timing, share with team
html	Interactive gallery with navigation	Review, iterate, keyboard controls
panels	Directory of PNG images	Custom assembly, integration

Panel Fidelity

Level	Description	Speed
sketch	Composition guides with shot codes	Fast
reference	Stick figure placeholders	Medium
generated	AI-generated images (requires /create-image)	Slow (raises NotImplementedError)

Integration Points

/create-movie

This skill is a sub-phase of /create-movie:

/create-movie workflow:
  RESEARCH → SCRIPT → [STORYBOARD] → BUILD TOOLS → GENERATE → ASSEMBLE
                ↑
         /create-storyboard

/create-story

Takes screenplay output as input:

# After /create-story generates screenplay.md
./run.sh start /path/to/screenplay.md

/memory

Queries for learned filmmaking techniques:

from memory_bridge import recall_film_reference, learn_technique

# Recall techniques
techniques = recall_film_reference("The Godfather")

# Store new technique after project
learn_technique(
    "Tension Push-In",
    "Slow 10-second push-in during confrontation",
    source="Project: Dark Horizon"
)

/ingest-movie

Techniques ingested via /ingest-movie become available for recall:

# Ingest a film's techniques
/ingest-movie "Blade Runner 2049"

# Later, /create-storyboard can recall:
"From my memory of Blade Runner 2049:
 • Minimal Composition: Desolate, geometric framing..."

Structured JSON Output

For agent consumption, use --json flag. Response format:

{
  "status": "needs_input",
  "phase": "camera_plan",
  "session_id": "storyboard-20260129-abc123",
  "questions": [
    {
      "id": "camera_s1",
      "scene_number": 1,
      "question_type": "creative_suggestion",
      "question": "For Scene 1, I'm thinking a slow push-in...",
      "options": ["sounds good", "prefer static", "suggest something else"],
      "context": "The cautious movement suggests building dread..."
    }
  ],
  "partial_results": {
    "total_shots": 5,
    "total_duration": 21.5,
    "shot_plan_file": "output/.../shot_plan.json"
  },
  "message": "Generated 5 shots. Please review my creative suggestions.",
  "resume_command": "./run.sh continue --session ... --answers '<JSON>'"
}

Status values:

• needs_input - Waiting for answers to proceed
• in_progress - Phase executing, will continue
• complete - All phases done, outputs ready
• error - Something failed

File Structure

create-storyboard/
├── SKILL.md                 # This file
├── run.sh                   # Entry point
├── orchestrator.py          # Main CLI with collaboration loop
├── screenplay_parser.py     # Parse markdown/Fountain screenplays
├── camera_planner.py        # Auto-select shots, estimate timing
├── panel_generator.py       # Generate visual panels
├── animatic_assembler.py    # Create MP4/HTML output
├── collaboration.py         # Session state, questions, structured output
├── creative_suggestions.py  # Natural language filmmaker suggestions
├── memory_bridge.py         # /memory integration
├── shot_taxonomy.py         # Camera shot definitions
└── sanity/                  # Dependency verification
    ├── ffmpeg_concat.sh
    ├── pillow_composite.py
    └── run_all.sh

Example Session

$ ./run.sh start screenplay.md

============================================================
📊 Status: NEEDS_INPUT
📍 Phase: camera_plan
🔑 Session: storyboard-20260129-134523-a1b2c3
============================================================

🎬 CREATIVE SUGGESTIONS

Here's what I'm thinking for the visual approach:

### 1. Scene 1 - Camera Suggestion

💡 For Scene 1 in the APARTMENT, I'm thinking we should use a slow
   push-in as the tension builds. It would really draw the audience
   into the character's anxiety.

   *Why*: The cautious movement and sparse dialogue suggest building
   dread - a push-in amplifies this without words.
   *Or*: locked-off static for uncomfortable stillness, handheld for
   visceral unease

   → sounds good / prefer static / let's try handheld / suggest something else

### 2. Scene 1 - Reference Suggestion

💡 I see you've referenced 'Blade Runner 2049' for Scene 1. I could
   search my memory for specific techniques from that film - the color
   grading, the shot composition, the pacing. Should I pull those details?

   *Why*: The reference to Blade Runner 2049 gives us a visual language
   to draw from.

   → yes_search_memory / no_skip / skip_all_references

============================================================
Reply with your thoughts on each, or just say 'looks good' to proceed.
============================================================

▶️  To continue: ./run.sh continue --session storyboard-20260129-134523-a1b2c3 --answers '<JSON>'

Camera Shot Taxonomy

Code	Name	Description	Emotional Use
EWS	Extreme Wide	Full environment, tiny figure	Isolation, scale
WS	Wide Shot	Full body with environment	Establishing, action
FS	Full Shot	Head to toe	Physical performance
MWS	Medium Wide	Knees up	Dialogue with movement
MS	Medium Shot	Waist up	Standard dialogue
MCU	Medium Close-Up	Chest up	Emotional dialogue
CU	Close-Up	Face only	Key emotional moments
ECU	Extreme Close-Up	Detail (eyes, hands)	Climactic intimacy
OTS	Over-The-Shoulder	Conversation framing	Dialogue, presence
POV	Point of View	Character's perspective	Empathy, discovery

Common Mistakes

WRONG: Auto-approving all suggestions without review

./run.sh start screenplay.md --auto-approve  # skips creative collaboration

RIGHT: Review suggestions interactively, provide feedback

./run.sh start screenplay.md --json
# Review suggestions, then continue with feedback
./run.sh continue --session <ID> --answers '{"camera_s1": "prefer static"}'

WRONG: Ignoring /memory recall for film reference techniques

./run.sh start screenplay.md  # misses learned techniques from /ingest-movie

RIGHT: Memory integration surfaces techniques from ingested films

# The skill queries /memory automatically for film references in the screenplay
# Ensure films are ingested first via /ingest-movie for best results

WRONG: Using "generated" fidelity (not implemented)

./run.sh start screenplay.md --fidelity generated  # raises NotImplementedError

RIGHT: Use sketch or reference fidelity

./run.sh start screenplay.md --fidelity sketch   # composition guides (fast)
./run.sh start screenplay.md --fidelity reference # stick figures (medium)

Dependencies

• Python 3.11+
• FFmpeg (for video assembly)
• Pillow (for panel generation)
• Typer (CLI framework)

Run sanity checks:

./sanity/run_all.sh