story-illustrator

Story Illustrator

Turns a story (already split into scenes) into a sequence of illustrations with consistent characters, locations, and style — using cascading reference images to preserve continuity from scene to scene.

This is where the storybook earns its polish. Naively prompting "scene 1", "scene 2", "scene 3" gives three different-looking children in three different rooms. This skill prevents that with a bible → references → cascading scene images workflow.

When this skill applies

{slug}_scenes.json exists (from scene-splitter) and the user wants images. Also applies if the user pastes a story and asks to illustrate it — in that case, run scene-splitter first (or fall back to building a quick internal shot list).

The skill does NOT apply to:

• Single one-off image requests with no narrative (run fal_image.py directly, or call an image tool).
• Video/animation tasks.
• Cases where the user only wants the bible or shot list as text, not actual images.

Required tools — the image backend

Images are generated through the Fal API using the bundled script assets/fal_image.py. One call generates one image:

python .claude/skills/story-illustrator/assets/fal_image.py \
  --model nano-banana-2 --aspect 4:5 \
  --prompt "<full prompt>" \
  --ref <url> --ref <url> \
  --out stories/<slug>/<slug>_images/part_03.png

It submits to Fal, polls until done, downloads the image locally, and prints one JSON line: {"url": "<fal cdn url>", "path": "<local file>", "model": "...", "cost_usd": 0.08}. Capture both the url and the path (explained in Stage 5/6).

Why a script, not an MCP: the only thing this skill needs from an image generator is the primitive (prompt, reference image URLs, aspect ratio) → an image. A small stdlib script over the Fal HTTP API does exactly that with one dependency — a FAL_KEY — and keeps the model choice fully in your hands. (Narration, by contrast, uses the ElevenLabs MCP — the repo deliberately demonstrates both integration styles.)