Cover 模式

/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 |

{ "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：

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：

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）：

# 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）：

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. 同时保存到文件备份

# 执行方式
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 配图

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 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 installed
• Bun runtime (for scripts)
• 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/

Usage

Basic Usage

# 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)

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)

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)

# 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:

{
  "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]" }
  ]
}

Critica