mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-05-29 06:31:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 14

feat(skills): adapt baoyu-article-illustrator for Hermes

Browse source 
Adapts the upstream baoyu-article-illustrator skill (verbatim-copied in
the previous commit) to Hermes' tool ecosystem, matching the pattern
used by baoyu-infographic.

- Metadata: openclaw → hermes; add author, license, tags, category
- Triggering: slash command + CLI flags → natural language
- User config: remove EXTEND.md, first-time-setup, preferences-schema
- User prompts: AskUserQuestion (batched) → clarify (one at a time)
- Image gen: baoyu-imagine → image_generate (describe refs in prompt text)
- Platform: drop Windows/PowerShell; Linux/macOS only
- File ops: switch to write_file / read_file
- Watermark: opt-in per-article instead of EXTEND.md-driven
- Add PORT_NOTES.md describing the adaptation and sync procedure

Style, palette, and prompt/system.md reference files are verbatim copies
and are the sync points with upstream.
This commit is contained in:
Jim Liu 宝玉 2026-04-20 16:18:20 -05:00 • committed by Teknium
parent 680189b5de
commit 4bd297094a
9 changed files with 285 additions and 651 deletions
Download patch file Download diff file Expand all files Collapse all files

47
skills/creative/baoyu-article-illustrator/PORT_NOTES.md Normal file
View file

