smart-illustrator
智能配图与 PPT 信息图生成器。支持三种模式:(1) 文章配图模式 - 分析文章内容,生成插图;(2) PPT/Slides 模式 - 生成批量信息图;(3) Cover 模式 - 生成封面图。所有模式默认生成图片,`--prompt-only` 只输出 prompt。支持 Bento Grid 功能展示图风格(--style bento)。触发词:配图、插图、PPT、slides、封面图、thumbnail、cover、bento grid、功能展示图、feature showcase。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/axtonliu-smart-illustrator)HTML
<a href="/listings/axtonliu-smart-illustrator"><img src="/api/listings/axtonliu-smart-illustrator/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prerequisites
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed - [Bun](https://bun.sh/) runtime (for scripts) - [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli) (for Mermaid diagrams): `npm install -g @mermaid-js/mermaid-cli` - Excalidraw export dependencies (optional, for Excalidraw diagrams): `cd ~/.claude/skills/smart-illustrator/scripts && npm install && npx playwright install firefox` - Gemini API Key (optional, for creative visuals): https://aistudio.google.com/apikey
Option A: Manual Installation (Recommended)
# Clone to Claude Code Skills directory git clone https://github.com/axtonliu/smart-illustrator.git ~/.claude/skills/smart-illustrator
Option B: Copy Individual Files
# If you only want the skill without scripts cp -r smart-illustrator/SKILL.md ~/.claude/skills/smart-illustrator/ cp -r smart-illustrator/styles ~/.claude/skills/smart-illustrator/
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 311 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: smart-illustrator
- description: 智能配图与 PPT 信息图生成器。支持三种模式:(1) 文章配图模式 - 分析文章内容,生成插图;(2) PPT/Slides 模式 - 生成批量信息图;(3) Cover 模式 - 生成封面图。所有模式默认生成图片,`--prompt-only` 只输出 prompt。支持 Bento Grid 功能展示图风格(--style bento)。触发词:配图、插图、PPT、slides、封面图、thumbnail、cover、bento grid、功能展示图、feature showcase。
- ---
- # Smart Illustrator - 智能配图与 PPT 生成器
- ## ⛔ 强制规则(违反即失败)
- ### 规则 1:用户提供的文件 = 要处理的文章
- ```
- /smart-illustrator SKILL_05.md → SKILL_05.md 是文章,为它配图
- /smart-illustrator README.md → README.md 是文章,为它配图
- /smart-illustrator whatever.md → whatever.md 是文章,为它配图
- ```
- **无论文件名叫什么,都是要配图的文章,不是 Skill 配置。**
- ### 规则 2:必须读取 style 文件
- 生成任何图片 prompt 前,**必须读取**对应的 style 文件:
- | 模式 | 必须读取的文件 |
- |------|---------------|
- | 文章配图(默认) | `styles/style-light.md` |
- | Cover 封面图 | `styles/style-cover.md` |
- | `--style dark` | `styles/style-dark.md` |
- | `--style bento` | `styles/style-bento.md` |
- **禁止自己编写 System Prompt。**
- ❌ 错误:`"你是一个专业的信息图设计师..."`(自己编的)
- ✅ 正确:从 style 文件的代码块中提取 System Prompt
- ---
- ## 使用方式
- ### 文章配图模式(默认)
- ```bash
- /smart-illustrator path/to/article.md
- /smart-illustrator path/to/article.md --prompt-only # 只输出 prompt
- /smart-illustrator path/to/article.md --style dark # 深色风格
- /smart-illustrator path/to/article.md --no-cover # 不生成封面图
- ```
- ### PPT/Slides 模式
- ```bash
- # 默认:直接生成图片
- /smart-illustrator path/to/script.md --mode slides
- # 只输出 JSON prompt(不调用 API)
- /smart-illustrator path/to/script.md --mode slides --prompt-only
- ```
- **默认行为**:调用 Gemini API 生成批量信息图。
- **`--prompt-only`**:输出 JSON prompt 并**自动复制到剪贴板**,可直接粘贴到 Gemini Web 手动生成。
- **PPT JSON 格式**(`--prompt-only` 时输出):
- ```json
- {
- "instruction": "请逐条生成以下 N 张独立信息图。",
- "batch_rules": { "total": "N", "one_item_one_image": true, "aspect_ratio": "16:9" },
- "style": "[从 styles/style-light.md 读取完整内容]",
- "pictures": [
- { "id": 1, "topic": "封面", "content": "系列名称\n\n第N节:标题" },
- { "id": 2, "topic": "主题", "content": "原始内容" }
- ]
- }
- ```
- ### Cover 模式
- ```bash
- /smart-illustrator path/to/article.md --mode cover --platform youtube
- /smart-illustrator --mode cover --platform youtube --topic "Claude 4 深度评测"
- ```
- **平台尺寸**(输出均为 2K 分辨率):
- | 平台 | 代码 | 宽高比 |
- |------|------|--------|
- | YouTube | `youtube` | 16:9 |
- | 公众号 | `wechat` | 2.35:1 |
- | Twitter | `twitter` | 1.91:1 |
- | 小红书 | `xiaohongshu` | 3:4 |
- ---
- ## 参数说明
- | 参数 | 默认值 | 说明 |
- |------|--------|------|
- | `--mode` | `article` | `article` / `slides` / `cover` |
- | `--platform` | `youtube` | 封面图平台(仅 cover 模式) |
- | `--topic` | - | 封面图主题(仅 cover 模式) |
- | `--prompt-only` | `false` | 输出 prompt 到剪贴板,不调用 API(适用于所有模式) |
- | `--style` | `light` | 风格:`light` / `dark` / `minimal` / `bento` |
- | `--no-cover` | `false` | 不生成封面图 |
- | `--ref` | - | 参考图路径(可多次使用) |
- | `-c, --candidates` | `1` | 候选图数量(最多 4) |
- | `-a, --aspect-ratio` | - | 宽高比:`16:9`(正文配图/封面图默认)、`3:2`(备选横版)、`3:4`(仅竖屏平台) |
- | `--engine` | `auto` | 引擎选择:`auto`(自动)/ `mermaid` / `gemini` / `excalidraw` |
- | `--mermaid-embed` | `false` | Mermaid 输出为代码块而非 PNG(旧行为) |
- | `--save-config` | - | 保存到项目配置 |
- | `--no-config` | `false` | 禁用 config.json |
- > **`--no-config` 范围**:只禁用 `config.json`,**不影响** `styles/style-*.md`。
- ---
- ## 配置文件
- **优先级**:CLI 参数 > 项目级 > 用户级
- | 位置 | 路径 |
- |------|------|
- | 项目级 | `.smart-illustrator/config.json` |
- | 用户级 | `~/.smart-illustrator/config.json` |
- ```json
- { "references": ["./refs/style-ref-01.png"] }
- ```
- ---
- ## 三级配图引擎
- | 优先级 | 引擎 | 适用场景 | 输出 |
- |--------|------|---------|------|
- | **1** | Gemini | 隐喻图、创意图、封面图、无法用图表表达的概念 | PNG |
- | **2** | Excalidraw | 概念图、对比图、简单流程(≤ 8 节点)、关系图、手绘风格示意图 | PNG |
- | **3** | Mermaid | **仅限**:复杂流程(> 8 节点)、多层架构图、多角色时序图、多分支决策树 | PNG |
- 选择逻辑:
- - 需要隐喻、情感、创意表达 → Gemini
- - 概念关系、对比、简单流程 → Excalidraw(**大多数图表场景的首选**)
- - **只有**节点 > 8、多层/多角色的复杂结构化图形 → Mermaid
- - Mermaid 视觉表现力有限,能用 Excalidraw 就不用 Mermaid
- - 唯一目标:提高文章吸引力
- 生成 Excalidraw 前必须读取 `references/excalidraw-guide.md`。
- ### Mermaid 语义色板
- 每种颜色有固定含义,**必须使用 `classDef` + `class` 应用**:
- | 语义 | 填充色 | 边框色 | 用于 |
- |------|--------|--------|------|
- | input | #d3f9d8 | #2f9e44 | 输入、起点、数据源 |
- | process | #e5dbff | #5f3dc4 | 处理、推理、核心逻辑 |
- | decision | #ffe3e3 | #c92a2a | 决策点、分支判断 |
- | action | #ffe8cc | #d9480f | 执行动作、工具调用 |
- | output | #c5f6fa | #0c8599 | 输出、结果、终点 |
- | storage | #fff4e6 | #e67700 | 存储、记忆、数据库 |
- | meta | #e7f5ff | #1971c2 | 标题、分组、元信息 |
- **classDef 写法**(放在图表末尾):
- ```
- classDef input fill:#d3f9d8,stroke:#2f9e44,color:#1a1a1a
- classDef process fill:#e5dbff,stroke:#5f3dc4,color:#1a1a1a
- classDef decision fill:#ffe3e3,stroke:#c92a2a,color:#1a1a1a
- classDef action fill:#ffe8cc,stroke:#d9480f,color:#1a1a1a
- classDef output fill:#c5f6fa,stroke:#0c8599,color:#1a1a1a
- class A input
- class B,C process
- class D output
- ```
- ### Mermaid 布局规则
- - **布局方向**:默认 `TB`(上到下),横向流程用 `LR`
- - **箭头分级**:`-->` 主流程 / `-.->` 可选/辅助路径 / `==>` 重点强调
- - **分组**:用 `subgraph` 对相关节点分组,标题简洁
- - **节点文字**:≤ 8 字,无 emoji,禁止 `1.` 格式(用 `①` 或 `Step 1:`)
- - **节点数量**:单图 ≤ 15 个节点,复杂内容拆成多图
- **`--engine` 参数**:
- - `auto`(默认):根据内容类型自动选择(优先级 Gemini > Excalidraw > Mermaid)
- - `gemini`:强制只使用 Gemini(适合创意内容)
- - `excalidraw`:强制只使用 Excalidraw(适合手绘概念图)
- - `mermaid`:强制只使用 Mermaid(适合技术文档)
- ---
- ## 执行流程
- ### Step 1: 分析文章
- 1. 读取文章内容
- 2. 识别配图位置(通常 3-5 个)
- 3. 为每个位置确定引擎(Gemini / Excalidraw / Mermaid)
- ### Step 2: 生成图片
- #### Mermaid(结构化图形)→ PNG
- 1. 生成 Mermaid 代码,保存为临时 `.mmd` 文件
- 2. 调用 mermaid-export.ts 导出高分辨率 PNG:
- ```bash
- npx -y bun ~/.claude/skills/smart-illustrator/scripts/mermaid-export.ts \
- -i {图表名}.mmd -o {图表名}.png -w 2400
- ```
- 3. 在文章中插入 PNG 图片引用
- 4. 保留 .mmd 源文件用于后续编辑
- 使用 `--mermaid-embed` 参数时,改为直接嵌入 Mermaid 代码块(旧行为)。
- #### Excalidraw(手绘/概念图)→ PNG
- 1. 读取 `references/excalidraw-guide.md` 获取 JSON 规范
- 2. 生成 Excalidraw JSON,保存为 `.excalidraw` 文件
- 3. 调用 excalidraw-export.ts 导出 PNG:
- ```bash
- npx -y bun ~/.claude/skills/smart-illustrator/scripts/excalidraw-export.ts \
- -i {图表名}.excalidraw -o {图表名}.png -s 2
- ```
- 4. 在文章中插入 PNG 图片引用
- 5. 保留 .excalidraw 源文件用于后续编辑
- 依赖未安装时的降级:提示手动打开 excalidraw.com 导出。
- #### Gemini(创意/视觉图形)
- **命令模板**(必须使用 HEREDOC + prompt-file):
- ```bash
- # Step 1: 写入 prompt
- cat > /tmp/image-prompt.txt <<'EOF'
- {从 style 文件提取的 System Prompt}
- **内容**:{配图内容}
- EOF
- # Step 2: 调用脚本
- GEMINI_API_KEY=$GEMINI_API_KEY npx -y bun ~/.claude/skills/smart-illustrator/scripts/generate-image.ts \
- --prompt-file /tmp/image-prompt.txt \
- --output {输出路径}.png \
- --aspect-ratio 16:9
- ```
- **封面图**(16:9):
- ```bash
- cat > /tmp/cover-prompt.txt <<'EOF'
- {从 style-cover.md 提取的 System Prompt}
- **内容**:
- - 核心概念:{主题}
- - 视觉隐喻:{设计}
- EOF
- GEMINI_API_KEY=$GEMINI_API_KEY npx -y bun ~/.claude/skills/smart-illustrator/scripts/generate-image.ts \
- --prompt-file /tmp/cover-prompt.txt \
- --output {文章名}-cover.png \
- --aspect-ratio 16:9
- ```
- **参数传递**:用户指定的 `--no-config`、`--ref`、`-c` 必须传递给脚本。
- ### Step 3: 创建带配图的文章
- 保存为 `{文章名}-image.md`,包含:
- - YAML frontmatter 声明封面图
- - 正文配图插入
- ### Step 4: 输出确认
- 报告:生成了几张图片、输出文件列表。
- ---
- ## `--prompt-only` 模式
- 当使用 `--prompt-only` 时,**不调用 API**,而是:
- 1. 生成 JSON prompt
- 2. **自动复制到剪贴板**(使用 `pbcopy`)
- 3. 同时保存到文件备份
- ```bash
- # 执行方式
- echo '{生成的 JSON}' | pbcopy
- echo "✓ JSON prompt 已复制到剪贴板"
- # 同时保存备份
- echo '{生成的 JSON}' > /tmp/smart-illustrator-prompt.json
- echo "✓ 备份已保存到 /tmp/smart-illustrator-prompt.json"
- ```
- 用户可直接粘贴到 Gemini Web 手动生成图片。
- ---
- ## 输出文件
- ```
- article.md # 原文(不修改)
- article-image.md # 带配图的文章
- article-cover.png # 封面图(16:9)
- article-image-01.png # Gemini 配图
- ```
README.md · README · 712 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Smart Illustrator
- [](https://opensource.org/licenses/MIT)
- [](#status)
- **[中文文档](README.zh-CN.md)**
- > **🆕 v1.4.0 — Tri-Engine System (Feb 2026)**
- >
- > New Excalidraw engine for hand-drawn concept diagrams. Three-tier priority: Gemini → Excalidraw → Mermaid. All diagram engines now output PNG by default. [Details →](#tri-engine-system)
- 
- Intelligent article illustration Skill for Claude Code with **tri-engine system**: automatically selects Gemini (for creative visuals), Excalidraw (for hand-drawn diagrams), or Mermaid (for structured diagrams) based on content type.
- ## Status
- > **Status: Experimental**
- >
- > - This is a public prototype that works for my demos, but does not yet cover all input scales and edge cases.
- > - Output quality varies based on model version and input structure; results may fluctuate.
- > - My primary focus is demonstrating how tools and systems work together, not maintaining this codebase.
- > - If you encounter issues, please submit a reproducible case (input + output file + steps to reproduce).
- ## Why Smart Illustrator?
- Creating illustrations for articles is time-consuming: manual design takes hours, stock photos lack context, and generic AI tools don't understand article structure. Smart Illustrator combines intelligent position detection, tri-engine system (Gemini + Excalidraw + Mermaid), and cover learning to generate contextual illustrations in minutes.
- **Who it's for:** Newsletter writers, YouTube creators, technical bloggers, course instructors.
- **When to use:** When you need high-quality illustrations for articles, YouTube thumbnails with best practices, or consistent visual style across content series.
- ## Background: the Make workflow version (auto-illustrate + WeChat publish)
- Before packaging this into a Skill, I had already built an end-to-end Make workflow:
- **search → write → auto-illustrate → format/publish (WeChat Official Account)**.
- Full walkthrough (workflow logic & design trade-offs):
- https://youtu.be/TbyJ3imLuXQ
- ## Features
- - **Tri-Engine System**: Auto-selects Gemini, Excalidraw, or Mermaid based on content type
- - **Smart Position Detection**: Analyzes article structure to identify optimal illustration points
- - **10+ Illustration Types**: flowchart, sequence, mindmap, concept, comparison, scene, metaphor...
- - **Extensible Style System**: Light, Dark, Minimal, Cover, and custom styles
- - **Cover Mode**: Generate high-CTR YouTube thumbnails with best practices built-in
- - **Multi-Platform Sizes**: YouTube, WeChat, Twitter, Xiaohongshu presets
- - **Resume Generation**: Skip already-generated images, regenerate specific ones
- - **Brand Customizable**: Modify `styles/` to apply your brand style
- - **Multiple Backends**: Gemini API for creative visuals (2K resolution), Excalidraw for hand-drawn diagrams, Mermaid CLI for structured diagrams — all output PNG by default
- ## What Are Skills?
- Skills are prompt-based extensions for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that give Claude specialized capabilities. Unlike MCP servers that require complex setup, skills are simple markdown files that Claude loads on demand.
- ## Installation
- ### Prerequisites
- - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed
- - [Bun](https://bun.sh/) runtime (for scripts)
- - [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli) (for Mermaid diagrams): `npm install -g @mermaid-js/mermaid-cli`
- - Excalidraw export dependencies (optional, for Excalidraw diagrams): `cd ~/.claude/skills/smart-illustrator/scripts && npm install && npx playwright install firefox`
- - Gemini API Key (optional, for creative visuals): https://aistudio.google.com/apikey
- ### Option A: Manual Installation (Recommended)
- ```bash
- # Clone to Claude Code Skills directory
- git clone https://github.com/axtonliu/smart-illustrator.git ~/.claude/skills/smart-illustrator
- ```
- ### Option B: Copy Individual Files
- ```bash
- # If you only want the skill without scripts
- cp -r smart-illustrator/SKILL.md ~/.claude/skills/smart-illustrator/
- cp -r smart-illustrator/styles ~/.claude/skills/smart-illustrator/
- ```
- ## Usage
- ### Basic Usage
- ```bash
- # Analyze article and auto-generate illustrations (default)
- /smart-illustrator path/to/article.md
- # Output prompts only, don't auto-generate images
- /smart-illustrator path/to/article.md --prompt-only
- # Specify style (loads from styles/ directory)
- /smart-illustrator path/to/article.md --style light # Light style (default)
- /smart-illustrator path/to/article.md --style dark # Dark tech style
- /smart-illustrator path/to/article.md --style minimal # Minimal style
- # List available styles
- /smart-illustrator --list-styles
- # Without cover image
- /smart-illustrator path/to/article.md --no-cover
- # Specify number of illustrations
- /smart-illustrator path/to/article.md --count 5
- ```
- ### Parameters
- | Parameter | Default | Description |
- |-----------|---------|-------------|
- | `--mode` | `article` | Mode: `article`, `slides`, or `cover` |
- | `--engine` | `auto` | Engine: `auto`, `gemini`, `excalidraw`, or `mermaid` |
- | `--mermaid-embed` | `false` | Embed Mermaid code blocks instead of exporting PNG |
- | `--platform` | `youtube` | Cover platform: `youtube`/`wechat`/`twitter`/`xiaohongshu`/`landscape`/`square` |
- | `--topic` | - | Cover topic (alternative to article path, cover mode only) |
- | `--description` | - | Cover visual direction (cover mode only) |
- | `--prompt-only` | `false` | Output prompts only, don't call API to generate images |
- | `--style` | `light` | Style name, loads `styles/style-{name}.md` |
- | `--list-styles` | - | List all available styles in `styles/` directory |
- | `--no-cover` | `false` | Skip cover image generation (article mode) |
- | `--count` | auto | Number of illustrations (auto-determined by article length) |
- ### Illustration Count Guidelines
- | Article Length | Suggested Count |
- |----------------|-----------------|
- | Short (< 1000 words) | 1-2 images |
- | Medium (1000-3000 words) | 2-4 images |
- | Long (> 3000 words) | 4-6 images |
- | Tutorials/Guides | 1 per major step |
- ### Output Files
- ```
- article.md # Original
- article-image.md # Article with illustrations (main output)
- article-cover.png # Cover image (16:9)
- article-image-01.png # Content illustration (3:4)
- article-image-02.png
- article-image-03.png
- ```
- ### Manual Script Usage
- #### generate-image.ts (Single Image)
- ```bash
- export GEMINI_API_KEY=your_key
- # From prompt text
- npx -y bun ~/.claude/skills/smart-illustrator/scripts/generate-image.ts \
- --prompt "A concept diagram showing..." \
- --output image.png
- # From prompt file
- npx -y bun ~/.claude/skills/smart-illustrator/scripts/generate-image.ts \
- --prompt-file prompt.md \
- --output image.png
- ```
- | Option | Description |
- |--------|-------------|
- | `-p, --prompt` | Image description text |
- | `-f, --prompt-file` | Read prompt from file |
- | `-o, --output` | Output path (default: generated.png) |
- | `-m, --model` | Model (default: gemini-3-pro-image-preview) |
- #### batch-generate.ts (Batch Generation)
- ```bash
- export GEMINI_API_KEY=your_key
- npx -y bun ~/.claude/skills/smart-illustrator/scripts/batch-generate.ts \
- --config slides.json \
- --output-dir ./images \
- --prefix SKILL_01
- ```
- | Option | Description |
- |--------|-------------|
- | `-c, --config` | JSON config file (required) |
- | `-o, --output-dir` | Output directory (default: ./illustrations) |
- | `-m, --model` | Model (default: gemini-3-pro-image-preview) |
- | `-d, --delay` | Delay between requests in ms (default: 2000) |
- | `-p, --prefix` | Filename prefix (default: from config filename) |
- | `-r, --regenerate` | Regenerate specific images (e.g., "3" or "3,5,7") |
- | `-f, --force` | Force regenerate all images (ignore existing) |
- **Resume Generation**: By default, the script skips images that already exist in the output directory. This allows resuming interrupted generation without re-generating completed images.
- Output: `{prefix}-01.png`, `{prefix}-02.png`, etc.
- #### mermaid-export.ts (Mermaid to PNG)
- ```bash
- # From .mmd file
- npx -y bun ~/.claude/skills/smart-illustrator/scripts/mermaid-export.ts \
- --input diagram.mmd \
- --output diagram.png
- # From inline content
- npx -y bun ~/.claude/skills/smart-illustrator/scripts/mermaid-export.ts \
- --content "flowchart LR
- A[Start] --> B[End]" \
- --output simple.png \
- --theme dark
- ```
- | Option | Description |
- |--------|-------------|
- | `-i, --input` | Input .mmd file path |
- | `-c, --content` | Mermaid diagram content (alternative) |
- | `-o, --output` | Output path (default: output.png) |
- | `-t, --theme` | Theme: `light` (default) or `dark` |
- | `-w, --width` | Image width in pixels |
- | `-H, --height` | Image height in pixels |
- ## PPT/Slides Generation Mode
- Beyond article illustrations, this skill can generate batch infographics for PPT/Keynote slides.
- ### When to Use
- | Mode | Use Case | Output |
- |------|----------|--------|
- | **Article Mode** | Blog posts, newsletters | 3-5 illustrations inserted in article |
- | **Slides Mode** | Video B-roll, presentations | 8-15 standalone infographics |
- ### JSON Format for Batch Generation
- Use `pictures[]` array format with explicit batch rules:
- ```json
- {
- "instruction": "请为我绘制 7 张图片(generate 7 images)。你是一位「信息图绘制者」。请逐条执行 pictures 数组:每个 id 对应 1 张独立的 16:9 信息图,严禁合并,严禁只输出文字描述。",
- "batch_rules": {
- "total": 7,
- "one_item_one_image": true,
- "aspect_ratio": "16:9",
- "do_not_merge": true
- },
- "fallback": "如果无法一次生成全部图片:请输出 7 条独立的单图绘图指令...",
- "style": "[Complete style prompt - see styles/style-light.md]",
- "pictures": [
- { "id": 1, "topic": "封面", "content": "Course Name\n\nSection Title\n\nLearning objectives..." },
- { "id": 2, "topic": "核心概念", "content": "[Raw content]" }
- ]
- }
- ```
- ### Critical Rules
- 1. **Use `pictures[]` array** - Array structure helps Gemini enter "loop execution" mode for batch generation.
- 2. **Add image trigger phrase** - Must include "请为我绘制 N 张图片(generate N images)" to trigger image generation mode.
- 3. **Role as "绘制者" not "导演"** - Use "信息图绘制者" (illustrator) not "视觉导演" (director) to trigger actual drawing behavior.
- 4. **Separate instruction from style** - `instruction` = what to do + role; `style` = visual rules only.
- 5. **Pass complete style** - Include the full style prompt from `styles/style-light.md`, don't summarize.
- 6. **Content granularity** - Judge by information density, not mechanically by H2 headers.
- ### Cover Slide Branding (PPT Mode)
- For course/series content, the cover slide (`id: 1`) should include:
- ```json
- {
- "id": 1,
- "topic": "封面",
- "content": "Agent Skills 完全指南\n\n第4节:渐进式披露与 Description 优化\n\n学习目标:理解 Progressive Disclosure 机制"
- }
- ```
- Structure:
- - **Series name**: e.g., "Agent Skills 完全指南"
- - **Section number**: e.g., "第4节"
- - **Section title**: e.g., "渐进式披露与 Description 优化"
- - **Learning objectives** (optional)
- ### Output Options (Applies to All Modes)
- `--prompt-only` is a **global option** that works with Article, Slides, Cover, and all other modes:
- | Output Mode | Parameter | Description | API Required |
- |-------------|-----------|-------------|--------------|
- | Generate Images | Default | Calls Gemini API to generate images | ✅ Yes |
- | Output JSON Prompt | `--prompt-only` | Copy to Gemini Web for manual generation | ❌ No |
- **Example Combinations:**
- ```bash
- # Slides mode + generate images (needs API)
- /smart-illustrator script.md --mode slides
- # Slides mode + output JSON only (no API)
- /smart-illustrator script.md --mode slides --prompt-only
- # Article mode + generate images (needs API)
- /smart-illustrator article.md
- # Article mode + output JSON only (no API)
- /smart-illustrator article.md --prompt-only
- ```
- **Manual Batch Generation (after JSON prompt output):**
- ```bash
- export GEMINI_API_KEY=your_key
- npx -y bun ~/.claude/skills/smart-illustrator/scripts/batch-generate.ts \
- --config slides.json \
- --output-dir ./images
- ```
- See `references/slides-prompt-example.json` for a complete example.
- > **💡 Tip**: Batch image generation with JSON in Gemini doesn't have 100% success rate. If generation fails:
- > 1. Retry 1-3 times (usually succeeds)
- > 2. If retries fail, copy individual items from `pictures` array and generate one by one
- ---
- ## Configuration Files (Style Reuse)
- Save common parameters to configuration files for consistent style across series content (courses, newsletters).
- ### Configuration File Locations
- **Priority: CLI Arguments > Project Config > User Config**
- | Location | Path | Purpose |
- |----------|------|---------|
- | Project | `{working-dir}/.smart-illustrator/config.json` | Project-specific style (e.g., course series) |
- | User | `~/.smart-illustrator/config.json` | User's global default style |
- ### Configuration File Format
- ```json
- {
- "references": [
- "./refs/style-ref-01.png",
- "./refs/style-ref-02.png"
- ]
- }
- ```
- **Supported options**:
- - `references`: Array of reference image paths (relative paths are resolved relative to config file directory)
- ### Usage Examples
- ```bash
- # Initial setup: configure style for course series
- cd ~/my-course
- /smart-illustrator article-01.md --ref ./refs/style-1.png --save-config
- # Subsequent generation: auto-apply config
- /smart-illustrator article-02.md # Automatically uses reference images
- # Temporary override: use different reference
- /smart-illustrator article-03.md --ref ./other-ref.png
- # Completely ignore config
- /smart-illustrator article-04.md --no-config
- # Save to user-level config (global default)
- /smart-illustrator article.md --ref ./my-style.png --save-config-global
- ```
- ### Configuration Loading Rules
- 1. Read user-level config (if exists)
- 2. Read project-level config (if exists, overrides user-level)
- 3. Apply command-line arguments (overrides config files)
- **Typical scenarios**:
- - **Course series**: Save `.smart-illustrator/config.json` in project directory for unified style across chapters
- - **Personal default**: Save `~/.smart-illustrator/config.json` in user directory as global default
- - **Temporary adjustment**: Use `--ref` parameter to temporarily override config without modifying saved settings
- ---
- ## Cover Mode (YouTube Thumbnails)
- Generate high-CTR cover images for YouTube, WeChat, Twitter, and more. Built on YouTuber best practices research.
- ```bash
- # Generate YouTube thumbnail from article
- /smart-illustrator path/to/article.md --mode cover --platform youtube
- # Generate with specific topic
- /smart-illustrator --mode cover --platform youtube --topic "Claude 4 Deep Review"
- # Generate with visual direction
- /smart-illustrator --mode cover --platform wechat --description "Comparison diagram + tech aesthetic"
- ```
- ### Supported Platforms
- All outputs are **2K resolution** (e.g., ~2816×1584 for 16:9).
- | Platform | Code | Aspect Ratio |
- |----------|------|--------------|
- | YouTube | `youtube` | 16:9 |
- | WeChat | `wechat` | 2.35:1 |
- | Twitter/X | `twitter` | 1.91:1 |
- | Xiaohongshu | `xiaohongshu` | 3:4 |
- | Landscape | `landscape` | 16:9 |
- | Square | `square` | 1:1 |
- ### Design Principles (from `references/cover-best-practices.md`)
- 1. **3-Second Rule**: Instantly convey topic and value
- 2. **High Contrast**: Dark background + bright subject
- 3. **Single Focus**: Only one visual center
- 4. **Minimal Text**: 3-6 words, bold sans-serif
- 5. **Curiosity Gap**: Make viewers want to click
- ### Visual Metaphors for Tech Content
- | Concept | Metaphor |
- |---------|----------|
- | AI Assistant | Two collaborative hands, chat bubbles |
- | Efficiency | Upward arrows, stairs, rocket trail |
- | Automation | Gears, assembly line nodes |
- | Learning/Growth | Seed → tree, ascending stairs |
- | Problem → Solution | Maze exit, completed puzzle |
- ---
- ## Smart Position Detection
- The skill analyzes article structure to identify optimal illustration points:
- | Signal | Illustration Value |
- |--------|-------------------|
- | Abstract concept first appears | High - helps build mental model |
- | Process/step description | High - visual is clearer than text |
- | Comparison/choice discussion | High - side-by-side is clear |
- | Data/statistics reference | Medium - numbers visualized have impact |
- | Section transition point | Medium - provides visual breathing room |
- | Emotional/story climax | Medium - enhances resonance |
- ---
- ## Tri-Engine System
- The skill automatically selects the best rendering engine based on content, with three-tier priority:
- | Priority | Engine | Best For | Output |
- |----------|--------|----------|--------|
- | **1** | **Gemini** | Creative visuals (metaphors, scenes, infographics) | PNG (2K) |
- | **2** | **Excalidraw** | Hand-drawn concept diagrams, comparisons, simple flows | PNG |
- | **3** | **Mermaid** | Complex structured diagrams (flowcharts, sequences, architectures) | PNG |
- **Selection logic:**
- - Needs metaphor, emotion, or creative expression → Gemini
- - Needs hand-drawn / informal style, or simple concept relationships → Excalidraw
- - Complex structured flows / architectures → Mermaid
- ## Illustration Types
- | Type | Engine | Best For | Syntax/Style |
- |------|--------|----------|--------------|
- | `process` | Mermaid | Complex workflows | `flowchart` |
- | `architecture` | Mermaid | System components | `block-beta` |
- | `sequence` | Mermaid | API calls, interactions | `sequenceDiagram` |
- | `mindmap` | Mermaid | Knowledge structure | `mindmap` |
- | `state` | Mermaid | State transitions | `stateDiagram` |
- | `concept` | Excalidraw / Gemini | Abstract concepts | Hand-drawn / Center-radial |
- | `comparison` | Excalidraw / Gemini | A vs B, contrasts | Hand-drawn / Left-right split |
- | `data` | Gemini | Statistics, trends | Infographic style |
- | `scene` | Gemini | Stories, scenarios | Narrative illustration |
- | `metaphor` | Gemini | Analogies, symbols | Creative visual |
- | `cover` | Gemini | Article cover | 16:9 dark tech |
- ### Type × Composition Reference
- | Type | Recommended Composition | Elements |
- |------|------------------------|----------|
- | concept | Center-radial, hierarchy | Core icon + surrounding factors |
- | process | Horizontal/vertical flow | Nodes + arrows + labels |
- | comparison | Left-right / top-bottom split | Two columns + corresponding items |
- | data | Chart-style | Numbers prominent + graphical |
- | scene | Narrative illustration | Characters + environment + action |
- | summary | Card grid, bullet points | Structured layout |
- | metaphor | Analogy visual | Creative visual metaphor |
- ## Style System
- ### Built-in Styles
- | Style | File | Best For |
- |-------|------|----------|
- | Light | `styles/style-light.md` | Content illustrations (default) |
- | Dark | `styles/style-dark.md` | Cover images, marketing |
- | Minimal | `styles/style-minimal.md` | Technical docs, whitepapers |
- | Cover | `styles/style-cover.md` | YouTube thumbnails, social covers (cover mode) |
- ### Content Illustrations: Light Style
- - 3:4 portrait format
- - Light gray background `#F8F9FA`
- - Flat geometric + thin lines
- - See `styles/style-light.md`
- ### Cover Images: Dark Tech Style
- - 16:9 landscape format
- - Deep blue gradient background
- - Line icons + glassmorphism
- - No text
- - See `styles/style-dark.md`
- ### Custom Styles
- Add your own style by creating `styles/style-{name}.md` and use it with `--style {name}`.
- ## File Structure
- ```
- smart-illustrator/
- ├── SKILL.md # Skill definition (Claude Code entry)
- ├── CLAUDE.md # Project rules (style sync, JSON format)
- ├── README.md
- ├── README.zh-CN.md # Chinese documentation
- ├── LICENSE
- ├── scripts/
- │ ├── generate-image.ts # Gemini single image generation
- │ ├── batch-generate.ts # Gemini batch generation (2K, resume support)
- │ ├── mermaid-export.ts # Mermaid diagram to PNG export
- │ ├── excalidraw-export.ts # Excalidraw diagram to PNG export
- │ └── package.json # Script dependencies (Excalidraw export)
- ├── styles/
- │ ├── brand-colors.md # Brand palette (customizable)
- │ ├── style-light.md # Light style Gemini prompt (default)
- │ ├── style-dark.md # Dark style Gemini prompt
- │ ├── style-minimal.md # Minimal style Gemini prompt
- │ └── style-cover.md # Cover/thumbnail style (cover mode)
- └── references/
- ├── slides-prompt-example.json # PPT mode JSON format example
- ├── cover-best-practices.md # YouTube thumbnail best practices
- └── excalidraw-guide.md # Excalidraw JSON specification
- ```
- ## Customization
- Want to use your own brand style?
- ### Option 1: Modify Existing Styles
- 1. Edit `styles/brand-colors.md` with your colors
- 2. Sync color values in `styles/style-*.md` files
- 3. Done! Your Skill now has your own brand identity.
- ### Option 2: Add New Styles
- 1. Create `styles/style-{name}.md` (e.g., `style-corporate.md`)
- 2. Follow the format in existing style files
- 3. Use with `--style {name}`
- ### Example: Custom Brand Palette
- Edit `styles/brand-colors.md`:
- ```markdown
- ## Core / 核心色
- | Your Brand Color | `#XXXXXX` | Your main color |
- ## Accent / 点缀色
- | Your Accent | `#XXXXXX` | Your accent color |
- ```
- ### Option 3: Customize AI Prompts
- All AI prompts are centralized in `prompts/` directory for easy customization:
- ```
- prompts/
- ├── README.md # Prompt management guide
- ├── varied-styles.md # Style hints for Varied mode
- └── learning-analysis.md # Cover learning analysis prompt
- ```
- **To customize:**
- 1. Edit the Markdown files directly (no code changes needed)
- 2. Changes take effect immediately on next generation
- 3. See `prompts/README.md` for detailed instructions
- **Difference from Style System:**
- - **Style files** (`styles/*.md`): Define core design rules (composition, colors, constraints)
- - **Prompt templates** (`prompts/*.md`): Define generation strategies (style hints, analysis focus)
- - Both work together: styles set the foundation, prompts add nuance
- ## Configuration Reference
- ### Mermaid Engine Parameters
- | Parameter | Value | Description |
- |-----------|-------|-------------|
- | `-s` | `3` | 3x scale for high-resolution output |
- | `-w` | `1600` | 1600px width |
- | `-b` | `white` | White background (light style) |
- | `-t` | `neutral` | Neutral theme |
- **Full command:**
- ```bash
- mmdc -i input.mmd -o output.png -s 3 -w 1600 -b white
- ```
- **Mermaid Best Practices:**
- This skill follows the style guidelines from [mermaid-visualizer](https://github.com/axtonliu/axton-obsidian-visual-skills):
- - Use `subgraph id["Display Name"]` format for groups with spaces
- - Reference nodes by ID, not display text
- - Avoid `number. space` patterns (use `①②③` or `(1)(2)(3)` instead)
- - Apply consistent color coding per layer/category
- - Use `direction LR` inside subgraphs for horizontal layouts
- ### Gemini Engine Parameters
- | Parameter | Value | Description |
- |-----------|-------|-------------|
- | Model | `gemini-3-pro-image-preview` | Best for illustrations |
- | Resolution | 2K (2816×1536) | High-res output via `imageConfig.imageSize` |
- | Content Aspect | 3:4 portrait | Optimized for article embedding |
- | Cover Aspect | 16:9 landscape | Platform-ready cover format |
- | Cover Text | **None** | Clean visual, title shown by platform |
- ### Brand Color Palette (Default: Axton Brand)
- | Name | Hex | Usage |
- |------|-----|-------|
- | Deep Space Violet | `#2F2B42` | Core color, dark backgrounds |
- | Amber | `#F59E0B` | Accent, highlights, Skills layer |
- | Sky Blue | `#38BDF8` | Accent, secondary highlights, Agents layer |
- | Light Gray | `#F8F9FA` | Light backgrounds, neutral elements |
- ### Style Files
- | File | Purpose | Aspect |
- |------|---------|--------|
- | `styles/style-light.md` | Content illustrations (default) | 3:4 portrait |
- | `styles/style-dark.md` | Cover images | 16:9 landscape |
- | `styles/style-minimal.md` | Technical docs | 3:4 portrait |
- | `styles/style-cover.md` | YouTube/social covers | Platform-specific |
- | `styles/brand-colors.md` | Color palette reference | - |
- ## Cost
- When using Gemini API for auto-generation:
- | Model | Price | Quality |
- |-------|-------|---------|
- | `gemini-3-pro-image-preview` | $0.134/image ≈ ¥1/image | 2K (default) |
- Get API Key: https://aistudio.google.com/apikey
- ## Contributing
- Contributions welcome (low-maintenance project):
- - Reproducible bug reports (input + output + steps + environment)
- - Documentation improvements
- - Small PRs (fixes/docs)
- > **Note:** Feature requests may not be acted on due to limited maintenance capacity.
- ## Acknowledgments
- This project builds upon these excellent tools:
- - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) - Anthropic's AI coding assistant
- - [Mermaid](https://mermaid.js.org/) - Diagramming and charting tool
- - [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli) - Command line interface for Mermaid
- - [Excalidraw](https://excalidraw.com/) - Virtual whiteboard for hand-drawn diagrams
- - [Playwright](https://playwright.dev/) - Browser automation (for Excalidraw PNG export)
- - [Gemini API](https://ai.google.dev/) - Google's image generation API
- - [Bun](https://bun.sh/) - Fast JavaScript runtime
- ## License
- MIT License - see [LICENSE](LICENSE) for details.
- ---
- ## Author
- **Axton Liu** - AI Educator & Creator
- - Website: [axtonliu.ai](https://www.axtonliu.ai)
- - YouTube: [@AxtonLiu](https://youtube.com/@AxtonLiu)
- - Twitter/X: [@axtonliu](https://twitter.com/axtonliu)
- ### Learn More
- - [MAPS™ AI Agent Course](https://www.axtonliu.ai/aiagent) - Systematic AI agent skills training
- - [Agent Skills Resource Library](https://www.axtonliu.ai/agent-skills) - Claude Code Skills collection and guides
- - [Claude Skills: A Systematic Guide](https://www.axtonliu.ai/newsletters/ai-2/posts/claude-agent-skills-maps-framework) - Complete methodology
- - [AI Elite Weekly Newsletter](https://www.axtonliu.ai/newsletters/ai-2) - Weekly AI insights
- - [Free AI Course](https://www.axtonliu.ai/axton-free-course) - Get started with AI
- ---
- MIT License © [Axton Liu](https://www.axtonliu.ai)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.