story-illustrator

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.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.)

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:

1. nano-banana-2 — fast & cheap, everywhere.
2. nano-banana-pro — best quality, everywhere.
3. Smart mix (suggested) — nano-banana-pro for scenes with 2+ characters in frame, nano-banana-2 for everything else and all reference plates. Best value: pay for the pro model only where multiple characters must stay coherent.
4. 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_type drives 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 book
• dominant_action becomes the prompt body
• characters selects which character references to attach
• scene selects the location reference
• mood informs lighting/color tone
• output image is recorded as scene index NN so the publisher can pair it with {slug}_part_NN.mp3

If no scenes.json exists, ask the user to run scene-splitter first.

Stage 1: Connect and orient

1. Confirm Fal is reachable: run python .claude/skills/story-illustrator/assets/fal_image.py --check. If fal_key is false, stop and tell the user to set FAL_KEY (env var or .env at the repo root). Don't continue without it.
2. Propose ONE visual style based on the story's tone and audience — don't list five options. For beginner children's stories, a strong default is "warm, soft watercolor children's-book illustration, gentle rounded shapes, cozy lighting." The user can override.
3. Determine the aspect ratio — HARD GATE, ask; do not pick silently. If the orchestrator pre-supplied one (look for "Aspect ratio: 4:5"), use that and skip the prompt. Otherwise ask:

   "What aspect ratio? Common options: 4:5 portrait (storybook / phone, the default for picture books), 1:1 square, 3:4 portrait (book page), 16:9 widescreen. Pick one." Lock the answer for the whole run — it MUST be passed to every image call so the storybook is visually consistent.

4. Determine the image model — HARD GATE, ask; do not pick silently (it spends money). Read the model keys + live prices from assets/image-models.json and present the four options from the Model registry section above (nano-banana-2 / nano-banana-pro / Smart mix (suggested) / seedream-4 or other). If the orchestrator pre-supplied a model, honor it and skip. Record the chosen policy (single model, or smart-mix) — Stage 5 applies it per scene.
5. State the scope with a real dollar estimate from the chosen model(s): "Style: [proposed]. Aspect: [answer]. Model: [choice]. N scenes + ~M references ≈ $X.XX (refs at $a, scenes at $b). Reply go to proceed."

Stage 2: Build the visual bible

Read references/bible-extraction.md for the full process. Briefly: extract a Markdown bible covering cast (each recurring character's physical traits, clothing, distinguishing details, default expression), locations (each recurring place's key features + mood), recurring props, and the locked style sheet. Run the two-pass extraction (extract, then re-read the story to catch missed characters/locations) — don't skip the second pass.

For anything the story doesn't physically describe, invent specific, distinctive details and record them. Specifics (exact clothing colors, hair style, a named accessory) are what make consistency visible across scenes; vague descriptions drift.

Two special tables when relevant:

• Prop-state tracker — if a key object visibly changes across scenes (a balloon inflating, a cup filling, a flower wilting then reviving), enumerate its state per scene. Otherwise the model defaults to the "neutral" version of the prop in every scene. Skip only if nothing changes state.
• Characters-in-frame map — for stories with ≥3 named characters, list who must be VISIBLE in each scene (separate from who merely exists). Without it, close shots silently drop characters who should be in the background.

Editorial check (child-safe): verify each character's design is modest and child-appropriate (shoulders/torso covered, sensible everyday clothing, no suggestive posing) before approving — fixing it after references are generated costs a regeneration per affected image. See CLAUDE.md → Editorial standards.

Write the bible to {slug}_bible.md and pause: "Bible drafted — anything to change before I generate references?" (The user can edit the file directly or say go.)

Stage 3: Generate reference images

Generate one reference image per consistent character and per recurring location, using the references model (references_model in the registry — default nano-banana-2). Each is a single fal_image.py call with no --ref (references are generated from the prompt alone), saved under stories/<slug>/<slug>_images/:

python .claude/skills/story-illustrator/assets/fal_image.py \
  --model nano-banana-2 --aspect <locked> \
  --prompt "<style> <character/location description> <no-text + no-border>" \
  --out stories/<slug>/<slug>_images/ref_pip.png

Universal prompt rules — in EVERY reference AND scene prompt:

No text, no labels, no signs, no readable writing in the image. No book titles, no name tags, no words on walls.

No borders, no frames, no decorative edges, no inner margins, no paper-edge effects, no vignettes. Full-bleed illustration — the art extends to all four canvas edges.

