storybook-pipeline
Skill87 starsChanged 4 months agoMITView on GitHub
Orchestrator that runs the full AI Storybook pipeline end-to-end on one English story. Dispatches the 4 component skills in order — scene-splitter → story-illustrator → story-narrator → story-html-publisher — using the locked filename convention {slug}_* and {slug}_part_NN.{png,mp3} so every image and audio clip pairs by scene index, ending with one self-contained HTML storybook. Use this skill whenever the user wants to run the pipeline, make a storybook from a story, turn a story into an illustrated narrated storybook, process a story end to end, or build the storybook without invoking each skill by hand. Trigger on phrases like "run the pipeline on stories/my-story.md", "make a storybook from this", "turn this into a storybook", "build the storybook end to end", "process this story", or whenever the user drops an English story in stories/ and wants the full split → illustrate → narrate → HTML flow. Preserves every sub-skill's hard gate. Optionally accepts "with QA" to enable the illustrator's vision-QA pass.
In this repository7 other files it gives its agents.
- prompt-to-designSkill
- 3d-image-rendererSkill
- cf-imageSkill
- scene-splitterSkill
- story-html-publisherSkill
- story-illustratorSkill
- story-narratorSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 6 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Does NOT apply to:
- Very specific: line 45
Determine the slug: Read line 1 (the # Title) + the filename.
- Very specific: line 48
Check for the QA flag: If the user said "with QA" / "--qa", note qa_enabled = true for the illustrator.
- Distinctive: line 49
Ask the image aspect ratio AND model up front — HARD GATES: Don't wait until Stage 2; settle both now so the long stages run uninterrupted:
- Very specific: line 65
If qa_enabled, add "with QA"
- Distinctive: line 102
If the user wants to fully automate (skip gates), that's their call to make explicitly — the orchestrator never decides it.
- Distinctive: line 113
Does NOT bypass any sub-skill's hard gate.
- Distinctive: line 114
Does NOT generate content itself — it only dispatches.
- Very specific: line 115
Does NOT write a story for the user — input is a finished English .md (this pipeline illustrates + narrates + exports.
- Distinctive: line 116
Does NOT support multi-story batch runs in one call.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Storybook Pipeline (Orchestrator)
The runbook for turning one English story into a finished, self-contained HTML storybook. It does no creative work itself — it dispatches the 4 component skills in order, with the right artifact paths, and locks the filename convention so every output pairs cleanly by scene index.
It exists so that in a fresh session, "make a storybook from this story" has a single entry point — no need to remember the 4 skills, their order, or the filename conventions.
When this skill applies
The user has an English story (typically in stories/) and wants the full output: scenes + images + audio + a single HTML storybook. Common phrasings:
- "run the pipeline on
stories/the-little-cloud.md" - "make a storybook from this story"
- "turn this into an illustrated storybook"
- "build the storybook end to end"
Does NOT apply to:
- Single-step requests — if they only want images, invoke
story-illustrator; only audio,story-narrator. The orchestrator is for the full chain. - Re-running after partial completion — if some artifacts exist, detect them and resume from the next missing step; don't blindly overwrite. Ask if unsure.
Pipeline order (LOCKED)
input: stories/{slug}.md
1. scene-splitter → {slug}_scenes.json
2. story-illustrator → {slug}_bible.md, {slug}_shotlist.md, {slug}_images.json
3. story-narrator → {slug}_audio/{slug}_part_NN.mp3 (+ manifest.json, optional title.mp3)
4. story-html-publisher → {slug}_story.json + {slug}.html ← the deliverableSteps 2 and 3 both read {slug}_scenes.json and are independent — but in an interactive session run them in order so the user reviews each at its own gate.
Slug + filename convention (LOCKED)
The slug is derived from the story title or filename: lowercased, hyphenated, ASCII-safe (^[a-z0-9-]+$, max 60 chars). Every artifact shares it. All artifacts live in stories/{slug}/; the raw .md stays at stories/ (it's the trigger, not an artifact). See CLAUDE.md for the full filename table.
Workflow — five dispatch stages
Stage 0: Intake
- Identify the story file (explicit argument → the single new
*.mdinstories/→ ask). - Determine the slug. Read line 1 (the
# Title) + the filename; propose a slug. One-line confirm: "Slug:the-little-cloud. OK?" — proceed ongo. (HARD GATE — locks the slug into every artifact.) - Create the working dir
stories/{slug}/. All sub-skills output there. - Detect completed stages. Glob for
stories/{slug}/{slug}_scenes.json,_images.json, etc. If any exist, list them and ask: skip those stages or redo? Default = skip completed. - Check for the QA flag. If the user said "with QA" / "--qa", note
qa_enabled = truefor the illustrator. Default OFF. - Ask the image aspect ratio AND model up front — HARD GATES. Don't wait until Stage 2; settle both now so the long stages run uninterrupted:
"What aspect ratio?
4:5portrait (storybook / phone — the default),1:1square,3:4book page, or16:9widescreen." "Which image model?nano-banana-2(fast & cheap, ~$0.08/img),nano-banana-pro(best for multi-character, ~$0.15/img), Smart mix (pro only for multi-character beats — suggested), orseedream-4(cheapest, ~$0.03/img). Seeimage-models.json." Lock them asaspect_ratioand the model choice and pass both to the illustrator at Stage 2. Ask — do not infer. Aspect ratio locks into every image; both gates spend money. They pause even under an auto-mode reminder. - Pre-flight checks:
stories/is writable;FAL_KEYis resolvable (python .claude/skills/story-illustrator/assets/fal_image.py --check— re-checked at Stage 2); the ElevenLabs MCP is connected (re-checked at Stage 3); and the user has (or will provide) an ElevenLabsvoice_idfor the narrator.
Stage 1: Dispatch scene-splitter
Invoke scene-splitter with the story path, the slug, and output dir stories/{slug}/. The user approves the scene plan at its hard gate. Output: {slug}_scenes.json — the spine for stages 2 + 3.
Stage 2: Dispatch story-illustrator
Invoke story-illustrator with:
stories/{slug}/{slug}_scenes.jsonand the slug- A style hint from the story's tone (e.g. "warm soft watercolor children's-book illustration" for a gentle beginner story)
- Pre-locked aspect ratio + model from Stage 0: "Aspect ratio:
{aspect_ratio}(already chosen, do not re-ask). Image model:{model choice}(already chosen, do not re-ask)." - If
qa_enabled, add "with QA" - A note: "Generate one image per scene, indexed to match
scenes.json. Save{slug}_bible.md,{slug}_shotlist.md,{slug}_images.jsontostories/{slug}/."
The illustrator's own aspect-ratio and model prompts are skipped because the orchestrator pre-supplied both. The user approves the bible (Stage 2 gate — remind them to verify child-safe character designs before approving, since fixing after generation costs a regen per image), the references, and the shot list / images. Each image costs money (Fal) — these are hard gates.
Stage 3: Dispatch story-narrator
Invoke story-narrator with:
stories/{slug}/{slug}_scenes.jsonand the slug- A note: "One MP3 per scene, saved as
{slug}_part_NN.mp3instories/{slug}/{slug}_audio/. Detectscenes.jsonand skip your own splitting." - The ElevenLabs
voice_idif known (else the narrator asks once)
The user approves the narration script at the narrator's hard gate (each TTS call is billed). Output: {slug}_audio/ with N MP3s + manifest.
Stage 4: Dispatch story-html-publisher
Invoke story-html-publisher with the slug. It discovers the artifacts automatically, runs the build script, and writes {slug}_story.json + {slug}.html. The user reviews the finished storybook at its hard gate and replies done.
Stage 5: Final summary
One-screen summary:
- Artifacts produced (with paths) — ending with the headline:
stories/{slug}/{slug}.html - Total cost: Fal images (~$X, from the per-scene models) + ElevenLabs narration
- "Open
stories/{slug}/{slug}.htmlin your browser to read the finished storybook."
Gates — preserved, not bypassed
This orchestrator does NOT auto-approve gates. Gates pause regardless of any auto-mode / "work without stopping" reminder — that reminder applies to read-only work, not to gates that spend money or commit a creative choice.
| Skill | Gate | Why preserve |
| (orchestrator) | slug + aspect ratio + image model | Lock into every artifact / every image; the model spends money |
| scene-splitter | scene plan | Wrong boundaries → wrong image AND wrong audio |
| story-illustrator | bible, references, shot list/images (+QA) | Each image costs money (Fal); bad bible → bad images; child-safe check |
| story-narrator | narration script | Each TTS call is billed; bad script wastes credits |
| story-html-publisher | final review | Last look before declaring done |
If the user wants to fully automate (skip gates), that's their call to make explicitly — the orchestrator never decides it.
Failure modes
- Story file not found → stop at Stage 0, list
stories/, ask which file. - Slug already has artifacts → list them, ask skip/replace, default skip (resume).
- A sub-skill returns
redo→ re-invoke that skill with the corrective input; don't re-run upstream stages. FAL_KEYmissing (Stage 2) or ElevenLabs MCP unavailable (Stage 3) → surface the error, suggest setup (README). The publisher can build a partial storybook if only one medium is missing — but ask first.
What this skill does NOT do
- Does NOT bypass any sub-skill's hard gate.
- Does NOT generate content itself — it only dispatches.
- Does NOT write a story for the user — input is a finished English
.md(this pipeline illustrates + narrates + exports; it doesn't author). - Does NOT support multi-story batch runs in one call.
Reference files
- scene-splitter/SKILL.md
- story-illustrator/SKILL.md
- story-narrator/SKILL.md
- story-html-publisher/SKILL.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

