Baoyu Comic

Operational Steps

1. 确认输入参数完整
2. 执行核心操作（参考本目录下的 scripts/ 或 references/）
3. 验证输出符合契约
4. 保存结果并报告

IO_CONTRACT

• input: request: str, context: dict — 用户请求描述、上下文信息
• output: result: dict — 技能执行结果（结构因技能而异）

对应原则：P2（机械原子暴露输入输出规范）

Knowledge Comic Creator

Adapted from baoyu-comic for Hermes Agent's tool ecosystem.

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

When to Use

Trigger this skill when the user asks to create a knowledge/educational comic, biography comic, tutorial comic, or uses terms like "知识漫画", "教育漫画", or "Logicomix-style". The user provides content (text, file path, URL, or topic) and optionally specifies art style, tone, layout, aspect ratio, or language.

Reference Images

Hermes' image_generate tool is prompt-only — it accepts a text prompt and an aspect ratio, and returns an image URL. It does NOT accept reference images. When the user supplies a reference image, use it to extract traits in text that get embedded in every page prompt:

Intake: Accept file paths when the user provides them (or pastes images in conversation).

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

Usage modes (per reference):

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

references:
  - ref_id: 01
    filename: 01-ref-scene.png
    usage: style
    traits: "muted earth tones, soft-edged ink wash, low-contrast backgrounds"

Character consistency is driven by text descriptions in characters/characters.md (written in Step 3) that get embedded inline in every page prompt (Step 5). The optional PNG character sheet generated in Step 7.1 is a human-facing review artifact, not an input to image_generate.

Options

Visual Dimensions

Partial Workflow Options

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.

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:

Language Handling

Detection Priority:

1. User-specified language (explicit option)
2. User's conversation language
3. Source content language

Rule: Use user's input language 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 Analyze content
  - [ ] 1.2 Check existing directory
- [ ] 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 character descriptions embedded in prompt)
- [ ] Step 8: Completion report

Flow

Input → Analyze → [Check Existing?] → [Confirm: Style + Reviews] → Storyboard → [Review?] → Prompts → [Review?] → Images → Complete

Step Summary

User Questions

Use the clarify tool to confirm options. Since clarify handles one question at a time, ask the most important question first and proceed sequentially. See references/workflow.md for the full Step 2 question set.

Timeout handling (CRITICAL): clarify can return "The user did not provide a response within the time limit. Use your best judgement to make the choice and proceed." — this is NOT user consent to default everything.

• Treat it as a default for that one question only. Continue asking the remaining Step 2 questions in sequence; each question is an independent consent point.
• Surface the default to the user visibly in your next message so they have a chance to correct it: e.g. "Style: defaulted to ohmsha preset (clarify timed out). Say the word to switch." — an unreported default is indistinguishable from never having asked.
• Do NOT collapse Step 2 into a single "use all defaults" pass after one timeout. If the user is genuinely absent, they will be equally absent for all five questions — but they can correct visible defaults when they return, and cannot correct invisible ones.

Step 7: Image Generation

Use Hermes' built-in image_generate tool for all image rendering. Its schema accepts only prompt and aspect_ratio (landscape | portrait | square); it returns a URL, not a local file. Every generated page or character sheet must therefore be downloaded to the output directory.

Prompt file requirement (hard): write each image's full, final prompt to a standalone file under prompts/ (naming: NN-{type}-[slug].md) BEFORE calling image_generate. The prompt file is the reproducibility record.

Aspect ratio mapping — the storyboard's aspect_ratio field maps to image_generate's format as follows:

Download step — after every image_generate call:

1. Read the URL from the tool result
2. Fetch the image bytes using an absolute output path, e.g. curl -fsSL "<url>" -o /abs/path/to/comic/<slug>/NN-page-<slug>.png
3. Verify the file exists and is non-empty at that exact path before proceeding to the next page

Never rely on shell CWD persistence for -o paths. The terminal tool's persistent-shell CWD can change between batches (session expiry, TERMINAL_LIFETIME_SECONDS, a failed cd that leaves you in the wrong directory). curl -o relative/path.png is a silent footgun: if CWD has drifted, the file lands somewhere else with no error. Always pass a fully-qualified absolute path to -o, or pass workdir=<abs path> to the terminal tool. Incident Apr 2026: pages 06-09 of a 10-page comic landed at the repo root instead of comic/<slug>/ because batch 3 inherited a stale CWD from batch 2 and curl -o 06-page-skills.png wrote to the wrong directory. The agent then spent several turns claiming the files existed where they didn't.