Both are non-negotiable. The no-text rule exists because image models hallucinate gibberish text into illustrations whenever there's a book, sign, or wall. The no-border rule keeps the gallery consistent (some models render scenes as matted "pages" otherwise). Prefer positive phrasing of the desired end-state ("a purely pictorial illustration with clean, unmarked surfaces; the art bleeds fully to all four edges") plus a short affirmative no-text clause — that outperforms a long wall of "no X" negations. Keep the explicit negation block for genuinely text-prone scenes (books, signs, walls with writing).

Reference prompts must:

• Include the locked style descriptor verbatim
• Include the no-text + no-border rules
• Describe the character or location in detail (pull from the bible)
• Characters: full body, neutral pose, neutral expression, plain white background extending to all edges (no inner frame around the figure)
• Locations: wide-angle plate, no people, all key features visible, neutral lighting, full-bleed

One reference per character — do NOT combine characters into a group portrait, even to save a generation. A group ref locks them into group-portrait poses; when a scene needs them re-posed (seated, reaching, bending), the model invents poses without per-character anchors and drops characters. Solo ref per character. Locations may bundle (an empty room is fine) since they aren't posed.

Do NOT generate a "style anchor" hero image — style is carried by the character refs + location refs + the style descriptor in every prompt; a style anchor with scene content causes duplication artifacts downstream.

After each generation, capture the printed url and path and store them in {slug}_images.json under references (see schema in Stage 6). Pause: "References generated — quick review, proceed to scenes?" Show the local files (and/or URLs).

Stage 4: Draft the shot list

Read references/shot-list.md for continuity rules and the prompt schema. Build one shot per scene from scenes.json, classifying each by continuity:

• HARD CUT — new location, time skip, or scene 1. Refs: characters + location + style. No previous-scene ref.
• SOFT CUT — same place/time, next moment. Refs: characters + location + previous scene image + style. The previous-scene ref carries clothes/hair/mood/lighting forward — this is the core consistency mechanism.
• MICRO CUT — same moment, tiny change. Refs: previous scene image (dominant) + characters + style.
• STATE RESET — same scene context BUT the character's physical state explicitly changed (got wet, changed clothes, got hurt). Drop the previous-scene ref (it would carry the old state); use character + location refs only and describe the new state in prose.

Derive the classification by comparing each scene to the previous one (location/time/state fields). Write the shot list to {slug}_shotlist.md: per scene → type/angle, action (the moment, in prose), location, characters present, continuity class, state-reset flag, refs to use, and any framing/lighting notes. Keep prompts about the moment and the change — do NOT redescribe characters or settings the references already carry.