@ -0,0 +1,47 @@
# Port Notes — baoyu-article-illustrator
Ported from [JimLiu/baoyu-skills](https://github.com/JimLiu/baoyu-skills) v1.57.0.
## Changes from upstream
`SKILL.md`, `references/workflow.md`, `references/usage.md`, `references/style-presets.md`, `references/styles.md`, and `references/prompt-construction.md` were adapted. The 21 style files, 4 palette files, and `prompts/system.md` are verbatim copies. The `references/config/` directory was removed entirely.
### Adaptations
| Change | Upstream | Hermes |
|--------|----------|--------|
| Metadata namespace | `openclaw` | `hermes` |
| Trigger | `/baoyu-article-illustrator` slash command + CLI flags | Natural language skill matching |
| User config | EXTEND.md (project/user/XDG paths) + first-time-setup | Removed — not part of Hermes infra |
| User prompts | `AskUserQuestion` (batched, multi-question) | `clarify` tool (one question at a time) |
| Image generation | `baoyu-imagine` (Bun/TypeScript, multi-provider, accepts `--ref`) | `image_generate` tool (describes references in prompt text) |
| Platform support | Linux/macOS/Windows/WSL/PowerShell | Linux/macOS only |
| File operations | Bash commands | Hermes file tools (`write_file`, `read_file`) |
| Watermark | Driven by EXTEND.md `watermark.enabled` | Optional — user asks for it per-article |
| Output directory | EXTEND.md `default_output_dir` (imgs-subdir / same-dir / illustrations-subdir / independent) | Defaults based on input type; user overrides in request |
### What was preserved
- Type × Style × Palette three-dimension framework
- All style definitions (23 files)
- All palette definitions (4 files)
- Core reference files (workflow, prompt-construction, styles, style-presets)
- `prompts/system.md` (generation prompt template)
- Core principles and workflow structure (analyze → confirm → outline → prompts → generate)
- Prompt-file-as-reproducibility-record discipline
- Author, version, homepage attribution
## Syncing with upstream
To pull upstream updates:
```bash
# Compare versions
curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/SKILL.md | head -5
# Look for version: line
# Diff style/palette files (safe to overwrite — unchanged from upstream)
diff <(curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-article-illustrator/references/styles/blueprint.md) references/styles/blueprint.md
```
`references/styles/*`, `references/palettes/*`, and `prompts/system.md` can be overwritten directly. `SKILL.md`, `references/workflow.md`, `references/usage.md`, `references/style-presets.md`, `references/styles.md`, and `references/prompt-construction.md` must be manually merged since they contain Hermes-specific adaptations.

206
skills/creative/baoyu-article-illustrator/SKILL.md
View file

@ -2,42 +2,24 @@
name: baoyu-article-illustrator
description: Analyzes article structure, identifies positions requiring visual aids, generates illustrations with Type × Style × Palette three-dimension approach. Use when user asks to "illustrate article", "add images", "generate images for article", or "为文章配图".
version: 1.57.0
author: 宝玉 (JimLiu)
license: MIT
metadata:
openclaw:
hermes:
tags: [article-illustration, creative, image-generation]
category: creative
homepage: https://github.com/JimLiu/baoyu-skills#baoyu-article-illustrator
---
# Article Illustrator
Analyze articles, identify illustration positions, generate images with Type × Style × Palette consistency.
Adapted from [baoyu-article-illustrator](https://github.com/JimLiu/baoyu-skills) for Hermes Agent's tool ecosystem.
## User Input Tools
Analyze articles, identify illustration positions, generate images with **Type × Style × Palette** consistency.
When this skill prompts the user, follow this tool-selection rule (priority order):
## When to Use
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:
- **Use whatever image-generation tool or skill is available** in the current runtime — e.g., Codex `imagegen`, Hermes `image_generate`, `baoyu-imagine`, or any equivalent the user has installed.
- **If multiple are available**, ask the user **once** at the start which to use (batch with any other initial questions).
- **If none are available**, tell the user and ask how to proceed.
**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 via `--ref <files...>` or by providing file paths / pasting images in conversation. Refs guide style, palette, composition, or subject for specific illustrations.
Full detection, storage, and processing rules are in [references/workflow.md](references/workflow.md) (Step 1.0 saves to `references/NN-ref-{slug}.{ext}`; Step 5.3 processes per-illustration usage `direct | style | palette`). When the chosen backend supports batch input, `direct`-usage entries in each prompt file's `references:` frontmatter should be propagated into its batch payload so backends can pass them through (e.g. `baoyu-imagine` accepts `ref` per task).
Trigger this skill when the user asks to illustrate an article, add images to an article, generate illustrations for content, or uses phrases like "为文章配图", "illustrate article", or "add images". The user provides an article (file path or pasted content) and optionally specifies type, style, palette, or density.
## Three Dimensions
@ -47,9 +29,9 @@ Full detection, storage, and processing rules are in [references/workflow.md](re
| **Style** | Rendering approach | notion, warm, minimal, blueprint, watercolor, elegant |
| **Palette** | Color scheme (optional) | macaron, warm, neon — overrides style's default colors |
Combine freely: `--type infographic --style vector-illustration --palette macaron`
Combine freely: `type=infographic, style=vector-illustration, palette=macaron`.
Or use presets: `--preset edu-visual` → type + style + palette in one flag. See [Style Presets](references/style-presets.md).
Or use presets: `edu-visual` → type + style + palette in one shot. See [style-presets.md](references/style-presets.md).
## Types
@ -64,37 +46,58 @@ Or use presets: `--preset edu-visual` → type + style + palette in one flag. Se
## Styles
See [references/styles.md](references/styles.md) for Core Styles, full gallery, and Type × Style compatibility.
See [references/styles.md](references/styles.md) for Core Styles, the full gallery, and Type × Style compatibility.
## Output Structure
```
{output-dir}/
├── source-{slug}.{ext} # Only for pasted content
├── outline.md
├── prompts/
│ └── NN-{type}-{slug}.md
└── NN-{type}-{slug}.png
```
**Default output directory**:
| Input | Output Directory | Markdown Insert Path |
|-------|------------------|----------------------|
| Article file path | `{article-dir}/imgs/` | `imgs/NN-{type}-{slug}.png` |
| Pasted content | `illustrations/{topic-slug}/` (cwd) | `illustrations/{topic-slug}/NN-{type}-{slug}.png` |
If the user asks for a different layout (e.g., images alongside the article, or a `illustrations/` subdirectory), honor that.
**Slug**: 2-4 words, kebab-case. **Conflict**: append `-YYYYMMDD-HHMMSS`.
## Core Principles
- **Visualize concepts, not metaphors** — if the article uses a metaphor (e.g., "电锯切西瓜"), illustrate the underlying concept, not the literal image.
- **Labels use article data** — actual numbers, terms, and quotes from the article, not generic placeholders.
- **Prompt files are reproducibility records** — every illustration must have a saved prompt file under `prompts/` before any image is generated.
- **Strip secrets** — scan source content for API keys, tokens, or credentials before writing anything to disk.
## Workflow
```
- [ ] Step 1: Pre-check (EXTEND.md, references, config)
- [ ] Step 1: Detect reference images (if provided)
- [ ] Step 2: Analyze content
- [ ] Step 3: Confirm settings (AskUserQuestion)
- [ ] Step 3: Confirm settings (clarify tool, one question at a time)
- [ ] Step 4: Generate outline
- [ ] Step 5: Generate images
- [ ] Step 6: Finalize
- [ ] Step 5: Generate prompts
- [ ] Step 6: Generate images (image_generate)
- [ ] Step 7: Finalize
```
### Step 1: Pre-check
### Step 1: Detect Reference Images
**1.5 Load Preferences (EXTEND.md) ⛔ BLOCKING**
If the user supplies reference images (paths pasted inline, attachments, or a list of files):
Check EXTEND.md in priority order — the first one found wins:
1. Copy each reference to `{output-dir}/references/NN-ref-{slug}.{ext}` using `write_file`.
2. Create a sidecar `NN-ref-{slug}.md` describing the reference.
3. If the user described a reference but can't provide a file path, extract style/palette verbally and record under `references/extracted-style.md` — do NOT add a `references:` field to prompt frontmatter in that case.
| Priority | Path | Scope |
|----------|------|-------|
| 1 | `.baoyu-skills/baoyu-article-illustrator/EXTEND.md` | Project |
| 2 | `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-article-illustrator/EXTEND.md` | XDG |
| 3 | `$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md` | User home |
| Result | Action |
|--------|--------|
| Found | Read, parse, display summary |
| Not found | ⛔ Run [first-time-setup](references/config/first-time-setup.md) |
Full procedures: [references/workflow.md](references/workflow.md#step-1-pre-check)
Full procedures: [references/workflow.md](references/workflow.md#step-1-detect-reference-images).
### Step 2: Analyze
@ -105,58 +108,65 @@ Full procedures: [references/workflow.md](references/workflow.md#step-1-pre-chec
| Core arguments | 2-5 main points |
| Positions | Where illustrations add value |
**CRITICAL**: Metaphors → visualize underlying concept, NOT literal image.
Read source (file path → `read_file`, or pasted text) and write the analysis to `{output-dir}/analysis.md` using `write_file`.
Full procedures: [references/workflow.md](references/workflow.md#step-2-setup--analyze)
Full procedures: [references/workflow.md](references/workflow.md#step-2-analyze).
### Step 3: Confirm Settings ⚠️
### Step 3: Confirm Settings
**ONE AskUserQuestion, max 4 Qs. Q1-Q2 REQUIRED. Q3 required unless preset chosen.**
Use the `clarify` tool. Since `clarify` handles one question at a time, ask the most important question first. Skip any question whose answer is already present in the user's request.
| Q | Options |
|---|---------|
| **Q1: Preset or Type** | [Recommended preset], [alt preset], or manual: infographic, scene, flowchart, comparison, framework, timeline, mixed |
| **Q2: Density** | minimal (1-2), balanced (3-5), per-section (Recommended), rich (6+) |
| **Q3: Style** | [Recommended], minimal-flat, sci-fi, hand-drawn, editorial, scene, poster, Other — **skip if preset chosen** |
| Q4: Palette | Default (style colors), macaron, warm, neon — **skip if preset includes palette or preferred_palette set** |
| Q5: Language | When article language ≠ EXTEND.md setting |
| Order | Question | Options |
|-------|----------|---------|
| Q1 | **Preset or Type** | [Recommended preset], [alt preset], or manual: infographic, scene, flowchart, comparison, framework, timeline, mixed |
| Q2 | **Density** | minimal (1-2), balanced (3-5), per-section (Recommended), rich (6+) |
| Q3 | **Style** *(skip if preset chosen in Q1)* | [Recommended], minimal-flat, sci-fi, hand-drawn, editorial, scene, poster |
| Q4 | **Palette** *(optional)* | Default (style colors), macaron, warm, neon |
| Q5 | **Language** *(only if article language is ambiguous)* | article language / user language |
Full procedures: [references/workflow.md](references/workflow.md#step-3-confirm-settings-)
Don't ask more than 2-3 `clarify` questions in a row. If the user already specified these in their request, skip entirely.
### Step 4: Generate Outline
Full procedures: [references/workflow.md](references/workflow.md#step-3-confirm-settings).
Save `outline.md` with frontmatter (type, density, style, palette, image_count) and entries:
### Step 4: Generate Outline → `outline.md`
Save `{output-dir}/outline.md` using `write_file` with frontmatter (type, density, style, palette, image_count) and one entry per illustration:
```yaml
## Illustration 1
**Position**: [section/paragraph]
**Purpose**: [why]
**Visual Content**: [what]
**Visual Content**: [what to show]
**Filename**: 01-infographic-concept-name.png
```
Full template: [references/workflow.md](references/workflow.md#step-4-generate-outline)
Full template: [references/workflow.md](references/workflow.md#step-4-generate-outline).
### Step 5: Generate Images
### Step 5: Generate Prompts
⛔ **BLOCKING: Prompt files MUST be saved before ANY image generation.** This is a hard requirement regardless of which backend is chosen — the prompt file is the reproducibility record.
**BLOCKING**: Every illustration must have a saved prompt file before any image is generated — the prompt file is the reproducibility record.
1. For each illustration, create a prompt file per [references/prompt-construction.md](references/prompt-construction.md)
2. Save to `prompts/NN-{type}-{slug}.md` with YAML frontmatter
3. Prompts **MUST** use type-specific templates with structured sections (ZONES / LABELS / COLORS / STYLE / ASPECT)
4. LABELS **MUST** include article-specific data: actual numbers, terms, metrics, quotes
5. **DO NOT** pass ad-hoc inline prompts to `--prompt` without saving prompt files first
6. Select the backend via the `## Image Generation Tools` rule at the top: use whatever is available; if multiple, ask the user once. Do this once per session before any generation.
7. **Execution strategy**: When multiple illustrations have saved prompt files and the task is now plain generation, prefer the chosen backend's batch interface (if it offers one) over spawning subagents. Use subagents only when each image still needs separate prompt iteration or creative exploration. If the backend has no batch interface, generate sequentially.
8. Process references (`direct`/`style`/`palette`) per prompt frontmatter
9. Apply watermark if EXTEND.md enabled
10. Generate from saved prompt files; retry once on failure
For each illustration:
Full procedures: [references/workflow.md](references/workflow.md#step-5-generate-images)
1. Create a prompt file per [references/prompt-construction.md](references/prompt-construction.md).
2. Save to `{output-dir}/prompts/NN-{type}-{slug}.md` using `write_file` with YAML frontmatter.
3. Prompts MUST use type-specific templates with structured sections (ZONES / LABELS / COLORS / STYLE / ASPECT).
4. LABELS MUST include article-specific data: actual numbers, terms, metrics, quotes.
5. Process references (`direct`/`style`/`palette`) per prompt frontmatter — for `direct` usage, embed a textual description of the reference in the prompt (since `image_generate` doesn't take reference-image inputs).
### Step 6: Finalize
### Step 6: Generate Images
Insert `![description]({relative-path}/NN-{type}-{slug}.png)` after paragraphs. Path computed relative to article file based on output directory setting.
Use the `image_generate` tool with the assembled prompt from each prompt file.
- Map aspect ratio to `image_generate` format: `16:9` → `landscape`, `9:16` → `portrait`, `1:1` → `square`. For custom ratios, pick the closest named aspect.
- Generate sequentially through the outline. On failure, auto-retry once.
- Save each image to `{output-dir}/NN-{type}-{slug}.png`.
### Step 7: Finalize
Insert `![description]({relative-path}/NN-{type}-{slug}.png)` after the corresponding paragraph. Alt text: concise description in the article's language.
Report:
```
Article Illustration Complete!
@ -164,31 +174,6 @@ Article: [path] | Type: [type] | Density: [level] | Style: [style] | Palette: [p
Images: X/N generated
```
## Output Directory
Output directory is determined by `default_output_dir` in EXTEND.md (set during first-time setup):
| `default_output_dir` | Output Path | Markdown Insert Path |
|----------------------|-------------|----------------------|
| `imgs-subdir` (default) | `{article-dir}/imgs/` | `imgs/NN-{type}-{slug}.png` |
| `same-dir` | `{article-dir}/` | `NN-{type}-{slug}.png` |
| `illustrations-subdir` | `{article-dir}/illustrations/` | `illustrations/NN-{type}-{slug}.png` |
| `independent` | `illustrations/{topic-slug}/` | `illustrations/{topic-slug}/NN-{type}-{slug}.png` (relative to cwd) |
All auxiliary files (outline, prompts) are saved inside the output directory:
```
{output-dir}/
├── outline.md
├── prompts/
│ └── NN-{type}-{slug}.md
└── NN-{type}-{slug}.png
```
When input is **pasted content** (no file path), always uses `illustrations/{topic-slug}/` with `source-{slug}.{ext}` saved alongside.
**Slug**: 2-4 words, kebab-case. **Conflict**: append `-YYYYMMDD-HHMMSS`.
## Modification
| Action | Steps |
@ -202,8 +187,15 @@ When input is **pasted content** (no file path), always uses `illustrations/{top
| File | Content |
|------|---------|
| [references/workflow.md](references/workflow.md) | Detailed procedures |
| [references/usage.md](references/usage.md) | Command syntax |
| [references/usage.md](references/usage.md) | Invocation examples |
| [references/styles.md](references/styles.md) | Style gallery + Palette gallery |
| [references/style-presets.md](references/style-presets.md) | Preset shortcuts (type + style + palette) |
| [references/prompt-construction.md](references/prompt-construction.md) | Prompt templates |
| [references/config/first-time-setup.md](references/config/first-time-setup.md) | First-time setup |
## Pitfalls
1. **Data integrity is paramount** — never summarize, paraphrase, or alter source statistics. "73% increase" stays "73% increase".
2. **Strip secrets** — scan source content for API keys, tokens, or credentials before including in any output file.
3. **Don't illustrate metaphors literally** — visualize the underlying concept.
4. **Prompt files are mandatory** — no image generation without a saved prompt file. The file is what lets you regenerate or switch backends later.
5. **`image_generate` aspect ratios** — the tool supports `landscape`, `portrait`, and `square`. Custom ratios map to the nearest option.

138
skills/creative/baoyu-article-illustrator/references/config/first-time-setup.md
View file

@ -1,138 +0,0 @@
---
name: first-time-setup
description: First-time setup flow for baoyu-article-illustrator preferences
---
# First-Time Setup
## Overview
When no EXTEND.md is found, guide user through preference setup.
**⛔ BLOCKING OPERATION**: This setup MUST complete before ANY other workflow steps. Do NOT:
- Ask about reference images
- Ask about content/article
- Ask about type or style preferences
- Proceed to content analysis
ONLY ask the questions in this setup flow, save EXTEND.md, then continue.
## Setup Flow
```
No EXTEND.md found
│
▼
┌─────────────────────┐
│ AskUserQuestion │
│ (all questions) │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ Create EXTEND.md │
└─────────────────────┘
│
▼
Continue to Step 1
```
## Questions
**Language**: Use user's input language or preferred language for all questions. Do not always use English.
Use single AskUserQuestion with multiple questions (AskUserQuestion auto-adds "Other" option):
### Question 1: Watermark
```
header: "Watermark"
question: "Watermark text for generated illustrations? Type your watermark content (e.g., name, @handle)"
options:
- label: "No watermark (Recommended)"
description: "No watermark, can enable later in EXTEND.md"
```
Position defaults to bottom-right.
### Question 2: Preferred Style
```
header: "Style"
question: "Default illustration style preference? Or type another style name or your custom style"
options:
- label: "None (Recommended)"
description: "Auto-select based on content analysis"
- label: "notion"
description: "Minimalist hand-drawn line art"
- label: "warm"
description: "Friendly, approachable, personal"
```
### Question 3: Output Directory
```
header: "Output Directory"
question: "Where to save generated illustrations when illustrating a file?"
options:
- label: "imgs-subdir (Recommended)"
description: "{article-dir}/imgs/ — images in a subdirectory next to the article"
- label: "same-dir"
description: "{article-dir}/ — images alongside the article file"
- label: "illustrations-subdir"
description: "{article-dir}/illustrations/ — separate illustrations subdirectory"
- label: "independent"
description: "illustrations/{topic-slug}/ — standalone directory in cwd"
```
### Question 4: Save Location
```
header: "Save"
question: "Where to save preferences?"
options:
- label: "Project"
description: ".baoyu-skills/ (this project only)"
- label: "User"
description: "~/.baoyu-skills/ (all projects)"
```
## Save Locations
| Choice | Path | Scope |
|--------|------|-------|
| Project | `.baoyu-skills/baoyu-article-illustrator/EXTEND.md` | Current project |
| User | `~/.baoyu-skills/baoyu-article-illustrator/EXTEND.md` | All projects |
## After Setup
1. Create directory if needed
2. Write EXTEND.md with frontmatter
3. Confirm: "Preferences saved to [path]"
4. Continue to Step 1
## EXTEND.md Template
```yaml
---
version: 1
watermark:
enabled: [true/false]
content: "[user input or empty]"
position: bottom-right
opacity: 0.7
preferred_style:
name: [selected style or null]
description: ""
default_output_dir: imgs-subdir # same-dir | imgs-subdir | illustrations-subdir | independent
language: null
custom_styles: []
---
```
## Modifying Preferences Later
Users can edit EXTEND.md directly or run setup again:
- Delete EXTEND.md to trigger setup
- Edit YAML frontmatter for quick changes
- Full schema: `config/preferences-schema.md`

127
skills/creative/baoyu-article-illustrator/references/config/preferences-schema.md
View file

@ -1,127 +0,0 @@
---
name: preferences-schema
description: EXTEND.md YAML schema for baoyu-article-illustrator user preferences
---
# Preferences Schema
## Full Schema
```yaml
---
version: 1
watermark:
enabled: false
content: ""
position: bottom-right # bottom-right|bottom-left|bottom-center|top-right
preferred_style:
name: null # Built-in or custom style name
description: "" # Override/notes
preferred_palette: null # Built-in palette name (macaron|warm|neon) or null
language: null # zh|en|ja|ko|auto
default_output_dir: null # same-dir|illustrations-subdir|independent
custom_styles:
- name: my-style
description: "Style description"
color_palette:
primary: ["#1E3A5F", "#4A90D9"]
background: "#F5F7FA"
accents: ["#00B4D8", "#48CAE4"]
visual_elements: "Clean lines, geometric shapes"
typography: "Modern sans-serif"
best_for: "Business, education"
---
```
## Field Reference
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `version` | int | 1 | Schema version |
| `watermark.enabled` | bool | false | Enable watermark |
| `watermark.content` | string | "" | Watermark text (@username or custom) |
| `watermark.position` | enum | bottom-right | Position on image |
| `preferred_style.name` | string | null | Style name or null |
| `preferred_style.description` | string | "" | Custom notes/override |
| `preferred_palette` | string | null | Palette override (macaron, warm, neon, or null) |
| `language` | string | null | Output language (null = auto-detect) |
| `default_output_dir` | enum | null | Output directory preference (null = ask each time) |
| `custom_styles` | array | [] | User-defined styles |
## Position Options
| Value | Description |
|-------|-------------|
| `bottom-right` | Lower right corner (default, most common) |
| `bottom-left` | Lower left corner |
| `bottom-center` | Bottom center |
| `top-right` | Upper right corner |
## Output Directory Options
| Value | Description |
|-------|-------------|
| `same-dir` | Same directory as article |
| `illustrations-subdir` | `{article-dir}/illustrations/` subdirectory |
| `independent` | `illustrations/{topic-slug}/` in working directory |
## Custom Style Fields
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Unique style identifier (kebab-case) |
| `description` | Yes | What the style conveys |
| `color_palette.primary` | No | Main colors (array) |
| `color_palette.background` | No | Background color |
| `color_palette.accents` | No | Accent colors (array) |
| `visual_elements` | No | Decorative elements |
| `typography` | No | Font/lettering style |
| `best_for` | No | Recommended content types |
## Example: Minimal Preferences
```yaml
---
version: 1
watermark:
enabled: true
content: "@myusername"
preferred_style:
name: notion
---
```
## Example: Full Preferences
```yaml
---
version: 1
watermark:
enabled: true
content: "@myaccount"
position: bottom-right
preferred_style:
name: notion
description: "Clean illustrations for tech articles"
language: zh
custom_styles:
- name: corporate
description: "Professional B2B style"
color_palette:
primary: ["#1E3A5F", "#4A90D9"]
background: "#F5F7FA"
accents: ["#00B4D8", "#48CAE4"]
visual_elements: "Clean lines, subtle gradients, geometric shapes"
typography: "Modern sans-serif, professional"
best_for: "Business, SaaS, enterprise"
---
```

6
skills/creative/baoyu-article-illustrator/references/prompt-construction.md
View file

@ -30,7 +30,7 @@ references: # ⚠️ ONLY if files EXIST in references/ direc
| Usage | Description | Generation Action |
|-------|-------------|-------------------|
| `direct` | Primary visual reference | Pass to `--ref` parameter |
| `direct` | Primary visual reference | Describe the reference (composition, subject, style, palette) in prompt text — `image_generate` does not accept reference-image inputs |
| `style` | Style characteristics only | Describe style in prompt text |
| `palette` | Color palette extraction | Include colors in prompt |
@ -417,9 +417,9 @@ When no palette is specified, use the style's built-in Color Palette as before.
- Missing concrete labels/annotations
- Generic decorative elements
## Watermark Integration
## Watermark Integration (optional)
If watermark enabled in preferences, append:
If the user asks for a watermark, append:
```
Include a subtle watermark "[content]" positioned at [position].

18
skills/creative/baoyu-article-illustrator/references/style-presets.md
View file

@ -1,12 +1,12 @@
# Style Presets
`--preset X` expands to a type + style + optional palette combination. Users can override any dimension.
A preset expands to a type + style + optional palette combination. Users can override any dimension in their request.
## By Category
### Technical & Engineering
| --preset | Type | Style | Palette | Best For |
| Preset | Type | Style | Palette | Best For |
|----------|------|-------|---------|----------|
| `tech-explainer` | `infographic` | `blueprint` | — | API docs, system metrics, technical deep-dives |
| `system-design` | `framework` | `blueprint` | — | Architecture diagrams, system design |
@ -15,7 +15,7 @@
### Knowledge & Education
| --preset | Type | Style | Palette | Best For |
| Preset | Type | Style | Palette | Best For |
|----------|------|-------|---------|----------|
| `knowledge-base` | `infographic` | `vector-illustration` | — | Concept explainers, tutorials, how-to |
| `saas-guide` | `infographic` | `notion` | — | Product guides, SaaS docs, tool walkthroughs |
@ -30,7 +30,7 @@
### Data & Analysis
| --preset | Type | Style | Palette | Best For |
| Preset | Type | Style | Palette | Best For |
|----------|------|-------|---------|----------|
| `data-report` | `infographic` | `editorial` | — | Data journalism, metrics reports, dashboards |
| `versus` | `comparison` | `vector-illustration` | — | Tech comparisons, framework shootouts |
@ -38,7 +38,7 @@
### Narrative & Creative
| --preset | Type | Style | Palette | Best For |
| Preset | Type | Style | Palette | Best For |
|----------|------|-------|---------|----------|
| `storytelling` | `scene` | `warm` | — | Personal essays, reflections, growth stories |
| `lifestyle` | `scene` | `watercolor` | — | Travel, wellness, lifestyle, creative |
@ -47,7 +47,7 @@
### Editorial & Opinion
| --preset | Type | Style | Palette | Best For |
| Preset | Type | Style | Palette | Best For |
|----------|------|-------|---------|----------|
| `opinion-piece` | `scene` | `screen-print` | — | Op-eds, commentary, critical essays |
| `editorial-poster` | `comparison` | `screen-print` | — | Debate, contrasting viewpoints |
@ -74,7 +74,7 @@ Use this table during Step 3 to recommend presets based on Step 2 content analys
## Override Examples
- `--preset tech-explainer --style notion` = infographic type with notion style
- `--preset storytelling --type timeline` = timeline type with warm style
- "use the tech-explainer preset but swap the style for notion" = infographic type with notion style
- "storytelling preset with timeline type" = timeline type with warm style
Explicit `--type`/`--style` flags always override preset values.
Explicit type/style/palette mentions in the user's request always override preset values.

2
skills/creative/baoyu-article-illustrator/references/styles.md
View file

@ -201,7 +201,7 @@ Full specifications: `references/styles/<style>.md`
## Palette Gallery
Palettes override a style's default colors. Combine any style with any palette: `--style vector-illustration --palette macaron`.
Palettes override a style's default colors. Combine any style with any palette (e.g. `style=vector-illustration, palette=macaron`).
| Palette | Description | Best For |
|---------|-------------|----------|

92
skills/creative/baoyu-article-illustrator/references/usage.md
View file

@ -1,82 +1,50 @@
# Usage
## Command Syntax
This skill is triggered by natural language in Hermes — no slash command or CLI flags.
```bash
# Auto-select type and style based on content
/baoyu-article-illustrator path/to/article.md
## Trigger Phrases
# Specify type
/baoyu-article-illustrator path/to/article.md --type infographic
# Specify style
/baoyu-article-illustrator path/to/article.md --style blueprint
# Combine type and style
/baoyu-article-illustrator path/to/article.md --type flowchart --style notion
# Specify density
/baoyu-article-illustrator path/to/article.md --density rich
# Direct content input (paste mode)
/baoyu-article-illustrator
[paste content]
```
## Options
| Option | Description |
|--------|-------------|
| `--type <name>` | Illustration type (see Type Gallery in SKILL.md) |
| `--style <name>` | Visual style (see references/styles.md) |
| `--preset <name>` | Shorthand for type + style combo (see [references/style-presets.md](references/style-presets.md)) |
| `--density <level>` | Image count: minimal / balanced / rich |
- "Illustrate this article" / "为文章配图"
- "Add images to this post"
- "Generate illustrations for [path/to/article.md]"
## Input Modes
| Mode | Trigger | Output Directory |
|------|---------|------------------|
| File path | `path/to/article.md` | Use `default_output_dir` preference, or ask if not set |
| Paste content | No path argument | `illustrations/{topic-slug}/` |
| Mode | How to trigger | Output Directory |
|------|----------------|------------------|
| File path | Mention an article path (`path/to/article.md`) | `{article-dir}/imgs/` (default) |
| Pasted content | Paste the article text in the conversation | `illustrations/{topic-slug}/` (cwd) |
## Output Directory Options
## Specifying Options in Natural Language
| Value | Path |
|-------|------|
| `same-dir` | `{article-dir}/` |
| `illustrations-subdir` | `{article-dir}/illustrations/` |
| `independent` | `illustrations/{topic-slug}/` |
The user can specify any of the following directly in their request. If not specified, the skill asks via the `clarify` tool.
Configure in EXTEND.md: `default_output_dir: illustrations-subdir`
| Option | Example phrasing |
|--------|------------------|
| Type | "as an infographic", "as a flowchart", "as scenes" |
| Style | "in blueprint style", "use notion style", "用 watercolor 风格" |
| Preset | "use the tech-explainer preset", "storytelling preset" |
| Palette | "with macaron palette", "warm colors only" |
| Density | "minimal images", "one per section", "rich illustrations" |
| Language | "images in English" / "图片文字用中文" |
| Output | "save images alongside the article" / "put them in `illustrations/`" |
## Examples
**Technical article with data**:
```bash
/baoyu-article-illustrator api-design.md --type infographic --style blueprint
```
> 帮我为 api-design.md 配图，用 infographic + blueprint 风格
**Same thing with preset**:
```bash
/baoyu-article-illustrator api-design.md --preset tech-explainer
```
**Preset shortcut**:
> Illustrate api-design.md with the tech-explainer preset
**Personal story**:
```bash
/baoyu-article-illustrator journey.md --preset storytelling
```
> Illustrate journey.md using the storytelling preset
**Tutorial with steps**:
```bash
/baoyu-article-illustrator how-to-deploy.md --preset tutorial --density rich
```
**Tutorial with rich images**:
> Generate illustrations for how-to-deploy.md — tutorial preset, rich density
**Opinion article with poster style**:
```bash
/baoyu-article-illustrator opinion.md --preset opinion-piece
```
**Opinion article**:
> Illustrate opinion.md with the opinion-piece preset
**Preset with override**:
```bash
/baoyu-article-illustrator article.md --preset tech-explainer --style notion
```
**Preset with style override**:
> Use the tech-explainer preset for article.md but swap the style for notion

300
skills/creative/baoyu-article-illustrator/references/workflow.md
View file

@ -1,28 +1,26 @@
# Detailed Workflow Procedures
## Step 1: Pre-check
## Step 1: Detect Reference Images
### 1.0 Detect & Save Reference Images ⚠️ REQUIRED if images provided
Check if user provided reference images. Handle based on input type:
Check if the user provided reference images. Handle based on input type:
| Input Type | Action |
|------------|--------|
| Image file path provided | Copy to `references/` subdirectory → can use `--ref` |
| Image in conversation (no path) | **ASK user for file path** with AskUserQuestion |
| User can't provide path | Extract style/palette verbally → append to prompts (NO frontmatter references) |
| Image file path provided | Copy to `{output-dir}/references/` → reference it by description in prompts |
| Image in conversation (no path) | Ask user (via `clarify`) for a file path or a description |
| User can't provide path | Extract style/palette verbally → append to prompts (no `references:` frontmatter) |
**CRITICAL**: Only add `references` to prompt frontmatter if files are ACTUALLY SAVED to `references/` directory.
**CRITICAL**: Only add a `references:` field to prompt frontmatter if files are ACTUALLY SAVED to the `references/` subdirectory.
**If user provides file path**:
1. Copy to `references/NN-ref-{slug}.png`
2. Create description: `references/NN-ref-{slug}.md`
3. Verify files exist before proceeding
**If user provides a file path**:
1. Copy to `{output-dir}/references/NN-ref-{slug}.png` using `write_file`
2. Create description: `{output-dir}/references/NN-ref-{slug}.md`
3. Verify files exist (via `read_file`) before proceeding
**If user can't provide path** (extracted verbally):
1. Analyze image visually, extract: colors, style, composition
2. Create `references/extracted-style.md` with extracted info
3. DO NOT add `references` to prompt frontmatter
**If user can't provide a path** (extracted verbally):
1. Analyze the image visually, extract: colors, style, composition
2. Create `{output-dir}/references/extracted-style.md` with extracted info
3. Do NOT add `references:` to prompt frontmatter
4. Instead, append extracted style/colors directly to prompt text
**Description File Format** (only when file saved):
@ -34,84 +32,20 @@ filename: NN-ref-{slug}.png
[User's description or auto-generated description]
```
**Verification** (only for saved files):
```
Reference Images Saved:
- 01-ref-{slug}.png ✓ (can use --ref)
- 02-ref-{slug}.png ✓ (can use --ref)
```
**Or for extracted style**:
```
Reference Style Extracted (no file):
- Colors: #E8756D coral, #7ECFC0 mint...
- Style: minimal flat vector, clean lines...
→ Will append to prompt text (not --ref)
```
---
### 1.1 Determine Input Type
## Step 2: Analyze
| Input | Output Directory | Next |
|-------|------------------|------|
| File path | EXTEND.md `default_output_dir` (default: `imgs-subdir`). If not configured, confirm in 1.2. | → 1.2 |
| Pasted content | `illustrations/{topic-slug}/` | → 1.4 |
### 2.1 Determine Output Directory
**Backup rule for pasted content**: If `source.md` exists in target directory, rename to `source-backup-YYYYMMDD-HHMMSS.md` before saving.
| Input | Output Directory | Source-save path |
|-------|------------------|------------------|
| Article file path | `{article-dir}/imgs/` (default) | — (read article via `read_file`) |
| Pasted content | `illustrations/{topic-slug}/` (cwd) | `source-{slug}.{ext}` (save via `write_file`) |
### 1.2-1.4 Configuration (file path input only)
If the user explicitly asked for a different layout (e.g., images in the article's folder, or an `illustrations/` subdirectory), honor that.
Check preferences and existing state, then ask ALL needed questions in ONE AskUserQuestion call (max 4 questions).
**Questions to include** (skip if preference exists or not applicable):
| Question | When to Ask | Options |
|----------|-------------|---------|
| Output directory | No `default_output_dir` in EXTEND.md | `{article-dir}/imgs/` (Recommended), `{article-dir}/`, `{article-dir}/illustrations/`, `illustrations/{topic-slug}/` |
| Existing images | Target dir has `.png/.jpg/.webp` files | `supplement`, `overwrite`, `regenerate` |
| Article update | Always (file path input) | `update`, `copy` |
**Preference Values** (if configured, skip asking):
| `default_output_dir` | Path |
|----------------------|------|
| `same-dir` | `{article-dir}/` |
| `imgs-subdir` | `{article-dir}/imgs/` |
| `illustrations-subdir` | `{article-dir}/illustrations/` |
| `independent` | `illustrations/{topic-slug}/` |
### 1.5 Load Preferences (EXTEND.md) ⛔ BLOCKING
**CRITICAL**: If EXTEND.md not found, MUST complete first-time setup before ANY other questions or steps. Do NOT proceed to reference images, do NOT ask about content, do NOT ask about type/style — ONLY complete the preferences setup first.
```bash
# macOS, Linux, WSL, Git Bash
test -f .baoyu-skills/baoyu-article-illustrator/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-article-illustrator/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md" && echo "user"
```
```powershell
# PowerShell (Windows)
if (Test-Path .baoyu-skills/baoyu-article-illustrator/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/baoyu-article-illustrator/EXTEND.md") { "xdg" }
if (Test-Path "$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md") { "user" }
```
| Result | Action |
|--------|--------|
| Found | Read, parse, display summary → Continue |
| Not found | ⛔ **BLOCKING**: Run first-time setup ONLY ([config/first-time-setup.md](config/first-time-setup.md)) → Complete and save EXTEND.md → Then continue |
**Supports**: Watermark | Preferred type/style | Custom styles | Language | Output directory
---
## Step 2: Setup & Analyze
### 2.1 Analyze Content
### 2.2 Analyze Content
| Analysis | Description |
|----------|-------------|
@ -122,16 +56,18 @@ if (Test-Path "$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md") { "user
| Recommended type | Based on content signals and purpose |
| Recommended density | Based on length and complexity |
### 2.2 Extract Core Arguments
Save analysis to `{output-dir}/analysis.md` using `write_file`.
### 2.3 Extract Core Arguments
- Main thesis
- Key concepts reader needs
- Comparisons/contrasts
- Framework/model proposed
**CRITICAL**: If article uses metaphors (e.g., "电锯切西瓜"), do NOT illustrate literally. Visualize the **underlying concept**.
**CRITICAL**: If the article uses metaphors (e.g., "电锯切西瓜"), do NOT illustrate literally. Visualize the **underlying concept**.
### 2.3 Identify Positions
### 2.4 Identify Positions
**Illustrate**:
- Core arguments (REQUIRED)
@ -144,7 +80,7 @@ if (Test-Path "$HOME/.baoyu-skills/baoyu-article-illustrator/EXTEND.md") { "user
- Decorative scenes
- Generic illustrations
### 2.4 Analyze Reference Images (if provided in Step 1.0)
### 2.5 Analyze Reference Images (if saved in Step 1)
For each reference image:
@ -162,38 +98,36 @@ For each reference image:
| `style` | Extract visual style characteristics only |
| `palette` | Extract color scheme only |
Note: `image_generate` does not accept reference-image inputs. For `direct` usage, describe the reference in the prompt text (composition, subject, palette) rather than passing the file itself.
---
## Step 3: Confirm Settings ⚠️
## Step 3: Confirm Settings
**Do NOT skip.** Use ONE AskUserQuestion call with max 4 questions. **Q1, Q2, Q3 are ALL REQUIRED.**
Use the `clarify` tool. Since `clarify` handles one question at a time, ask the most important question first. Skip any question the user already answered in their request.
### Q1: Preset or Type ⚠️ REQUIRED
### Q1: Preset or Type (highest priority)
Based on Step 2 content analysis, recommend a preset first (sets both type & style). Look up [style-presets.md](style-presets.md) "Content Type → Preset Recommendations" table.
- [Recommended preset] — [brief: type + style + why] (Recommended)
- [Recommended preset] — [brief: type + style + why]
- [Alternative preset] — [brief]
- Or choose type manually: infographic / scene / flowchart / comparison / framework / timeline / mixed
**If user picks a preset → skip Q3** (type & style both resolved).
**If user picks a type → Q3 is REQUIRED.**
**If user picks a type → Q3 is required.**
### Q2: Density ⚠️ REQUIRED - DO NOT SKIP
- minimal (1-2) - Core concepts only
- balanced (3-5) - Major sections
- per-section - At least 1 per section/chapter (Recommended)
- rich (6+) - Comprehensive coverage
### Q2: Density
### Q3: Style ⚠️ REQUIRED (skip if preset chosen in Q1)
- minimal (1-2) — Core concepts only
- balanced (3-5) — Major sections
- per-section — At least 1 per section/chapter (Recommended)
- rich (6+) — Comprehensive coverage
If EXTEND.md has `preferred_style`:
- [Custom style name + brief description] (Recommended)
- [Top compatible core style 1]
- [Top compatible core style 2]
- Other (see full Style Gallery)
### Q3: Style (skip if preset chosen in Q1)
Present Core Styles first:
If no `preferred_style` (present Core Styles first):
- [Best compatible core style] (Recommended)
- [Other compatible core style 1]
- [Other compatible core style 2]
@ -210,33 +144,33 @@ If no `preferred_style` (present Core Styles first):
| `scene` | warm/watercolor | Narratives, emotional, lifestyle |
| `poster` | screen-print | Opinion, editorial, cultural, cinematic |
Style selection based on Type × Style compatibility matrix (styles.md).
**In Step 5.1**, read `styles/<style>.md` for visual elements and rendering rules.
Style selection based on Type × Style compatibility matrix ([styles.md](styles.md)).
**In Step 5**, read `styles/<style>.md` for visual elements and rendering rules.
### Q4: Palette (optional)
If preset did not specify a palette, and the user may benefit from a palette override, offer available palettes:
If the preset did not specify a palette, offer:
- Default (use style's built-in colors) (Recommended)
- `macaron` — soft pastel blocks on warm cream
- `warm` — warm earth tones, no cool colors
- `neon` — vibrant neon on dark backgrounds
**Skip if**: preset already resolved palette, or `preferred_palette` set in EXTEND.md.
**Skip if**: preset already resolved palette, or user specified a palette in the request.
See Palette Gallery in [styles.md](styles.md#palette-gallery) and full specs in `palettes/<palette>.md`.
### Q5: Image Text Language ⚠️ REQUIRED when article language ≠ EXTEND.md `language`
### Q5: Image Text Language (only when ambiguous)
Detect article language from content. If different from EXTEND.md `language` setting, MUST ask:
If the article language is different from the user's conversational language, ask which to use:
- Article language (match article content) (Recommended)
- EXTEND.md language (user's general preference)
- User's conversational language
**Skip only if**: Article language matches EXTEND.md `language`, or EXTEND.md has no `language` setting.
**Skip if**: languages match, or the user already specified in the request.
### Display Reference Usage (if references detected in Step 1.0)
### Display Reference Usage (if references saved in Step 1)
When presenting outline preview to user, show reference assignments:
When presenting the outline preview to the user, show reference assignments:
```
Reference Images:
@ -250,7 +184,7 @@ Reference Images:
## Step 4: Generate Outline
Save as `{output-dir}/outline.md` (all paths below are relative to the output directory determined in Step 1.1/1.2):
Save as `{output-dir}/outline.md` using `write_file`:
```yaml
---
@ -281,24 +215,24 @@ references: # Only if references provided
...
```
**Backup rule**: If `outline.md` exists, rename to `outline-backup-YYYYMMDD-HHMMSS.md` before writing.
**Requirements**:
- Each position justified by content needs
- Type applied consistently
- Style reflected in descriptions
- Count matches density
- References assigned based on Step 2.4 analysis
- References assigned based on Step 2.5 analysis
---
## Step 5: Generate Images
## Step 5: Generate Prompts
### 5.1 Create Prompts ⛔ BLOCKING
**Every illustration MUST have a saved prompt file before generation begins. DO NOT skip this step.**
**BLOCKING**: Every illustration must have a saved prompt file before any image is generated.
For each illustration in the outline:
1. **Create prompt file**: `{output-dir}/prompts/NN-{type}-{slug}.md`
1. **Create prompt file**: `{output-dir}/prompts/NN-{type}-{slug}.md` via `write_file`
2. **Include YAML frontmatter**:
```yaml
---
@ -307,7 +241,7 @@ For each illustration in the outline:
style: custom-flat-vector
---
```
3. **Load style specs**: Read `styles/<style>.md` for visual elements, style rules, and rendering instructions
3. **Load style specs**: Read `styles/<style>.md` (via `read_file`) for visual elements, style rules, and rendering instructions
4. **Load palette specs** (if palette specified): Read `palettes/<palette>.md` for colors and background. Palette colors **replace** the style's default Color Palette. If no palette specified, use the style's built-in colors.
5. **Follow type-specific template** from [prompt-construction.md](prompt-construction.md), using rendering from style + colors from palette (or style default)
6. **Prompt quality requirements** (all REQUIRED):
@ -317,97 +251,55 @@ For each illustration in the outline:
- `COLORS`: Specify hex codes from palette (or style default) with semantic meaning
- `STYLE`: Describe line treatment, texture, mood, character rendering per style rules
- `ASPECT`: Specify ratio (e.g., `16:9`)
7. **Apply defaults**: composition requirements, character rendering, text guidelines, watermark
8. **Backup rule**: If prompt file exists, rename to `prompts/NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.md`
**Verification** ⛔: Before proceeding to 5.2, confirm ALL prompt files exist:
```
Prompt Files:
- prompts/01-infographic-overview.md ✓
- prompts/02-infographic-distillation.md ✓
...
```
**DO NOT** pass ad-hoc inline text to `--prompt` without first saving prompt files. The generation command should either use `--promptfiles prompts/NN-{type}-{slug}.md` or read the saved file content for `--prompt`.
**Execution choice**:
- If multiple illustrations already have saved prompt files and the task is now plain generation, prefer the chosen backend's batch interface (if it offers one); otherwise generate sequentially
- Use subagents only when each illustration still needs separate prompt rewriting, style exploration, or other per-image reasoning before generation
7. **Apply defaults**: composition requirements, character rendering, text guidelines
8. **Backup rule**: If a prompt file exists, rename to `prompts/NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.md`
**CRITICAL - References in Frontmatter**:
- Only add `references` field if files ACTUALLY EXIST in `references/` directory
- Only add `references` field if files ACTUALLY EXIST in `{output-dir}/references/` directory
- If style/palette was extracted verbally (no file), append info to prompt BODY instead
- Before writing frontmatter, verify: `test -f references/NN-ref-{slug}.png`
- Before writing frontmatter, verify the reference file exists
### 5.2 Select Generation Skill
### 5.1 Process References (if references saved in Step 1)
Check available skills. If multiple, ask user.
Since `image_generate` doesn't accept reference-image inputs, convert every reference to a textual description and append it to the prompt body:
### 5.3 Process References ⚠️ REQUIRED if references saved in Step 1.0
**DO NOT SKIP if user provided reference images.** For each illustration with references:
1. **VERIFY files exist first**:
```bash
test -f references/NN-ref-{slug}.png && echo "exists" || echo "MISSING"
```
- If file MISSING but in frontmatter → ERROR, fix frontmatter or remove references field
- If file exists → proceed with processing
2. Read prompt frontmatter for reference info
3. Process based on usage type:
| Usage | Action | Example |
|-------|--------|---------|
| `direct` | Add reference path to `--ref` parameter | `--ref references/01-ref-brand.png` |
| `style` | Analyze reference, append style traits to prompt | "Style: clean lines, gradient backgrounds..." |
| `palette` | Extract colors from reference, append to prompt | "Colors: #E8756D coral, #7ECFC0 mint..." |
4. Check image generation skill capability:
| Skill Supports `--ref` | Action |
|------------------------|--------|
| Yes (e.g., baoyu-imagine with Google) | Pass reference images via `--ref` |
| No | Convert to text description, append to prompt |
**Verification**: Before generating, confirm reference processing:
```
Reference Processing:
- Illustration 1: using 01-ref-brand.png (direct) ✓
- Illustration 2: extracted palette from 02-ref-style.png ✓
```
### 5.4 Apply Watermark (if enabled)
Add: `Include a subtle watermark "[content]" at [position].`
### 5.5 Generate
1. For each illustration:
- **Backup rule**: If image file exists, rename to `NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.md`
- If references with `direct` usage: include `--ref` parameter
- Generate image
2. After each: "Generated X/N"
3. On failure: retry once, then log and continue
| Usage | Action |
|-------|--------|
| `direct` | Describe the reference (composition, subject, style, palette) in the prompt body |
| `style` | Append style traits to prompt: "Style: clean lines, gradient backgrounds..." |
| `palette` | Append extracted colors to prompt: "Colors: #E8756D coral, #7ECFC0 mint..." |
---
## Step 6: Finalize
## Step 6: Generate Images
### 6.1 Update Article
For each prompt file:
Insert after corresponding paragraph, using path relative to article file:
1. Read the prompt file (via `read_file`) and extract the assembled prompt
2. Map the prompt's `ASPECT` to `image_generate`'s format: `16:9` → `landscape`, `9:16` → `portrait`, `1:1` → `square`. Custom ratios → nearest named aspect.
3. Call `image_generate` with the prompt text
4. **Backup rule**: If an existing image file is present, rename to `NN-{type}-{slug}-backup-YYYYMMDD-HHMMSS.png` before writing
5. Save the resulting image to `{output-dir}/NN-{type}-{slug}.png`
6. On failure, retry once, then log and continue. After each generation, report "Generated X/N".
| `default_output_dir` | Insert Path |
|----------------------|-------------|
| `imgs-subdir` | `![description](imgs/NN-{type}-{slug}.png)` |
| `same-dir` | `![description](NN-{type}-{slug}.png)` |
| `illustrations-subdir` | `![description](illustrations/NN-{type}-{slug}.png)` |
| `independent` | `![description](illustrations/{topic-slug}/NN-{type}-{slug}.png)` (relative to cwd) |
---
Alt text: concise description in article's language.
## Step 7: Finalize
### 6.2 Output Summary
### 7.1 Update Article
Insert after the corresponding paragraph, using the path relative to the article file:
| Input | Insert Path |
|-------|-------------|
| Article file path (default `imgs-subdir`) | `![description](imgs/NN-{type}-{slug}.png)` |
| Article file path (images alongside) | `![description](NN-{type}-{slug}.png)` |
| Article file path (`illustrations/` subdirectory) | `![description](illustrations/NN-{type}-{slug}.png)` |
| Pasted content | `![description](illustrations/{topic-slug}/NN-{type}-{slug}.png)` (relative to cwd) |
Alt text: concise description in the article's language.
### 7.2 Output Summary
```
Article Illustration Complete!