agentleFS
hassancs91hassancs91/claude-image-generation/.claude/skills/storybook-pipeline/SKILL.md

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.

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
  1. Distinctive:

    Does NOT apply to:

    line 20
  2. Very specific:

    Determine the slug: Read line 1 (the # Title) + the filename.

    line 45
  3. Very specific:

    Check for the QA flag: If the user said "with QA" / "--qa", note qa_enabled = true for the illustrator.

    line 48
  4. Distinctive:

    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:

    line 49
  5. Very specific:

    If qa_enabled, add "with QA"

    line 65
  6. Distinctive:

    If the user wants to fully automate (skip gates), that's their call to make explicitly — the orchestrator never decides it.

    line 102
  7. Distinctive:

    Does NOT bypass any sub-skill's hard gate.

    line 113
  8. Distinctive:

    Does NOT generate content itself — it only dispatches.

    line 114
  9. Very specific:

    Does NOT write a story for the user — input is a finished English .md (this pipeline illustrates + narrates + exports.

    line 115
  10. Distinctive:

    Does NOT support multi-story batch runs in one call.

    line 116

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 deliverable

Steps 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

  1. Identify the story file (explicit argument → the single new *.md in stories/ → ask).
  2. Determine the slug. Read line 1 (the # Title) + the filename; propose a slug. One-line confirm: "Slug: the-little-cloud. OK?" — proceed on go. (HARD GATE — locks the slug into every artifact.)
  3. Create the working dir stories/{slug}/. All sub-skills output there.
  4. 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.
  5. Check for the QA flag. If the user said "with QA" / "--qa", note qa_enabled = true for the illustrator. Default OFF.
  6. 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:5 portrait (storybook / phone — the default), 1:1 square, 3:4 book page, or 16:9 widescreen." "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), or seedream-4 (cheapest, ~$0.03/img). See image-models.json." Lock them as aspect_ratio and 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.

  7. Pre-flight checks: stories/ is writable; FAL_KEY is 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 ElevenLabs voice_id for 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.json and 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.json to stories/{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.json and the slug
  • A note: "One MP3 per scene, saved as {slug}_part_NN.mp3 in stories/{slug}/{slug}_audio/. Detect scenes.json and skip your own splitting."
  • The ElevenLabs voice_id if 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}.html in 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.

SkillGateWhy preserve
(orchestrator)slug + aspect ratio + image modelLock into every artifact / every image; the model spends money
scene-splitterscene planWrong boundaries → wrong image AND wrong audio
story-illustratorbible, references, shot list/images (+QA)Each image costs money (Fal); bad bible → bad images; child-safe check
story-narratornarration scriptEach TTS call is billed; bad script wastes credits
story-html-publisherfinal reviewLast 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_KEY missing (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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.