baoyu-comic

# 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: ```yaml 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](#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](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](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](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](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/config/preferences-schema.md). ## References **Core Templates**: - [analysis-framework.md](references/analysis-framework.md) - Deep content analysis - [character-template.md](references/character-template.md) - Character definition format - [storyboard-template.md](references/storyboard-template.md) - Storyboard structure - [ohmsha-guide.md](references/ohmsha-guide.md) - Ohmsha manga specifics **Style Definitions**: