Agent Skills: Knowledge Comic Creator

Knowledge Comic Creator

Create original knowledge comics with flexible art style × tone combinations.

User Input Tools

When this skill prompts the user, follow this tool-selection rule (priority order):

1. Prefer built-in user-input tools exposed by the current agent runtime — e.g., AskUserQuestion, request_user_input, clarify, ask_user, or any equivalent.
2. Fallback: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
3. Batching: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.

Concrete AskUserQuestion references below are examples — substitute the local equivalent in other runtimes.

Image Generation Tools

When this skill needs to render an image, resolve the backend in this order:

1. Current-request override — if the user names a specific backend in the current message, use it.
2. Saved preference — if EXTEND.md sets preferred_image_backend to a backend available right now, use it.
3. Auto-select (when the preference is auto, unset, or the pinned backend isn't available):
   • If the current runtime exposes a native image tool (e.g., Codex imagegen, Hermes image_generate), use it. Runtime-native tools are preferred by default — agents that know their own tool inventory should surface the native one here.
   • Otherwise, if exactly one non-native backend is installed (e.g., baoyu-imagine), use it.
   • Otherwise (multiple non-native backends with no runtime-native tool), ask the user once — batch with any other initial questions.
4. If none are available, tell the user and ask how to proceed.

Setting preferred_image_backend: ask forces the step-3 prompt every run regardless of available backends. Users change the pinned backend via the ## Changing Preferences section below.

Prompt file requirement (hard): write each image's full, final prompt to a standalone file under prompts/ (naming: NN-{type}-[slug].md) BEFORE invoking any backend. The backend receives the prompt file (or its content); the file is the reproducibility record and lets you switch backends without regenerating prompts.

Concrete tool names (imagegen, image_generate, baoyu-imagine) above are examples — substitute the local equivalents under the same rule.

Reference Images

Users may supply reference images to guide art style, palette, scene composition, or subject. This is separate from the auto-generated character sheet (Step 7.1) — both can coexist: user refs guide the look, the character sheet anchors recurring character identity.

Intake: Accept via --ref <files...> or when the user provides file paths / pastes images in conversation.

• File path(s) → copy to refs/NN-ref-{slug}.{ext} alongside the comic output
• Pasted image with no path → ask the user for the path (per the User Input Tools rule above), or extract style traits verbally as a text fallback
• No reference → skip this section

Usage modes (per reference):

| Usage | Effect | |-------|--------| | direct | Pass the file to the backend as a reference image on every page (or selected pages) | | style | Extract style traits (line treatment, texture, mood) and append to every page's prompt body | | palette | Extract hex colors and append to every page's prompt body |

Record in each page's prompt frontmatter when refs exist:

references:
  - ref_id: 01
    filename: 01-ref-scene.png
    usage: direct

At generation time:

• Verify each referenced file exists on disk
• If usage: direct AND the chosen backend accepts multiple reference images → pass both the character sheet (Step 7.2) and the user refs via the backend's ref parameter; compress images first per Step 7.1's guidance to avoid payload failures
• If the backend accepts only one ref → prefer the character sheet for pages with recurring characters; embed user-ref traits in the prompt body instead
• For style/palette usage → embed extracted traits in every page's prompt text (applies regardless of backend capability)

Options

Visual Dimensions

| Option | Values | Description | |--------|--------|-------------| | --art | ligne-claire (default), manga, realistic, ink-brush, chalk, minimalist | Art style / rendering technique | | --tone | neutral (default), warm, dramatic, romantic, energetic, vintage, action | Mood / atmosphere | | --layout | standard (default), cinematic, dense, splash, mixed, webtoon, four-panel | Panel arrangement | | --aspect | 3:4 (default, portrait), 4:3 (landscape), 16:9 (widescreen) | Page aspect ratio | | --lang | auto (default), zh, en, ja, etc. | Output language | | --ref <files...> | File paths | Reference images applied to every page for style / palette / scene guidance. See Reference Images above. |

Partial Workflow Options

| Option | Description | |--------|-------------| | --storyboard-only | Generate storyboard only, skip prompts and images | | --prompts-only | Generate storyboard + prompts, skip images | | --images-only | Generate images from existing prompts directory | | --regenerate N | Regenerate specific page(s) only (e.g., 3 or 2,5,8) |

Details: references/partial-workflows.md

Art, Tone & Preset Catalogue

• Art styles (6): ligne-claire, manga, realistic, ink-brush, chalk, minimalist. Full definitions at references/art-styles/<style>.md.

• Tones (7): neutral, warm, dramatic, romantic, energetic, vintage, action. Full definitions at references/tones/<tone>.md.

• Presets (5) with special rules beyond plain art+tone:

  | Preset | Equivalent | Hook | |--------|-----------|------| | ohmsha | manga + neutral | Visual metaphors, no talking heads, gadget reveals | | wuxia | ink-brush + action | Qi effects, combat visuals, atmospheric | | shoujo | manga + romantic | Decorative elements, eye details, romantic beats | | concept-story | manga + warm | Visual symbol system, growth arc, dialogue+action balance | | four-panel | minimalist + neutral + four-panel layout | 起承转合 structure, B&W + spot color, stick-figure characters |

  Full rules at references/presets/<preset>.md — load the file when a preset is picked.

• Compatibility matrix and content-signal → preset table live in references/auto-selection.md. Read it before recommending combinations in Step 2.

Script Directory

Important: All scripts are located in the scripts/ subdirectory of this skill.

Agent Execution Instructions:

1. Determine this SKILL.md file's directory path as {baseDir}
2. Script path = {baseDir}/scripts/<script-name>.ts
3. Replace all {baseDir} in this document with the actual path
4. Resolve ${BUN_X} runtime: if bun installed → bun; if npx available → npx -y bun; else suggest installing bun

Script Reference: | Script | Purpose | |--------|---------| | scripts/merge-to-pdf.ts | Merge comic pages into PDF |

File Structure

Output directory: comic/{topic-slug}/

• Slug: 2-4 words kebab-case from topic (e.g., alan-turing-bio)
• Conflict: append timestamp (e.g., turing-story-20260118-143052)

Contents: | File | Description | |------|-------------| | source-{slug}.{ext} | Source files | | analysis.md | Content analysis | | storyboard.md | Storyboard with panel breakdown | | characters/characters.md | Character definitions | | characters/characters.png | Character reference sheet | | prompts/NN-{cover\|page}-[slug].md | Generation prompts | | NN-{cover\|page}-[slug].png | Generated images | | {topic-slug}.pdf | Final merged PDF |

Language Handling

Detection Priority:

1. --lang flag (explicit)
2. EXTEND.md language setting
3. User's conversation language
4. Source content language

Rule: Use user's input language or saved language preference for ALL interactions:

• Storyboard outlines and scene descriptions
• Image generation prompts
• User selection options and confirmations
• Progress updates, questions, errors, summaries

Technical terms remain in English.

Workflow

Progress Checklist

Comic Progress:
- [ ] Step 1: Setup & Analyze
  - [ ] 1.1 Preferences (EXTEND.md) ⛔ BLOCKING
    - [ ] Found → load preferences → continue
    - [ ] Not found → run first-time setup → MUST complete before other steps
  - [ ] 1.2 Analyze, 1.3 Check existing
- [ ] Step 2: Confirmation - Style & options ⚠️ REQUIRED
- [ ] Step 3: Generate storyboard + characters
- [ ] Step 4: Review outline (conditional)
- [ ] Step 5: Generate prompts
- [ ] Step 6: Review prompts (conditional)
- [ ] Step 7: Generate images
  - [ ] 7.1 Generate character sheet (if needed) → characters/characters.png
  - [ ] 7.2 Generate pages (with --ref if character sheet exists)
- [ ] Step 8: Merge to PDF
- [ ] Step 9: Completion report

Flow

Input → [Preferences] ─┬─ Found → Continue
                       │
                       └─ Not found → First-Time Setup ⛔ BLOCKING
                                      │
                                      └─ Complete setup → Save EXTEND.md → Continue
                                                                              │
        ┌─────────────────────────────────────────────────────────────────────┘
        ↓
Analyze → [Check Existing?] → [Confirm: Style + Reviews] → Storyboard → [Review?] → Prompts → [Review?] → Images → PDF → Complete

Step Summary

| Step | Action | Key Output | |------|--------|------------| | 1.1 | Load EXTEND.md preferences ⛔ BLOCKING if not found | Config loaded | | 1.2 | Analyze content | analysis.md | | 1.3 | Check existing directory | Handle conflicts | | 2 | Confirm style, focus, audience, reviews | User preferences | | 3 | Generate storyboard + characters | storyboard.md, characters/ | | 4 | Review outline (if requested) | User approval | | 5 | Generate prompts | prompts/*.md | | 6 | Review prompts (if requested) | User approval | | 7.1 | Generate character sheet (if needed) | characters/characters.png | | 7.2 | Generate pages (with character ref if available) | *.png files | | 8 | Merge to PDF | {slug}.pdf | | 9 | Completion report | Summary |

Step 7: Image Generation

Pick a backend once per session using the ## Image Generation Tools rule at the top. If the backend is a repo skill (e.g., baoyu-imagine), read its SKILL.md and use its documented interface rather than its scripts.

7.1 Character sheet — generate it (to characters/characters.png, aspect 4:3) when the comic is multi-page with recurring characters. Skip for simple presets (e.g., four-panel minimalist) or single-page comics. Compress to JPEG before use-as---ref (sips -s format jpeg -s formatOptions 80 … on macOS, pngquant --quality=65-80 … elsewhere) to avoid payload failures. The prompt file at characters/characters.md must exist before invoking the backend.

7.2 Pages — each page's prompt MUST already be at prompts/NN-{cover|page}-[slug].md before invoking the backend; the file is the reproducibility record. Strategy depends on the character sheet:

| Character sheet | Backend --ref | Strategy | |-----------------|-----------------|----------| | Exists | Supported | Pass sheet as --ref on every page | | Exists | Not supported | Prepend character descriptions to every prompt file | | Skipped | — | All descriptions inline in prompt |

Backup rule: existing prompts/…md and …png files → rename with -backup-YYYYMMDD-HHMMSS suffix before regenerating. Aspect ratio from storyboard (default 3:4; preset may override).

--ref failure recovery: compress sheet → retry → still fails → drop --ref and embed character descriptions in the prompt text.

Full step-by-step workflow (analysis, storyboard, review gates, regeneration variants): references/workflow.md.

EXTEND.md Paths ⛔ BLOCKING

If EXTEND.md is not found, first-time setup is blocking — complete it before any content analysis or style/tone questions.

| Priority | Path | Scope | |----------|------|-------| | 1 | .baoyu-skills/baoyu-comic/EXTEND.md | Project | | 2 | $HOME/.baoyu-skills/baoyu-comic/EXTEND.md | User home |

| Result | Action | |--------|--------| | Found | Read, parse, display summary → continue | | Not found | ⛔ Run first-time setup (references/config/first-time-setup.md) → save EXTEND.md → continue |

EXTEND.md supports: watermark, preferred art/tone/layout, custom style definitions, character presets, language preference. Schema: references/config/preferences-schema.md.

References

Core Templates:

• analysis-framework.md - Deep content analysis
• character-template.md - Character definition format
• storyboard-template.md - Storyboard structure
• ohmsha-guide.md - Ohmsha manga specifics

Style Definitions:

• references/art-styles/ - Art styles (ligne-claire, manga, realistic, ink-brush, chalk, minimalist)
• references/tones/ - Tones (neutral, warm, dramatic, romantic, energetic, vintage, action)
• references/presets/ - Presets with special rules (ohmsha, wuxia, shoujo, concept-story, four-panel)
• references/layouts/ - Layouts (standard, cinematic, dense, splash, mixed, webtoon, four-panel)

Workflow:

• workflow.md - Full workflow details
• auto-selection.md - Content signal analysis
• partial-workflows.md - Partial workflow options

Config:

• config/preferences-schema.md - EXTEND.md schema
• config/first-time-setup.md - First-time setup
• config/watermark-guide.md - Watermark configuration

Page Modification

| Action | Steps | |--------|-------| | Edit | Update prompt file FIRST → --regenerate N → Regenerate PDF | | Add | Create prompt at position → Generate with character ref → Renumber subsequent → Update storyboard → Regenerate PDF | | Delete | Remove files → Renumber subsequent → Update storyboard → Regenerate PDF |

IMPORTANT: When updating pages, ALWAYS update the prompt file (prompts/NN-{cover|page}-[slug].md) FIRST before regenerating. This ensures changes are documented and reproducible.

Notes

• Image generation: 10-30 seconds per page
• Auto-retry once on generation failure
• Use stylized alternatives for sensitive public figures
• Maintain style consistency via session ID
• Step 2 confirmation required - do not skip
• Steps 4/6 conditional - only if user requested in Step 2
• Step 7.1 character sheet - recommended for multi-page comics, optional for simple presets
• Step 7.2 character reference - use --ref if sheet exists; compress/convert on failure; fall back to prompt-only
• Watermark/language configured once in EXTEND.md

Changing Preferences

EXTEND.md lives at .baoyu-skills/baoyu-comic/EXTEND.md (project) or ~/.baoyu-skills/baoyu-comic/EXTEND.md (user). Three ways to change it:

• Edit directly — open EXTEND.md and change fields. Full schema: references/config/preferences-schema.md.
• Reconfigure interactively — delete EXTEND.md (or ask "reconfigure baoyu-comic preferences" / "重新配置"). The next run re-triggers first-time setup.
• Common one-line edits:
  • preferred_image_backend: auto — default; runtime-native tool wins, falls back to the only installed backend, asks only if multiple non-native are present.
  • preferred_image_backend: codex-imagegen — pin to Codex's built-in.
  • preferred_image_backend: baoyu-imagine — pin to the baoyu-imagine skill.
  • preferred_image_backend: ask — confirm backend every run.
  • watermark.enabled: true, preferred_art, preferred_tone, preferred_layout, language — shift the auto-selection defaults and cosmetic choices.