If the user chose Smart mix, also record a model per scene in the shot list: count the characters that must be visible in frame (use the characters-in-frame map when present, else the scene's characters). 2+ visible → nano-banana-pro; otherwise → nano-banana-2. List which scenes get the pro model so the cost is transparent. (For a single-model choice, every scene uses that one model.)

Show the shot list with a dollar estimate from the per-scene models. Gate: "N scenes ≈ $X.XX ([k] at pro, [n] at the base model). Reply go to generate, or review to inspect first."

Stage 5: Generate scene images with cascading references

For each scene in order:

1. Build the full prompt: style descriptor + no-text + no-border constraints + the scene's prompt body.
2. Paste in the prop-state line and the characters-in-frame roster from the bible (when those tables exist).
3. Apply the targeted anti-failure clauses from references/shot-list.md as needed:
   • Anti-duplicate-environment — for a close shot of an object that also exists in the room (a table close-up in a kitchen), add "ONE [object] only — no second [object] in the background."
   • Anatomy budget — for body-part close-ups, state the exact count and single source ("TWO hands, both the mother's; no extra limbs").
   • No floating text on question/thought scenes — describe the physical motion ("hands open, palms up, eyebrows raised") rather than "questioningly", and add "no thought bubbles, no question marks, no floating text."
   • Solo-close scenes stay solo — if the scene's characters list is one name and the framing is close, render just that character; don't add others "in the background" (the model renders them at separate tables/seats).
4. Assemble the reference URL list per the scene's continuity class, in priority order: characters first, then location, then previous scene. Respect the model's max_refs (nano-banana models cap at 4; seedream allows more). When a SOFT-cut scene would exceed the cap (3 characters + location + previous = 5), drop the standalone location ref — the previous-scene image already carries the location. Use the references' url values (the Fal CDN URLs) and, for the previous-scene ref, the url returned for that scene earlier in this run.
5. Call the backend with this scene's model (from the Stage 4 policy — the smart-mix model, or the single chosen model) and the locked aspect ratio:

   python .claude/skills/story-illustrator/assets/fal_image.py \
     --model <scene model> --aspect <locked> \
     --prompt "<full prompt>" \
     --ref <char url> --ref <location url> --ref <previous scene url> \
     --out stories/<slug>/<slug>_images/part_<NN>.png
   

6. Capture the printed url and path into {slug}_images.json under shots at this scene's index (index = NN, zero-padded to match {slug}_part_NN.mp3).
7. The next SOFT/MICRO scene uses this scene's url as its previous-scene reference (the cascade). The path is the durable local copy the publisher embeds.

On failure, read the script's error message and act: a non-zero exit prints the reason. auth/FAL_KEY → stop, tell the user to fix the key; 429 rate-limit/out-of-credits → stop and tell the user; 422 validation → check the params/refs and retry; a timeout → retry once; a Fal safety block → surface to the user and suggest rephrasing the prompt. Don't silently skip a scene — every scene needs an image for the publisher to pair it.

Don't run vision-QA inline per scene — it adds latency. QA (if requested) happens after all scenes in Stage 4.5.

Stage 4.5 (OPT-IN): Vision QA — suggestion only

Trigger: the user asked for QA. Default OFF.

Hard rule: never auto-regenerate. Produce a suggestion table; the human decides what to redo.

1. The scene images are already saved locally (each shot's path in {slug}_images.json) — no download needed.
2. Read each path with the Read tool (Claude is multimodal — reading the image loads it into vision context). Read them in parallel in one message.
3. For each image, check against the bible + scene metadata: does each visible character match their locked design? Is the required prop present and in the right state? Does lighting match the mood? Does the composition match the panel_type? Any hallucinated text/labels/borders? Any anatomy issues (hand count, doubled limbs), extra characters, or duplicated objects?
4. Compile one table: scene # · findings · severity (🟢 OK / 🟡 minor / 🔴 worth a redo). List the 🔴 items at the top.
5. Prompt with explicit, named options (no auto-fix): regen N (with a delta), regen N M ..., keep, regen all warns.
6. Run approved regens per references/qa-and-retry.md (re-run fal_image.py for that scene, overwriting its part_NN.png), update its url + path in {slug}_images.json, optionally re-QA those scenes, loop until keep.

Stage 6: Finalize the registry

Ensure {slug}_images.json is complete and present it to the user:

{
  "story_slug": "the-little-cloud",
  "style": "warm soft watercolor children's-book illustration",
  "aspect_ratio": "4:5",
  "references": [
    { "name": "pip", "kind": "character", "path": "stories/the-little-cloud/the-little-cloud_images/ref_pip.png", "url": "https://v3.fal.media/...", "model": "nano-banana-2" },
    { "name": "sky", "kind": "location",  "path": "stories/the-little-cloud/the-little-cloud_images/ref_sky.png", "url": "https://v3.fal.media/...", "model": "nano-banana-2" }
  ],
  "shots": [
    { "index": 1, "path": "stories/the-little-cloud/the-little-cloud_images/part_01.png", "url": "https://v3.fal.media/...", "model": "nano-banana-2",   "continuity": "HARD CUT" },
    { "index": 2, "path": "stories/the-little-cloud/the-little-cloud_images/part_02.png", "url": "https://v3.fal.media/...", "model": "nano-banana-pro", "continuity": "SOFT CUT" }
  ]
}

Each entry carries both path (durable local file) and url (the Fal CDN URL, used as a cascade reference during the run). shots[i].index MUST match scenes[i].index. The publisher prefers path (it embeds the local file, so a stale Fal URL never breaks the storybook).

Confirm: "Wrote {slug}_images.json — N scene images + M references. Ready for the publisher." Optionally offer to build a quick local gallery for review; the publisher's final storybook is the real review surface.

Triggering retries

When the user flags an image, read references/qa-and-retry.md: translate the feedback into specific corrective deltas, regenerate by re-running fal_image.py with the previous image's url as the primary --ref (so the model treats it as "mostly right, fix these things"), overwrite part_NN.png, replace the url + path in {slug}_images.json, and re-present.

What good looks like

• {slug}_bible.md — a bible the user can read and trust
• {slug}_shotlist.md — the shot list with continuity classes
• {slug}_images.json — every reference + scene image (path + url + model), indexed
• 2–5 reference plates + 8–12 scene images saved under stories/{slug}/{slug}_images/
• A natural flow: user approves the bible, says go a couple times, has all images a few minutes later

Reference files

• references/bible-extraction.md — two-pass bible extraction
• references/shot-list.md — continuity classification + prompt schema
• references/qa-and-retry.md — corrective-delta retry pattern
• references/image-backends.md — the model registry + adding/swapping Fal models
• assets/fal_image.py — the Fal image script (stdlib only)
• assets/image-models.json — the model registry