7.1 Character sheet — generate it (to characters/characters.png, aspect landscape) when the comic is multi-page with recurring characters. Skip for simple presets (e.g., four-panel minimalist) or single-page comics. The prompt file at characters/characters.md must exist before invoking image_generate. The rendered PNG is a human-facing review artifact (so the user can visually verify character design) and a reference for later regenerations or manual prompt edits — it does not drive Step 7.2. Page prompts are already written in Step 5 from the text descriptions in characters/characters.md; image_generate cannot accept images as visual input.

7.2 Pages — each page's prompt MUST already be at prompts/NN-{cover|page}-[slug].md before invoking image_generate. Because image_generate is prompt-only, character consistency is enforced by embedding character descriptions (sourced from characters/characters.md) inline in every page prompt during Step 5. The embedding is done uniformly whether or not a PNG sheet is produced in 7.1; the PNG is only a review/regeneration aid.

Backup rule: existing prompts/…md and …png files → rename with -backup-YYYYMMDD-HHMMSS suffix before regenerating.

Full step-by-step workflow (analysis, storyboard, review gates, regeneration variants): references/workflow.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

Page Modification

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.

Pitfalls

-

-

Verification

-

-

• Image generation: 10-30 seconds per page; auto-retry once on failure
• Always download the URL returned by image_generate to a local PNG — downstream tooling (and the user's review) expects files in the output directory, not ephemeral URLs
• Use absolute paths for curl -o — never rely on persistent-shell CWD across batches. Silent footgun: files land in the wrong directory and subsequent ls on the intended path shows nothing. See Step 7 "Download step".
• Use stylized alternatives for sensitive public figures
• 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. The PNG is a review/regeneration aid; page prompts (written in Step 5) use the text descriptions in characters/characters.md, not the PNG. image_generate does not accept images as visual input
• Strip secrets — scan source content for API keys, tokens, or credentials before writing any output file

验证清单 · VERIFICATION

• Step 2 风格确认已完成（未跳过）；clarify 超时导致的默认选择已逐条向用户显式展示，未折叠为全默认
• 每页/封面调用 image_generate 前，其最终提示词已写入 prompts/NN-{cover|page}-[slug].md；角色描述已内联嵌入每一页提示词（角色一致性靠文本而非参考图）
• 每个返回 URL 已用绝对路径 curl -fsSL 下载到 comic/{topic-slug}/ 下的对应 PNG，且下载后验证文件存在且非空
• 输出目录结构完整：source-{slug}.md、analysis.md、storyboard.md、characters/、prompts/、各页 PNG 齐全；参考图已拷贝至 refs/ 并在页面 frontmatter 记录 usage/traits
• 敏感公众人物已用风格化替代；源内容已扫描并剔除 API key/token 等凭据后才写入任何输出文件

约束规则 · RULES

1. 输入约束: 参数类型、范围、格式必须校验
2. 输出约束: 返回值结构、编码、命名必须一致
3. 异常约束: 错误信息必须包含上下文和恢复建议
4. 安全约束: 不执行未验证的任意代码，不暴露内部状态

Golden 集合 · GOLDEN SET

• Golden Input: 标准输入样本（覆盖正常路径）
• Golden Output: 预期输出（精确匹配或格式校验）
• Golden Error: 预期错误信息（覆盖失败路径）

Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

违反规则的操作视为不安全，必须拒绝或隔离。

每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

Baoyu Comic

Genes (策略基因)

紧凑策略表示。条件→策略。需要深度时参考完整文档。

• [BAOY-001] 用户提供参考图片时 → 提取风格/色彩/场景特征转化为文本描述嵌入提示词，而非直接传入图像模型
• [BAOY-002] 需要保持角色一致性时 → 在 characters.md 中定义详细文本描述，并在每一页的生成提示词中内联嵌入
• [BAOY-003] 确定视觉风格时 → 优先匹配预设组合（如 ohmsha, wuxia），若未命中则根据内容信号自动推荐 Art+Tone 组合
• [BAOY-004] 处理多语言交互时 → 严格遵循“用户指定 > 对话语言 > 源内容语言”的优先级，所有交互及提示词均使用用户语言
• [BAOY-005] 执行生成流程时 → 在风格确认、大纲审查、提示词审查等关键节点设置条件性用户确认环节
• [BAOY-006] 处理部分生成需求时 → 支持仅生成分镜、仅生成提示词或仅重新生成指定页码，跳过无关步骤
• [BAOY-007] 管理输出文件时 → 采用 comic/{topic-slug}/ 目录结构，冲突时追加时间戳，并保留参考图副本以溯源