story-illustrator
Generates a consistent illustrated image for every scene of a story — keeping characters, locations, and visual style coherent across the whole sequence using cascading reference images. Reads a {slug}_scenes.json (from scene-splitter), proposes a visual style, ASKS the user for the aspect ratio and image model, extracts a visual bible, drafts a continuity-classified shot list, generates one reference image per character + location, then one image per scene (with a strict no-text/no-border constraint), and records every image in {slug}_images.json. Images are generated through the Fal API via the bundled fal_image.py script, with a pluggable model registry (nano-banana-2, nano-banana-pro, seedream-4, or any Fal model you add). Use this skill whenever the user wants to illustrate a story, generate scene images, draw the pictures for a storybook, build the illustrations, or produce a consistent visual sequence. Trigger on phrases like "illustrate this story", "generate the images", "draw
hassancs91 · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add hassancs91/claude-image-generation --skill story-illustratorAbout this skill
name: story-illustrator description: Generates a consistent illustrated image for every scene of a story — keeping characters, locations, and visual style coherent across the whole sequence using cascading reference images. Reads a {slug}_scenes.json (from scene-splitter), proposes a visual style, ASKS the user for the aspect ratio and image model, extracts a visual bible, drafts a continuity-classified shot list, generates one reference image per character + location, then one image per scene (with a strict no-text/no-border constraint), and records every image in {slug}_images.json. Images are generated through the Fal API via the bundled fal_image.py script, with a pluggable model registry (nano-banana-2, nano-banana-pro, seedream-4, or any Fal model you add). Use this skill whenever the user wants to illustrate a story, generate scene images, draw the pictures for a storybook, build the illustrations, or produce a consistent visual sequence. Trigger on phrases like "illustrate this story", "generate the images", "draw the scenes", "make the pictures", "visualize this story", or whenever scenes.json exists and the user wants images. Requires a Fal API key (FAL_KEY in the environment or a .env file).
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.pydirectly, 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.)
Before anything else, confirm Fal is reachable:
python .claude/skills/story-illustrator/assets/fal_image.py --check
If it prints {"fal_key": false} (exit 1), stop and tell the user to set FAL_KEY (env var, or a .env at the repo root — see the README). Don't proceed without it.
Model registry — and choosing a model (ASK each run)
Available models live in assets/image-models.json — each entry maps a friendly key to its Fal endpoint, whether it accepts reference images (required for the cascade), how it encodes aspect ratio, and its cost per image. To add or swap a model, edit that file — no code change. The bundled defaults:
| Key | Model | Cost/img | Best for |
|---|---|---|---|
nano-banana-2 | Nano Banana 2 (Google) | $0.08 | references + single-character scenes |
nano-banana-pro | Nano Banana Pro (Gemini 3 Pro Image) | $0.15 | multi-character beats, fine detail |
seedream-4 | Seedream v4 (ByteDance) | $0.03 | cheapest; a different look / testing |
Picking the model is a HARD GATE — ask the user each run (Stage 1). Read the live prices from image-models.json and offer:
nano-banana-2— fast & cheap, everywhere.nano-banana-pro— best quality, everywhere.- Smart mix (suggested) —
nano-banana-profor scenes with 2+ characters in frame,nano-banana-2for everything else and all reference plates. Best value: pay for the pro model only where multiple characters must stay coherent. seedream-4(or any other registry key) — cheapest / alternative style.
Whatever they pick, references always use the cheapest reference-capable model (references_model in the registry, default nano-banana-2) unless the user chose "pro everywhere." If the orchestrator pre-supplied a model choice, honor it and skip the prompt.
Workflow — six stages (plus optional Stage 4.5 QA)
A Stage 4.5 vision-QA pass is available between scene generation and finishing. It is opt-in (default OFF) — invoke with qa, --qa, or "with QA". It reviews the generated images and produces a suggestion table; it never auto-regenerates.
Stage 0: Load scenes.json
Read {slug}_scenes.json from stories/{slug}/. Each scene becomes exactly one image:
- one image per scene, in order, indexed to match
scenes[i].index panel_typedrives framing (establishing→ wide;action→ dynamic;reaction→ close on face;detail→ tight on object) — don't override it; that variety is what makes the gallery feel like a real bookdominant_actionbecomes the prompt bodycharactersselects which character references to attachsceneselects the