Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/axtonliu-smart-illustrator/badge.svg)](/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

i

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)

  1. ---
  2. name: smart-illustrator
  3. description: 智能配图与 PPT 信息图生成器。支持三种模式:(1) 文章配图模式 - 分析文章内容,生成插图;(2) PPT/Slides 模式 - 生成批量信息图;(3) Cover 模式 - 生成封面图。所有模式默认生成图片,`--prompt-only` 只输出 prompt。支持 Bento Grid 功能展示图风格(--style bento)。触发词:配图、插图、PPT、slides、封面图、thumbnail、cover、bento grid、功能展示图、feature showcase。
  4. ---
  5. # Smart Illustrator - 智能配图与 PPT 生成器
  6. ## ⛔ 强制规则(违反即失败)
  7. ### 规则 1:用户提供的文件 = 要处理的文章
  8. ```
  9. /smart-illustrator SKILL_05.md → SKILL_05.md 是文章,为它配图
  10. /smart-illustrator README.md → README.md 是文章,为它配图
  11. /smart-illustrator whatever.md → whatever.md 是文章,为它配图
  12. ```
  13. **无论文件名叫什么,都是要配图的文章,不是 Skill 配置。**
  14. ### 规则 2:必须读取 style 文件
  15. 生成任何图片 prompt 前,**必须读取**对应的 style 文件:
  16. | 模式 | 必须读取的文件 |
  17. |------|---------------|
  18. | 文章配图(默认) | `styles/style-light.md` |
  19. | Cover 封面图 | `styles/style-cover.md` |
  20. | `--style dark` | `styles/style-dark.md` |
  21. | `--style bento` | `styles/style-bento.md` |
  22. **禁止自己编写 System Prompt。**
  23. ❌ 错误:`"你是一个专业的信息图设计师..."`(自己编的)
  24. ✅ 正确:从 style 文件的代码块中提取 System Prompt
  25. ---
  26. ## 使用方式
  27. ### 文章配图模式(默认)
  28. ```bash
  29. /smart-illustrator path/to/article.md
  30. /smart-illustrator path/to/article.md --prompt-only # 只输出 prompt
  31. /smart-illustrator path/to/article.md --style dark # 深色风格
  32. /smart-illustrator path/to/article.md --no-cover # 不生成封面图
  33. ```
  34. ### PPT/Slides 模式
  35. ```bash
  36. # 默认:直接生成图片
  37. /smart-illustrator path/to/script.md --mode slides
  38. # 只输出 JSON prompt(不调用 API)
  39. /smart-illustrator path/to/script.md --mode slides --prompt-only
  40. ```
  41. **默认行为**:调用 Gemini API 生成批量信息图。
  42. **`--prompt-only`**:输出 JSON prompt 并**自动复制到剪贴板**,可直接粘贴到 Gemini Web 手动生成。
  43. **PPT JSON 格式**(`--prompt-only` 时输出):
  44. ```json
  45. {
  46. "instruction": "请逐条生成以下 N 张独立信息图。",
  47. "batch_rules": { "total": "N", "one_item_one_image": true, "aspect_ratio": "16:9" },
  48. "style": "[从 styles/style-light.md 读取完整内容]",
  49. "pictures": [
  50. { "id": 1, "topic": "封面", "content": "系列名称\n\n第N节:标题" },
  51. { "id": 2, "topic": "主题", "content": "原始内容" }
  52. ]
  53. }
  54. ```
  55. ### Cover 模式
  56. ```bash
  57. /smart-illustrator path/to/article.md --mode cover --platform youtube
  58. /smart-illustrator --mode cover --platform youtube --topic "Claude 4 深度评测"
  59. ```
  60. **平台尺寸**(输出均为 2K 分辨率):
  61. | 平台 | 代码 | 宽高比 |
  62. |------|------|--------|
  63. | YouTube | `youtube` | 16:9 |
  64. | 公众号 | `wechat` | 2.35:1 |
  65. | Twitter | `twitter` | 1.91:1 |
  66. | 小红书 | `xiaohongshu` | 3:4 |
  67. ---
  68. ## 参数说明
  69. | 参数 | 默认值 | 说明 |
  70. |------|--------|------|
  71. | `--mode` | `article` | `article` / `slides` / `cover` |
  72. | `--platform` | `youtube` | 封面图平台(仅 cover 模式) |
  73. | `--topic` | - | 封面图主题(仅 cover 模式) |
  74. | `--prompt-only` | `false` | 输出 prompt 到剪贴板,不调用 API(适用于所有模式) |
  75. | `--style` | `light` | 风格:`light` / `dark` / `minimal` / `bento` |
  76. | `--no-cover` | `false` | 不生成封面图 |
  77. | `--ref` | - | 参考图路径(可多次使用) |
  78. | `-c, --candidates` | `1` | 候选图数量(最多 4) |
  79. | `-a, --aspect-ratio` | - | 宽高比:`16:9`(正文配图/封面图默认)、`3:2`(备选横版)、`3:4`(仅竖屏平台) |
  80. | `--engine` | `auto` | 引擎选择:`auto`(自动)/ `mermaid` / `gemini` / `excalidraw` |
  81. | `--mermaid-embed` | `false` | Mermaid 输出为代码块而非 PNG(旧行为) |
  82. | `--save-config` | - | 保存到项目配置 |
  83. | `--no-config` | `false` | 禁用 config.json |
  84. > **`--no-config` 范围**:只禁用 `config.json`,**不影响** `styles/style-*.md`。
  85. ---
  86. ## 配置文件
  87. **优先级**:CLI 参数 > 项目级 > 用户级
  88. | 位置 | 路径 |
  89. |------|------|
  90. | 项目级 | `.smart-illustrator/config.json` |
  91. | 用户级 | `~/.smart-illustrator/config.json` |
  92. ```json
  93. { "references": ["./refs/style-ref-01.png"] }
  94. ```
  95. ---
  96. ## 三级配图引擎
  97. | 优先级 | 引擎 | 适用场景 | 输出 |
  98. |--------|------|---------|------|
  99. | **1** | Gemini | 隐喻图、创意图、封面图、无法用图表表达的概念 | PNG |
  100. | **2** | Excalidraw | 概念图、对比图、简单流程(≤ 8 节点)、关系图、手绘风格示意图 | PNG |
  101. | **3** | Mermaid | **仅限**:复杂流程(> 8 节点)、多层架构图、多角色时序图、多分支决策树 | PNG |
  102. 选择逻辑:
  103. - 需要隐喻、情感、创意表达 → Gemini
  104. - 概念关系、对比、简单流程 → Excalidraw(**大多数图表场景的首选**)
  105. - **只有**节点 > 8、多层/多角色的复杂结构化图形 → Mermaid
  106. - Mermaid 视觉表现力有限,能用 Excalidraw 就不用 Mermaid
  107. - 唯一目标:提高文章吸引力
  108. 生成 Excalidraw 前必须读取 `references/excalidraw-guide.md`。
  109. ### Mermaid 语义色板
  110. 每种颜色有固定含义,**必须使用 `classDef` + `class` 应用**:
  111. | 语义 | 填充色 | 边框色 | 用于 |
  112. |------|--------|--------|------|
  113. | input | #d3f9d8 | #2f9e44 | 输入、起点、数据源 |
  114. | process | #e5dbff | #5f3dc4 | 处理、推理、核心逻辑 |
  115. | decision | #ffe3e3 | #c92a2a | 决策点、分支判断 |
  116. | action | #ffe8cc | #d9480f | 执行动作、工具调用 |
  117. | output | #c5f6fa | #0c8599 | 输出、结果、终点 |
  118. | storage | #fff4e6 | #e67700 | 存储、记忆、数据库 |
  119. | meta | #e7f5ff | #1971c2 | 标题、分组、元信息 |
  120. **classDef 写法**(放在图表末尾):
  121. ```
  122. classDef input fill:#d3f9d8,stroke:#2f9e44,color:#1a1a1a
  123. classDef process fill:#e5dbff,stroke:#5f3dc4,color:#1a1a1a
  124. classDef decision fill:#ffe3e3,stroke:#c92a2a,color:#1a1a1a
  125. classDef action fill:#ffe8cc,stroke:#d9480f,color:#1a1a1a
  126. classDef output fill:#c5f6fa,stroke:#0c8599,color:#1a1a1a
  127. class A input
  128. class B,C process
  129. class D output
  130. ```
  131. ### Mermaid 布局规则
  132. - **布局方向**:默认 `TB`(上到下),横向流程用 `LR`
  133. - **箭头分级**:`-->` 主流程 / `-.->` 可选/辅助路径 / `==>` 重点强调
  134. - **分组**:用 `subgraph` 对相关节点分组,标题简洁
  135. - **节点文字**:≤ 8 字,无 emoji,禁止 `1.` 格式(用 `①` 或 `Step 1:`)
  136. - **节点数量**:单图 ≤ 15 个节点,复杂内容拆成多图
  137. **`--engine` 参数**:
  138. - `auto`(默认):根据内容类型自动选择(优先级 Gemini > Excalidraw > Mermaid)
  139. - `gemini`:强制只使用 Gemini(适合创意内容)
  140. - `excalidraw`:强制只使用 Excalidraw(适合手绘概念图)
  141. - `mermaid`:强制只使用 Mermaid(适合技术文档)
  142. ---
  143. ## 执行流程
  144. ### Step 1: 分析文章
  145. 1. 读取文章内容
  146. 2. 识别配图位置(通常 3-5 个)
  147. 3. 为每个位置确定引擎(Gemini / Excalidraw / Mermaid)
  148. ### Step 2: 生成图片
  149. #### Mermaid(结构化图形)→ PNG
  150. 1. 生成 Mermaid 代码,保存为临时 `.mmd` 文件
  151. 2. 调用 mermaid-export.ts 导出高分辨率 PNG:
  152. ```bash
  153. npx -y bun ~/.claude/skills/smart-illustrator/scripts/mermaid-export.ts \
  154. -i {图表名}.mmd -o {图表名}.png -w 2400
  155. ```
  156. 3. 在文章中插入 PNG 图片引用
  157. 4. 保留 .mmd 源文件用于后续编辑
  158. 使用 `--mermaid-embed` 参数时,改为直接嵌入 Mermaid 代码块(旧行为)。
  159. #### Excalidraw(手绘/概念图)→ PNG
  160. 1. 读取 `references/excalidraw-guide.md` 获取 JSON 规范
  161. 2. 生成 Excalidraw JSON,保存为 `.excalidraw` 文件
  162. 3. 调用 excalidraw-export.ts 导出 PNG:
  163. ```bash
  164. npx -y bun ~/.claude/skills/smart-illustrator/scripts/excalidraw-export.ts \
  165. -i {图表名}.excalidraw -o {图表名}.png -s 2
  166. ```
  167. 4. 在文章中插入 PNG 图片引用
  168. 5. 保留 .excalidraw 源文件用于后续编辑
  169. 依赖未安装时的降级:提示手动打开 excalidraw.com 导出。
  170. #### Gemini(创意/视觉图形)
  171. **命令模板**(必须使用 HEREDOC + prompt-file):
  172. ```bash
  173. # Step 1: 写入 prompt
  174. cat > /tmp/image-prompt.txt <<'EOF'
  175. {从 style 文件提取的 System Prompt}
  176. **内容**:{配图内容}
  177. EOF
  178. # Step 2: 调用脚本
  179. GEMINI_API_KEY=$GEMINI_API_KEY npx -y bun ~/.claude/skills/smart-illustrator/scripts/generate-image.ts \
  180. --prompt-file /tmp/image-prompt.txt \
  181. --output {输出路径}.png \
  182. --aspect-ratio 16:9
  183. ```
  184. **封面图**(16:9):
  185. ```bash
  186. cat > /tmp/cover-prompt.txt <<'EOF'
  187. {从 style-cover.md 提取的 System Prompt}
  188. **内容**:
  189. - 核心概念:{主题}
  190. - 视觉隐喻:{设计}
  191. EOF
  192. GEMINI_API_KEY=$GEMINI_API_KEY npx -y bun ~/.claude/skills/smart-illustrator/scripts/generate-image.ts \
  193. --prompt-file /tmp/cover-prompt.txt \
  194. --output {文章名}-cover.png \
  195. --aspect-ratio 16:9
  196. ```
  197. **参数传递**:用户指定的 `--no-config`、`--ref`、`-c` 必须传递给脚本。
  198. ### Step 3: 创建带配图的文章
  199. 保存为 `{文章名}-image.md`,包含:
  200. - YAML frontmatter 声明封面图
  201. - 正文配图插入
  202. ### Step 4: 输出确认
  203. 报告:生成了几张图片、输出文件列表。
  204. ---
  205. ## `--prompt-only` 模式
  206. 当使用 `--prompt-only` 时,**不调用 API**,而是:
  207. 1. 生成 JSON prompt
  208. 2. **自动复制到剪贴板**(使用 `pbcopy`)
  209. 3. 同时保存到文件备份
  210. ```bash
  211. # 执行方式
  212. echo '{生成的 JSON}' | pbcopy
  213. echo "✓ JSON prompt 已复制到剪贴板"
  214. # 同时保存备份
  215. echo '{生成的 JSON}' > /tmp/smart-illustrator-prompt.json
  216. echo "✓ 备份已保存到 /tmp/smart-illustrator-prompt.json"
  217. ```
  218. 用户可直接粘贴到 Gemini Web 手动生成图片。
  219. ---
  220. ## 输出文件
  221. ```
  222. article.md # 原文(不修改)
  223. article-image.md # 带配图的文章
  224. article-cover.png # 封面图(16:9)
  225. article-image-01.png # Gemini 配图
  226. ```
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)

  1. # Smart Illustrator
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![Status: Experimental](https://img.shields.io/badge/Status-Experimental-orange.svg)](#status)
  4. **[中文文档](README.zh-CN.md)**
  5. > **🆕 v1.4.0 — Tri-Engine System (Feb 2026)**
  6. >
  7. > 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)
  8. ![Tri-Engine Architecture](assets/dual-engine-architecture.png)
  9. 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.
  10. ## Status
  11. > **Status: Experimental**
  12. >
  13. > - This is a public prototype that works for my demos, but does not yet cover all input scales and edge cases.
  14. > - Output quality varies based on model version and input structure; results may fluctuate.
  15. > - My primary focus is demonstrating how tools and systems work together, not maintaining this codebase.
  16. > - If you encounter issues, please submit a reproducible case (input + output file + steps to reproduce).
  17. ## Why Smart Illustrator?
  18. 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.
  19. **Who it's for:** Newsletter writers, YouTube creators, technical bloggers, course instructors.
  20. **When to use:** When you need high-quality illustrations for articles, YouTube thumbnails with best practices, or consistent visual style across content series.
  21. ## Background: the Make workflow version (auto-illustrate + WeChat publish)
  22. Before packaging this into a Skill, I had already built an end-to-end Make workflow:
  23. **search → write → auto-illustrate → format/publish (WeChat Official Account)**.
  24. Full walkthrough (workflow logic & design trade-offs):
  25. https://youtu.be/TbyJ3imLuXQ
  26. ## Features
  27. - **Tri-Engine System**: Auto-selects Gemini, Excalidraw, or Mermaid based on content type
  28. - **Smart Position Detection**: Analyzes article structure to identify optimal illustration points
  29. - **10+ Illustration Types**: flowchart, sequence, mindmap, concept, comparison, scene, metaphor...
  30. - **Extensible Style System**: Light, Dark, Minimal, Cover, and custom styles
  31. - **Cover Mode**: Generate high-CTR YouTube thumbnails with best practices built-in
  32. - **Multi-Platform Sizes**: YouTube, WeChat, Twitter, Xiaohongshu presets
  33. - **Resume Generation**: Skip already-generated images, regenerate specific ones
  34. - **Brand Customizable**: Modify `styles/` to apply your brand style
  35. - **Multiple Backends**: Gemini API for creative visuals (2K resolution), Excalidraw for hand-drawn diagrams, Mermaid CLI for structured diagrams — all output PNG by default
  36. ## What Are Skills?
  37. 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.
  38. ## Installation
  39. ### Prerequisites
  40. - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed
  41. - [Bun](https://bun.sh/) runtime (for scripts)
  42. - [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli) (for Mermaid diagrams): `npm install -g @mermaid-js/mermaid-cli`
  43. - Excalidraw export dependencies (optional, for Excalidraw diagrams): `cd ~/.claude/skills/smart-illustrator/scripts && npm install && npx playwright install firefox`
  44. - Gemini API Key (optional, for creative visuals): https://aistudio.google.com/apikey
  45. ### Option A: Manual Installation (Recommended)
  46. ```bash
  47. # Clone to Claude Code Skills directory
  48. git clone https://github.com/axtonliu/smart-illustrator.git ~/.claude/skills/smart-illustrator
  49. ```
  50. ### Option B: Copy Individual Files
  51. ```bash
  52. # If you only want the skill without scripts
  53. cp -r smart-illustrator/SKILL.md ~/.claude/skills/smart-illustrator/
  54. cp -r smart-illustrator/styles ~/.claude/skills/smart-illustrator/
  55. ```
  56. ## Usage
  57. ### Basic Usage
  58. ```bash
  59. # Analyze article and auto-generate illustrations (default)
  60. /smart-illustrator path/to/article.md
  61. # Output prompts only, don't auto-generate images
  62. /smart-illustrator path/to/article.md --prompt-only
  63. # Specify style (loads from styles/ directory)
  64. /smart-illustrator path/to/article.md --style light # Light style (default)
  65. /smart-illustrator path/to/article.md --style dark # Dark tech style
  66. /smart-illustrator path/to/article.md --style minimal # Minimal style
  67. # List available styles
  68. /smart-illustrator --list-styles
  69. # Without cover image
  70. /smart-illustrator path/to/article.md --no-cover
  71. # Specify number of illustrations
  72. /smart-illustrator path/to/article.md --count 5
  73. ```
  74. ### Parameters
  75. | Parameter | Default | Description |
  76. |-----------|---------|-------------|
  77. | `--mode` | `article` | Mode: `article`, `slides`, or `cover` |
  78. | `--engine` | `auto` | Engine: `auto`, `gemini`, `excalidraw`, or `mermaid` |
  79. | `--mermaid-embed` | `false` | Embed Mermaid code blocks instead of exporting PNG |
  80. | `--platform` | `youtube` | Cover platform: `youtube`/`wechat`/`twitter`/`xiaohongshu`/`landscape`/`square` |
  81. | `--topic` | - | Cover topic (alternative to article path, cover mode only) |
  82. | `--description` | - | Cover visual direction (cover mode only) |
  83. | `--prompt-only` | `false` | Output prompts only, don't call API to generate images |
  84. | `--style` | `light` | Style name, loads `styles/style-{name}.md` |
  85. | `--list-styles` | - | List all available styles in `styles/` directory |
  86. | `--no-cover` | `false` | Skip cover image generation (article mode) |
  87. | `--count` | auto | Number of illustrations (auto-determined by article length) |
  88. ### Illustration Count Guidelines
  89. | Article Length | Suggested Count |
  90. |----------------|-----------------|
  91. | Short (< 1000 words) | 1-2 images |
  92. | Medium (1000-3000 words) | 2-4 images |
  93. | Long (> 3000 words) | 4-6 images |
  94. | Tutorials/Guides | 1 per major step |
  95. ### Output Files
  96. ```
  97. article.md # Original
  98. article-image.md # Article with illustrations (main output)
  99. article-cover.png # Cover image (16:9)
  100. article-image-01.png # Content illustration (3:4)
  101. article-image-02.png
  102. article-image-03.png
  103. ```
  104. ### Manual Script Usage
  105. #### generate-image.ts (Single Image)
  106. ```bash
  107. export GEMINI_API_KEY=your_key
  108. # From prompt text
  109. npx -y bun ~/.claude/skills/smart-illustrator/scripts/generate-image.ts \
  110. --prompt "A concept diagram showing..." \
  111. --output image.png
  112. # From prompt file
  113. npx -y bun ~/.claude/skills/smart-illustrator/scripts/generate-image.ts \
  114. --prompt-file prompt.md \
  115. --output image.png
  116. ```
  117. | Option | Description |
  118. |--------|-------------|
  119. | `-p, --prompt` | Image description text |
  120. | `-f, --prompt-file` | Read prompt from file |
  121. | `-o, --output` | Output path (default: generated.png) |
  122. | `-m, --model` | Model (default: gemini-3-pro-image-preview) |
  123. #### batch-generate.ts (Batch Generation)
  124. ```bash
  125. export GEMINI_API_KEY=your_key
  126. npx -y bun ~/.claude/skills/smart-illustrator/scripts/batch-generate.ts \
  127. --config slides.json \
  128. --output-dir ./images \
  129. --prefix SKILL_01
  130. ```
  131. | Option | Description |
  132. |--------|-------------|
  133. | `-c, --config` | JSON config file (required) |
  134. | `-o, --output-dir` | Output directory (default: ./illustrations) |
  135. | `-m, --model` | Model (default: gemini-3-pro-image-preview) |
  136. | `-d, --delay` | Delay between requests in ms (default: 2000) |
  137. | `-p, --prefix` | Filename prefix (default: from config filename) |
  138. | `-r, --regenerate` | Regenerate specific images (e.g., "3" or "3,5,7") |
  139. | `-f, --force` | Force regenerate all images (ignore existing) |
  140. **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.
  141. Output: `{prefix}-01.png`, `{prefix}-02.png`, etc.
  142. #### mermaid-export.ts (Mermaid to PNG)
  143. ```bash
  144. # From .mmd file
  145. npx -y bun ~/.claude/skills/smart-illustrator/scripts/mermaid-export.ts \
  146. --input diagram.mmd \
  147. --output diagram.png
  148. # From inline content
  149. npx -y bun ~/.claude/skills/smart-illustrator/scripts/mermaid-export.ts \
  150. --content "flowchart LR
  151. A[Start] --> B[End]" \
  152. --output simple.png \
  153. --theme dark
  154. ```
  155. | Option | Description |
  156. |--------|-------------|
  157. | `-i, --input` | Input .mmd file path |
  158. | `-c, --content` | Mermaid diagram content (alternative) |
  159. | `-o, --output` | Output path (default: output.png) |
  160. | `-t, --theme` | Theme: `light` (default) or `dark` |
  161. | `-w, --width` | Image width in pixels |
  162. | `-H, --height` | Image height in pixels |
  163. ## PPT/Slides Generation Mode
  164. Beyond article illustrations, this skill can generate batch infographics for PPT/Keynote slides.
  165. ### When to Use
  166. | Mode | Use Case | Output |
  167. |------|----------|--------|
  168. | **Article Mode** | Blog posts, newsletters | 3-5 illustrations inserted in article |
  169. | **Slides Mode** | Video B-roll, presentations | 8-15 standalone infographics |
  170. ### JSON Format for Batch Generation
  171. Use `pictures[]` array format with explicit batch rules:
  172. ```json
  173. {
  174. "instruction": "请为我绘制 7 张图片(generate 7 images)。你是一位「信息图绘制者」。请逐条执行 pictures 数组:每个 id 对应 1 张独立的 16:9 信息图,严禁合并,严禁只输出文字描述。",
  175. "batch_rules": {
  176. "total": 7,
  177. "one_item_one_image": true,
  178. "aspect_ratio": "16:9",
  179. "do_not_merge": true
  180. },
  181. "fallback": "如果无法一次生成全部图片:请输出 7 条独立的单图绘图指令...",
  182. "style": "[Complete style prompt - see styles/style-light.md]",
  183. "pictures": [
  184. { "id": 1, "topic": "封面", "content": "Course Name\n\nSection Title\n\nLearning objectives..." },
  185. { "id": 2, "topic": "核心概念", "content": "[Raw content]" }
  186. ]
  187. }
  188. ```
  189. ### Critical Rules
  190. 1. **Use `pictures[]` array** - Array structure helps Gemini enter "loop execution" mode for batch generation.
  191. 2. **Add image trigger phrase** - Must include "请为我绘制 N 张图片(generate N images)" to trigger image generation mode.
  192. 3. **Role as "绘制者" not "导演"** - Use "信息图绘制者" (illustrator) not "视觉导演" (director) to trigger actual drawing behavior.
  193. 4. **Separate instruction from style** - `instruction` = what to do + role; `style` = visual rules only.
  194. 5. **Pass complete style** - Include the full style prompt from `styles/style-light.md`, don't summarize.
  195. 6. **Content granularity** - Judge by information density, not mechanically by H2 headers.
  196. ### Cover Slide Branding (PPT Mode)
  197. For course/series content, the cover slide (`id: 1`) should include:
  198. ```json
  199. {
  200. "id": 1,
  201. "topic": "封面",
  202. "content": "Agent Skills 完全指南\n\n第4节:渐进式披露与 Description 优化\n\n学习目标:理解 Progressive Disclosure 机制"
  203. }
  204. ```
  205. Structure:
  206. - **Series name**: e.g., "Agent Skills 完全指南"
  207. - **Section number**: e.g., "第4节"
  208. - **Section title**: e.g., "渐进式披露与 Description 优化"
  209. - **Learning objectives** (optional)
  210. ### Output Options (Applies to All Modes)
  211. `--prompt-only` is a **global option** that works with Article, Slides, Cover, and all other modes:
  212. | Output Mode | Parameter | Description | API Required |
  213. |-------------|-----------|-------------|--------------|
  214. | Generate Images | Default | Calls Gemini API to generate images | ✅ Yes |
  215. | Output JSON Prompt | `--prompt-only` | Copy to Gemini Web for manual generation | ❌ No |
  216. **Example Combinations:**
  217. ```bash
  218. # Slides mode + generate images (needs API)
  219. /smart-illustrator script.md --mode slides
  220. # Slides mode + output JSON only (no API)
  221. /smart-illustrator script.md --mode slides --prompt-only
  222. # Article mode + generate images (needs API)
  223. /smart-illustrator article.md
  224. # Article mode + output JSON only (no API)
  225. /smart-illustrator article.md --prompt-only
  226. ```
  227. **Manual Batch Generation (after JSON prompt output):**
  228. ```bash
  229. export GEMINI_API_KEY=your_key
  230. npx -y bun ~/.claude/skills/smart-illustrator/scripts/batch-generate.ts \
  231. --config slides.json \
  232. --output-dir ./images
  233. ```
  234. See `references/slides-prompt-example.json` for a complete example.
  235. > **💡 Tip**: Batch image generation with JSON in Gemini doesn't have 100% success rate. If generation fails:
  236. > 1. Retry 1-3 times (usually succeeds)
  237. > 2. If retries fail, copy individual items from `pictures` array and generate one by one
  238. ---
  239. ## Configuration Files (Style Reuse)
  240. Save common parameters to configuration files for consistent style across series content (courses, newsletters).
  241. ### Configuration File Locations
  242. **Priority: CLI Arguments > Project Config > User Config**
  243. | Location | Path | Purpose |
  244. |----------|------|---------|
  245. | Project | `{working-dir}/.smart-illustrator/config.json` | Project-specific style (e.g., course series) |
  246. | User | `~/.smart-illustrator/config.json` | User's global default style |
  247. ### Configuration File Format
  248. ```json
  249. {
  250. "references": [
  251. "./refs/style-ref-01.png",
  252. "./refs/style-ref-02.png"
  253. ]
  254. }
  255. ```
  256. **Supported options**:
  257. - `references`: Array of reference image paths (relative paths are resolved relative to config file directory)
  258. ### Usage Examples
  259. ```bash
  260. # Initial setup: configure style for course series
  261. cd ~/my-course
  262. /smart-illustrator article-01.md --ref ./refs/style-1.png --save-config
  263. # Subsequent generation: auto-apply config
  264. /smart-illustrator article-02.md # Automatically uses reference images
  265. # Temporary override: use different reference
  266. /smart-illustrator article-03.md --ref ./other-ref.png
  267. # Completely ignore config
  268. /smart-illustrator article-04.md --no-config
  269. # Save to user-level config (global default)
  270. /smart-illustrator article.md --ref ./my-style.png --save-config-global
  271. ```
  272. ### Configuration Loading Rules
  273. 1. Read user-level config (if exists)
  274. 2. Read project-level config (if exists, overrides user-level)
  275. 3. Apply command-line arguments (overrides config files)
  276. **Typical scenarios**:
  277. - **Course series**: Save `.smart-illustrator/config.json` in project directory for unified style across chapters
  278. - **Personal default**: Save `~/.smart-illustrator/config.json` in user directory as global default
  279. - **Temporary adjustment**: Use `--ref` parameter to temporarily override config without modifying saved settings
  280. ---
  281. ## Cover Mode (YouTube Thumbnails)
  282. Generate high-CTR cover images for YouTube, WeChat, Twitter, and more. Built on YouTuber best practices research.
  283. ```bash
  284. # Generate YouTube thumbnail from article
  285. /smart-illustrator path/to/article.md --mode cover --platform youtube
  286. # Generate with specific topic
  287. /smart-illustrator --mode cover --platform youtube --topic "Claude 4 Deep Review"
  288. # Generate with visual direction
  289. /smart-illustrator --mode cover --platform wechat --description "Comparison diagram + tech aesthetic"
  290. ```
  291. ### Supported Platforms
  292. All outputs are **2K resolution** (e.g., ~2816×1584 for 16:9).
  293. | Platform | Code | Aspect Ratio |
  294. |----------|------|--------------|
  295. | YouTube | `youtube` | 16:9 |
  296. | WeChat | `wechat` | 2.35:1 |
  297. | Twitter/X | `twitter` | 1.91:1 |
  298. | Xiaohongshu | `xiaohongshu` | 3:4 |
  299. | Landscape | `landscape` | 16:9 |
  300. | Square | `square` | 1:1 |
  301. ### Design Principles (from `references/cover-best-practices.md`)
  302. 1. **3-Second Rule**: Instantly convey topic and value
  303. 2. **High Contrast**: Dark background + bright subject
  304. 3. **Single Focus**: Only one visual center
  305. 4. **Minimal Text**: 3-6 words, bold sans-serif
  306. 5. **Curiosity Gap**: Make viewers want to click
  307. ### Visual Metaphors for Tech Content
  308. | Concept | Metaphor |
  309. |---------|----------|
  310. | AI Assistant | Two collaborative hands, chat bubbles |
  311. | Efficiency | Upward arrows, stairs, rocket trail |
  312. | Automation | Gears, assembly line nodes |
  313. | Learning/Growth | Seed → tree, ascending stairs |
  314. | Problem → Solution | Maze exit, completed puzzle |
  315. ---
  316. ## Smart Position Detection
  317. The skill analyzes article structure to identify optimal illustration points:
  318. | Signal | Illustration Value |
  319. |--------|-------------------|
  320. | Abstract concept first appears | High - helps build mental model |
  321. | Process/step description | High - visual is clearer than text |
  322. | Comparison/choice discussion | High - side-by-side is clear |
  323. | Data/statistics reference | Medium - numbers visualized have impact |
  324. | Section transition point | Medium - provides visual breathing room |
  325. | Emotional/story climax | Medium - enhances resonance |
  326. ---
  327. ## Tri-Engine System
  328. The skill automatically selects the best rendering engine based on content, with three-tier priority:
  329. | Priority | Engine | Best For | Output |
  330. |----------|--------|----------|--------|
  331. | **1** | **Gemini** | Creative visuals (metaphors, scenes, infographics) | PNG (2K) |
  332. | **2** | **Excalidraw** | Hand-drawn concept diagrams, comparisons, simple flows | PNG |
  333. | **3** | **Mermaid** | Complex structured diagrams (flowcharts, sequences, architectures) | PNG |
  334. **Selection logic:**
  335. - Needs metaphor, emotion, or creative expression → Gemini
  336. - Needs hand-drawn / informal style, or simple concept relationships → Excalidraw
  337. - Complex structured flows / architectures → Mermaid
  338. ## Illustration Types
  339. | Type | Engine | Best For | Syntax/Style |
  340. |------|--------|----------|--------------|
  341. | `process` | Mermaid | Complex workflows | `flowchart` |
  342. | `architecture` | Mermaid | System components | `block-beta` |
  343. | `sequence` | Mermaid | API calls, interactions | `sequenceDiagram` |
  344. | `mindmap` | Mermaid | Knowledge structure | `mindmap` |
  345. | `state` | Mermaid | State transitions | `stateDiagram` |
  346. | `concept` | Excalidraw / Gemini | Abstract concepts | Hand-drawn / Center-radial |
  347. | `comparison` | Excalidraw / Gemini | A vs B, contrasts | Hand-drawn / Left-right split |
  348. | `data` | Gemini | Statistics, trends | Infographic style |
  349. | `scene` | Gemini | Stories, scenarios | Narrative illustration |
  350. | `metaphor` | Gemini | Analogies, symbols | Creative visual |
  351. | `cover` | Gemini | Article cover | 16:9 dark tech |
  352. ### Type × Composition Reference
  353. | Type | Recommended Composition | Elements |
  354. |------|------------------------|----------|
  355. | concept | Center-radial, hierarchy | Core icon + surrounding factors |
  356. | process | Horizontal/vertical flow | Nodes + arrows + labels |
  357. | comparison | Left-right / top-bottom split | Two columns + corresponding items |
  358. | data | Chart-style | Numbers prominent + graphical |
  359. | scene | Narrative illustration | Characters + environment + action |
  360. | summary | Card grid, bullet points | Structured layout |
  361. | metaphor | Analogy visual | Creative visual metaphor |
  362. ## Style System
  363. ### Built-in Styles
  364. | Style | File | Best For |
  365. |-------|------|----------|
  366. | Light | `styles/style-light.md` | Content illustrations (default) |
  367. | Dark | `styles/style-dark.md` | Cover images, marketing |
  368. | Minimal | `styles/style-minimal.md` | Technical docs, whitepapers |
  369. | Cover | `styles/style-cover.md` | YouTube thumbnails, social covers (cover mode) |
  370. ### Content Illustrations: Light Style
  371. - 3:4 portrait format
  372. - Light gray background `#F8F9FA`
  373. - Flat geometric + thin lines
  374. - See `styles/style-light.md`
  375. ### Cover Images: Dark Tech Style
  376. - 16:9 landscape format
  377. - Deep blue gradient background
  378. - Line icons + glassmorphism
  379. - No text
  380. - See `styles/style-dark.md`
  381. ### Custom Styles
  382. Add your own style by creating `styles/style-{name}.md` and use it with `--style {name}`.
  383. ## File Structure
  384. ```
  385. smart-illustrator/
  386. ├── SKILL.md # Skill definition (Claude Code entry)
  387. ├── CLAUDE.md # Project rules (style sync, JSON format)
  388. ├── README.md
  389. ├── README.zh-CN.md # Chinese documentation
  390. ├── LICENSE
  391. ├── scripts/
  392. │ ├── generate-image.ts # Gemini single image generation
  393. │ ├── batch-generate.ts # Gemini batch generation (2K, resume support)
  394. │ ├── mermaid-export.ts # Mermaid diagram to PNG export
  395. │ ├── excalidraw-export.ts # Excalidraw diagram to PNG export
  396. │ └── package.json # Script dependencies (Excalidraw export)
  397. ├── styles/
  398. │ ├── brand-colors.md # Brand palette (customizable)
  399. │ ├── style-light.md # Light style Gemini prompt (default)
  400. │ ├── style-dark.md # Dark style Gemini prompt
  401. │ ├── style-minimal.md # Minimal style Gemini prompt
  402. │ └── style-cover.md # Cover/thumbnail style (cover mode)
  403. └── references/
  404. ├── slides-prompt-example.json # PPT mode JSON format example
  405. ├── cover-best-practices.md # YouTube thumbnail best practices
  406. └── excalidraw-guide.md # Excalidraw JSON specification
  407. ```
  408. ## Customization
  409. Want to use your own brand style?
  410. ### Option 1: Modify Existing Styles
  411. 1. Edit `styles/brand-colors.md` with your colors
  412. 2. Sync color values in `styles/style-*.md` files
  413. 3. Done! Your Skill now has your own brand identity.
  414. ### Option 2: Add New Styles
  415. 1. Create `styles/style-{name}.md` (e.g., `style-corporate.md`)
  416. 2. Follow the format in existing style files
  417. 3. Use with `--style {name}`
  418. ### Example: Custom Brand Palette
  419. Edit `styles/brand-colors.md`:
  420. ```markdown
  421. ## Core / 核心色
  422. | Your Brand Color | `#XXXXXX` | Your main color |
  423. ## Accent / 点缀色
  424. | Your Accent | `#XXXXXX` | Your accent color |
  425. ```
  426. ### Option 3: Customize AI Prompts
  427. All AI prompts are centralized in `prompts/` directory for easy customization:
  428. ```
  429. prompts/
  430. ├── README.md # Prompt management guide
  431. ├── varied-styles.md # Style hints for Varied mode
  432. └── learning-analysis.md # Cover learning analysis prompt
  433. ```
  434. **To customize:**
  435. 1. Edit the Markdown files directly (no code changes needed)
  436. 2. Changes take effect immediately on next generation
  437. 3. See `prompts/README.md` for detailed instructions
  438. **Difference from Style System:**
  439. - **Style files** (`styles/*.md`): Define core design rules (composition, colors, constraints)
  440. - **Prompt templates** (`prompts/*.md`): Define generation strategies (style hints, analysis focus)
  441. - Both work together: styles set the foundation, prompts add nuance
  442. ## Configuration Reference
  443. ### Mermaid Engine Parameters
  444. | Parameter | Value | Description |
  445. |-----------|-------|-------------|
  446. | `-s` | `3` | 3x scale for high-resolution output |
  447. | `-w` | `1600` | 1600px width |
  448. | `-b` | `white` | White background (light style) |
  449. | `-t` | `neutral` | Neutral theme |
  450. **Full command:**
  451. ```bash
  452. mmdc -i input.mmd -o output.png -s 3 -w 1600 -b white
  453. ```
  454. **Mermaid Best Practices:**
  455. This skill follows the style guidelines from [mermaid-visualizer](https://github.com/axtonliu/axton-obsidian-visual-skills):
  456. - Use `subgraph id["Display Name"]` format for groups with spaces
  457. - Reference nodes by ID, not display text
  458. - Avoid `number. space` patterns (use `①②③` or `(1)(2)(3)` instead)
  459. - Apply consistent color coding per layer/category
  460. - Use `direction LR` inside subgraphs for horizontal layouts
  461. ### Gemini Engine Parameters
  462. | Parameter | Value | Description |
  463. |-----------|-------|-------------|
  464. | Model | `gemini-3-pro-image-preview` | Best for illustrations |
  465. | Resolution | 2K (2816×1536) | High-res output via `imageConfig.imageSize` |
  466. | Content Aspect | 3:4 portrait | Optimized for article embedding |
  467. | Cover Aspect | 16:9 landscape | Platform-ready cover format |
  468. | Cover Text | **None** | Clean visual, title shown by platform |
  469. ### Brand Color Palette (Default: Axton Brand)
  470. | Name | Hex | Usage |
  471. |------|-----|-------|
  472. | Deep Space Violet | `#2F2B42` | Core color, dark backgrounds |
  473. | Amber | `#F59E0B` | Accent, highlights, Skills layer |
  474. | Sky Blue | `#38BDF8` | Accent, secondary highlights, Agents layer |
  475. | Light Gray | `#F8F9FA` | Light backgrounds, neutral elements |
  476. ### Style Files
  477. | File | Purpose | Aspect |
  478. |------|---------|--------|
  479. | `styles/style-light.md` | Content illustrations (default) | 3:4 portrait |
  480. | `styles/style-dark.md` | Cover images | 16:9 landscape |
  481. | `styles/style-minimal.md` | Technical docs | 3:4 portrait |
  482. | `styles/style-cover.md` | YouTube/social covers | Platform-specific |
  483. | `styles/brand-colors.md` | Color palette reference | - |
  484. ## Cost
  485. When using Gemini API for auto-generation:
  486. | Model | Price | Quality |
  487. |-------|-------|---------|
  488. | `gemini-3-pro-image-preview` | $0.134/image ≈ ¥1/image | 2K (default) |
  489. Get API Key: https://aistudio.google.com/apikey
  490. ## Contributing
  491. Contributions welcome (low-maintenance project):
  492. - Reproducible bug reports (input + output + steps + environment)
  493. - Documentation improvements
  494. - Small PRs (fixes/docs)
  495. > **Note:** Feature requests may not be acted on due to limited maintenance capacity.
  496. ## Acknowledgments
  497. This project builds upon these excellent tools:
  498. - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) - Anthropic's AI coding assistant
  499. - [Mermaid](https://mermaid.js.org/) - Diagramming and charting tool
  500. - [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli) - Command line interface for Mermaid
  501. - [Excalidraw](https://excalidraw.com/) - Virtual whiteboard for hand-drawn diagrams
  502. - [Playwright](https://playwright.dev/) - Browser automation (for Excalidraw PNG export)
  503. - [Gemini API](https://ai.google.dev/) - Google's image generation API
  504. - [Bun](https://bun.sh/) - Fast JavaScript runtime
  505. ## License
  506. MIT License - see [LICENSE](LICENSE) for details.
  507. ---
  508. ## Author
  509. **Axton Liu** - AI Educator & Creator
  510. - Website: [axtonliu.ai](https://www.axtonliu.ai)
  511. - YouTube: [@AxtonLiu](https://youtube.com/@AxtonLiu)
  512. - Twitter/X: [@axtonliu](https://twitter.com/axtonliu)
  513. ### Learn More
  514. - [MAPS™ AI Agent Course](https://www.axtonliu.ai/aiagent) - Systematic AI agent skills training
  515. - [Agent Skills Resource Library](https://www.axtonliu.ai/agent-skills) - Claude Code Skills collection and guides
  516. - [Claude Skills: A Systematic Guide](https://www.axtonliu.ai/newsletters/ai-2/posts/claude-agent-skills-maps-framework) - Complete methodology
  517. - [AI Elite Weekly Newsletter](https://www.axtonliu.ai/newsletters/ai-2) - Weekly AI insights
  518. - [Free AI Course](https://www.axtonliu.ai/axton-free-course) - Get started with AI
  519. ---
  520. MIT License © [Axton Liu](https://www.axtonliu.ai)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.