微信扫一扫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 learningshorus-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 (not yet implemented) |
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 proceedin_progress- Phase executing, will continuecomplete- All phases done, outputs readyerror- 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 |
Dependencies
- Python 3.11+
- FFmpeg (for video assembly)
- Pillow (for panel generation)
- Typer (CLI framework)
Run sanity checks:
./sanity/run_all.sh