webtoon-story-telling

name

webtoon-story-telling

description

Design, create, revise, and validate vertical-scroll webtoon episodes, storyboards, panels, sketches, section plans, character acting, short dialogue, sound effects, balloons, and scroll pacing. Use when turning plot or canon into episode source under episodes/; planning cuts, camera, action, expression, balloon placement, or panel-to-panel transitions; generating speech-balloon-free panel art with approved character/background assets; lettering approved art; or checking episode and visual continuity before publication.

Webtoon Story Telling

Operating Contract

Turn canon into a narratively understandable top-to-bottom episode contract. Define what every beat changes, what the reader can infer, short dialogue, and continuity; then invoke $direct-webtoon to translate those narrative requirements into visual direction before any storyboard image, sketch, or final panel is generated.

Read AGENTS.md, project.md, style/000.storytelling-guide.md, style/lettering-guide.md, the target plot/continuity sources, and only the linked character/background/material/MacGuffin files. Read episode-contract.md when creating or revising episode source.

Before bundled scripts, call load_workspace_dependencies, set PYTHON to the returned executable, and use locked uv run --frozen --python "$PYTHON" python ... commands below.

Use $imagegen for all generated panel, sketch, transition, or environmental art. Never ask image generation to render speech/thought balloons or their text. SFX, onomatopoeia, captions, signage-like story text, and other non-balloon typography that must visually belong to the background are part of generated panel art. Letter only approved speech/thought balloons with the bundled deterministic renderer.

Workflow

1. Establish The Episode Contract

Define:

• entry reader model: what is known, suspected, wanted, and predicted;
• episode promise and one governing dramatic question;
• inherited character, relationship, location, prop, costume, injury, and world state;
• causal change chain: orientation → pressure → reaction → choice → consequence → hook;
• reveal/evidence plan and facts that must remain hidden or ambiguous;
• exit reader model and next-episode pull;
• total height, panel count, silence, density, and section budget.

Do not invent missing canon silently. List contradictions or author decisions before fixing them.

2. Build The Narrative Beat Map

Give every panel one primary story function. For each beat define:

• what changes or what the reader can infer;
• required action, emotion, reaction, and spatial information;
• provisional shot/reveal intent and required character/background asset versions;
• scroll reveal distance, panel height, border/bleed, and transition;
• dialogue job, if any;
• continuity in/out.

Use dialogue only when it adds intent, leverage, subtext, relationship, evidence, or reinterpretation. Remove lines that name visible action or emotion. Use silent reaction panels when the reaction is the story.

3. Plan Balloons Before Final Art

Balloon order is top-to-bottom, then left-to-right within a shared vertical band. Record every balloon in panel frontmatter:

balloons:
  - id: balloon-001
    order: 1
    kind: speech
    speaker: char-hero
    text: "짧은 대사"
    box: [48, 40, 310, 178]
    tail_target: [360, 300]
    style: speech
    safe_margin: 24

Use speech or thought. Keep ordinary panels to at most three balloons unless the density is intentional. Tails must identify the speaker without crossing other tails, text, faces, or required action. Keep all text and tails away from section seams.

Record non-balloon text separately for generative integration:

integrated_text:
  - id: sfx-001
    kind: onomatopoeia
    text: "쿵"
    placement: [0.58, 0.18, 0.30, 0.22]
    scale: "large"
    color: "#A84B45"
    contrast: "readable against the dark wall without dominating the face"
    perspective: "tilted with the wall plane"
    interaction: "partly occluded by dust, never by the balloon safe area"

Include these exact requirements in the owning $imagegen prompt. Visually verify spelling, shape, color, contrast, perspective, occlusion, and compositional integration. A failed integrated text item requires regeneration of its panel/section; do not paste generic renderer text over it.

4. Write Episode Source

Prepare one reviewed JSON payload and use the bundled writer:

uv run --frozen --python "$PYTHON" python .agents/skills/webtoon-story-telling/scripts/write_episode.py \
  --project-root . --input /absolute/path/to/episode.json

The script creates episodes/ep.NN/episode.md, storyboard.md, panels/NNN.md, and sections/NNN.md, refuses collisions unless explicitly forced, and keeps numbers, IDs, and paths synchronized. Use _template only as a schema reference; never publish it.

For revisions, edit only the requested canonical files and preserve created, IDs, numbering, author text, and approved asset-version pins.

5. Invoke Direction Before Storyboard Images

Hand the approved episode contract, beats, dialogue/balloon plan, integrated-text requirements, continuity, and pinned visual asset versions to $direct-webtoon. It must enrich every panel's direction block before any visual job:

1. character blocking, pose, expression, gaze, depth, facing, and asset view;
2. camera size, height, angle, lens, movement, focus, and reveal timing;
3. background asset/view, spatial staging, lighting, atmosphere, and effects;
4. balloon-safe regions and every exact approved integrated_text item;
5. transition in/out and relationship to neighboring panels.

$direct-webtoon then owns storyboard/sketch prompts, final panel generation prompts, grounding images, generation QA, and provenance. It generates independent panel/section-scale jobs rather than one 10,000px image. Only normalized approved character/background assets may ground composition. If directed art establishes a new canonical fact, update the relevant character/background/world/material source.

6. Letter Approved Panels

Render balloons onto a 690px-wide approved panel:

uv run --frozen --python "$PYTHON" python .agents/skills/webtoon-story-telling/scripts/letter_panel.py \
  --input assets/episodes/ep.01/panels/001.png \
  --panel-md episodes/ep.01/panels/001.md \
  --output assets/episodes/ep.01/lettered/001.png \
  --font /absolute/path/to/approved-font.ttf

The renderer accepts only speech and thought balloons and owns their wrapping, fill/stroke, tail geometry, and deterministic output. It must reject SFX, captions, or other integrated text. Inspect the final image visually; code cannot decide whether a balloon covers an important face or gesture.

7. Hand Off To Direction

After $direct-webtoon has approved the storyboard images and final panels, keep the same direction contract for section composition. That skill owns final crop, scale, position, overlap, negative space, color script, generated bridge/ambient layers, scroll reveals, full-scroll preview, and safe seam approval.

Do not mark a section final from this skill alone. $direct-webtoon must compose the final 690×2,000–4,000px section source, preserve the approved panel order and text, set direction_approved: true, and approve the outgoing seam. $publish-webtoon consumes only this approved direction output.

8. Validate

Run:

uv run --frozen --python "$PYTHON" python .agents/skills/webtoon-story-telling/scripts/check_webtoon.py \
  --project-root . --strict

Resolve errors. Review warnings for dialogue density, missing visual pins, short episodes, or incomplete source art. Then run an independent continuity/lettering/render pass when subagents are available.

Repair Policy

• Repair numbering, paths, layout metadata, wrapping, or chroma deterministically when the source art is correct.
• Regenerate only the failed panel/section visual when identity, action, expression, spatial meaning, or crop is wrong.
• If several failures share the same character/background asset, repair that canonical asset version before more panel generation.
• Never raster-warp faces/anatomy or hide drift with effects.
• Do not replace approved source or published images in place; create a new version and republish.

Completion Gate

Do not finish until the episode has a material entry-to-exit change, every panel has a story function, balloon order is unambiguous, dialogue is concise, integrated text is exact and visually grounded, required inferences have visible evidence, panels pin approved asset versions, the direction handoff is complete, structural validation passes, and new canon is reflected in source and continuity files. Final section composition and seam approval belong to $direct-webtoon.