article-illustrator

article-illustrator

Purpose

Automatically plan and generate illustrations for any Markdown article. By default, the skill uses "high-completion editorial visuals" as the global quality baseline: not simple illustrations, not decorative icon collages, and not low-information-density sketches. The system first generates a unified visual bible for the article, then generates structured prompts for each image, so that illustrations for the same article share a unified style language, while adjusting composition, information focus, and layout according to the section content.

By default, prioritize compatibility with the Gemini Nano Banana workflow, and by default use the Xiaomi Gemini-compatible interface; it also supports Gemini native proxy / relay station mode and the official Gemini interface.

When to Use

User requests "illustrate an article", "illustrate article", "add images to article"
wechat-writing Skill Step 6 call (with_illustrations=true）
User wants to generate a high-completion feature visual more suitable for a WeChat Official Account scenario
User wants to upload local images to Qiniu Cloud to obtain a CDN URL

Prerequisites

The article Markdown file already exists
At least one usable image generation channel has been configured:
- Official Gemini direct connection:GEMINI_API_KEY or GOOGLE_API_KEY
- Gemini native proxy / relay station:IMAGE_PROVIDER=gemini、IMAGE_API_KEY, optional IMAGE_BASE_URL
- Xiaomi Gemini-compatible interface:IMAGE_PROVIDER=xiaomi or XIAOMI_API_KEY, optional XIAOMI_BASE_URL
- If upload is enabled: Qiniu Cloud configuration is ready (skill root directory .env in the QINIU_ACCESS_KEY / QINIU_SECRET_KEY / QINIU_BUCKET / QINIU_DOMAIN）

Workflow

Step 1: Analyze the article

Objective: Understand the article structure and determine the number, placement, and expression method of illustrations

Operations：

Read article_path 's full content
Parse the article structure: title, section headings (## / ###), number of paragraphs, code block positions
Identify core information points:
- Key concepts / terminology explanations -> suitable for infographics
- Comparisons / difference descriptions -> suitable for comparison charts
- Steps / process descriptions -> suitable for flowcharts
- Architecture / framework descriptions -> suitable for architecture diagrams
- Data / statistics -> suitable for data visualization
- Scenes / narrative descriptions -> suitable for feature illustrations or editorial scene images
Based on density determine the illustration strategy:
- minimal: Illustrate only the 1-2 most core information points
- balanced: For each ## -level main section, create one image
- rich: Create one image about every 300 words or for each important paragraph
Determine slug：
- If the user provides slug: use it directly
- Otherwise derive from the article H1 title kebab-case
Create output directory:{article_dir}/illustrations/{slug}/

Output: Article structure analysis results, illustration placement list

Step 2: Generate visual bible and illustration plan

Objective: Establish a unified visual baseline for the entire article and generate planning information for each image

Operations：

First generate the article-level visual_bible, save to {article_dir}/illustrations/{slug}/visual-bible.md
visual_bible must cover:
- quality_baseline: Uniformly adopt high-completion editorial visual / feature illustration standards
- visual_theme: The overall style direction of this article
- color_system: Primary color, secondary color, accent color, background tendency
- graphic_language: Graphic language, lines/materials/lighting, information hierarchy method
- layout_discipline：Page whitespace, module density, rhythm between title area and content area
- text_policy：Default Simplified Chinese; only english_terms_whitelist terms in retain English
- negative_rules：No simple drawings, childish cartoons, meaningless decorations, garbled English, or random mixed styles
Then generate an outline entry for each illustration position, containing at least:
- position：Insertion position (after which chapter/paragraph)
- purpose：What information this image should convey
- image_type：Comparison diagram / flowchart / architecture diagram / data chart / scene image / editorial feature visual
- core_message：The single core expression of this image
- content_blocks：Content blocks that must appear in the image
- text_blocks：Titles, labels, and annotations that need to appear in the image (Simplified Chinese by default)
- english_terms_used：The subset of English terms allowed to appear in this image
- layout_hint：Layout direction and information zoning
- filename：Output filename (format:NN-简短描述.png）
- alt_text：Alt text for the Markdown image
Save to {article_dir}/illustrations/{slug}/outline.md
At the same time, generate an independent prompt file for each image, save to {article_dir}/illustrations/{slug}/prompts/

outline.md format：

---
article: <article_path>
slug: <slug>
density: <density>
aspect_ratio: <ratio>
prompt_profile: <profile>
text_language: <language>
image_provider: <provider>
image_model: <model>
image_count: <N>
generated_at: <ISO timestamp>
---

Output：visual_bible_path、outline_path

Step 3: Generate images

Goal：Based on visual_bible + outline, generate high-quality image files

Operations：

Build a structured prompt for each image; the prompt must simultaneously inherit:
- Global quality baseline: high-completion editorial visuals, not simple drawings
- Article-level visual_bible
- Single-image content planning
The prompt must include the following layers:
- 任务定位：This is a finished-product-level feature visual that can be used directly in a WeChat official account article
- 风格锚点：Reuse the unified visual language of this article
- 画面主体：Core objects, information modules, foreground/midground/background relationships
- 版式结构：The organization of the title area, content area, comparison area, process area, and data area
- 信息层级：Priority of the main title, secondary labels, and supplementary explanations
- 文字规则：By default, all visible text uses Simplified Chinese; only whitelisted terms retain English
- 质量要求：Rich details, clear hierarchy, strong layout sense, avoid template feel
- 禁止项：Childish, vague, overly decorative, meaningless icon stacking, garbled English
For Nano Banana / Gemini-type models, prioritize optimizing the following features:
- Complete image information, clear instructions, specific elements
- Keep text display as short and accurate as possible; avoid long explanatory text
- Every image in the same article shares a unified color scheme, unified graphic language, and unified level of completion
- Images should look more like editorial feature visuals, not ordinary illustrations
Save all prompts to {article_dir}/illustrations/{slug}/prompts/ directory
Call this skill's built-in script to generate images:
- Script path:scripts/image-gen.ts
- Parameters:--prompt "<提示词内容>" --output "<输出路径>" --ar <宽高比>
- Optional:--provider gemini|google|xiaomi|openai
- Optional:--model <模型名>
- Optional:--base-url <Gemini 原生代理基础地址>
- Optional:--api-key <临时 key>
- Optional:--image-size <清晰度/尺寸标识>(e.g., Xiaomi's 1K）
- Optional:--ref <参考图路径>(Gemini multimodal scenario)
- Parallel generation：A maximum of 4 concurrent is recommended
If you need one-click completion of planning + image generation + insertion back into the article, you can directly call:
```
node scripts/illustrate-article.ts --article <article.md>
```
- If using the Xiaomi Gemini compatible interface, you may add:--image-provider xiaomi --image-model gemini-3-pro-image-preview --image-size 1K
Failure handling:
- Single failure -> retry once, you may fine-tune the layout, text density, or prohibited items in the prompt
- Still failing -> record it in the failure list, continue to the next one
- Do not interrupt the overall process

Output: image file list, failure list

Step 4: Upload images to image hosting (optional)

Trigger condition：upload=true

Goal: upload the generated images to Qiniu Cloud and obtain CDN URLs

Operations：

Check Qiniu Cloud configuration: read the skill root directory .env

Call the upload script:

bun run scripts/qiniu-upload.ts --file <本地路径> --key <远程路径>

Remote key format:illustrations/{slug}/{filename}
Upload one by one, recording each image's CDN URL
If upload fails, keep the local path and do not interrupt the process

Output：uploaded_urls list (CDN URL or null）

Step 5: Insert into article copy

Goal: create an article copy with image references

Operations：

Copy article_path as article.illustrated.md(same directory)
Insert an image reference at each position specified in the outline:
- If already uploaded (has a CDN URL):![alt_text](CDN_URL)
- If not uploaded:![alt_text](illustrations/{slug}/{filename})
For images that failed to generate, insert a placeholder comment:
```

```
Output a completion summary:
- illustrated_article_path
- Success / failure / upload statistics
- List of failed images and reasons

Output：illustrated_article_path

Data Flow

article.md
    |
    v
Step 1: 分析文章结构 -> 配图位置列表
    |
    v
Step 2: 生成 visual-bible.md + outline.md
    |
    v
Step 3: 生成结构化 prompts -> illustrations/{slug}/*.png
    |
    v
Step 4: (--upload) 上传七牛云 -> CDN URLs
    |
    v
Step 5: 插入副本 -> article.illustrated.md

Error Handling

Failure scenario	Handling method
Article file does not exist	Report an error immediately and exit
Gemini / proxy configuration missing	Prompt the user to configure `IMAGE_PROVIDER`、`IMAGE_API_KEY`, optionally `IMAGE_BASE_URL`, or fall back to the official `GEMINI_API_KEY`
Xiaomi interface configuration missing	Prompt the user to configure `IMAGE_PROVIDER=xiaomi` or `XIAOMI_API_KEY`, and set as needed `XIAOMI_BASE_URL` / `XIAOMI_IMAGE_SIZE`
Single image generation failed	Retry once; if it still fails, record and skip, then continue to the next one
Poor results due to too much text	Simplify the title/tag/annotation length and retry
Qiniu Cloud configuration missing	Prompt the user to configure the skill root directory `.env`, skip the upload step
Qiniu Cloud upload failed	Keep the local path, record the error, continue to the next one
slug directory already exists	Use it directly (overwrite files with the same name)

Example Usage

Default Nano Banana style illustration：

article_path: articles/playwright-introduction/article.md
density: balanced
prompt_profile: nano-banana
text_language: zh-CN
image_provider: xiaomi
image_model: gemini-3.1-flash-image-preview
image_base_url: https://your-compatible-endpoint.example/v1beta
image_size: 1K
upload: false

Generate images via the Gemini native proxy：

article_path: articles/playwright-introduction/article.md
density: balanced
image_provider: gemini
image_model: gemini-3.1-flash-image-preview
image_base_url: https://your-relay.example.com/v1beta
upload: false

Generate images via the Xiaomi Gemini compatible interface：

article_path: articles/playwright-introduction/article.md
density: balanced
image_provider: xiaomi
image_model: gemini-3.1-flash-image-preview
image_base_url: https://your-compatible-endpoint.example/v1beta
image_size: 1K
upload: false

Specify English whitelist terms：

article_path: articles/playwright-introduction/article.md
english_terms_whitelist:
  - Playwright
  - Chromium
  - Firefox
  - WebKit

Notes

The global quality baseline is fixed at high-completion editorial visuals; do not generate simple decorative images
Different articles may have different visual styles, but the same article must share a unified style system
By default, all visible text uses Simplified Chinese; only whitelist terms remain in English
Always create a copy (article.illustrated.md), do not modify the original text
Image references must use relative paths and the / separator (local mode)
Save the prompt to prompts/ Directory, for traceability and regeneration after manual adjustments
You can use bun run scripts/plan-illustrations.ts --article <article.md> to automatically generate visual-bible.md、outline.md and prompts/
You can use node scripts/illustrate-article.ts --article <article.md> to complete planning, diagram generation, and article.illustrated.md generation in one click
Xiaomi/Gemini compatible interfaces can be configured via image_provider=xiaomi and custom image_base_url configuration; the open-source repository does not preset any private relay address

About this skill

Purpose

When to Use

Prerequisites

Workflow

Step 1: Analyze the article

Step 2: Generate visual bible and illustration plan

Step 3: Generate images

Step 4: Upload images to image hosting (optional)

Step 5: Insert into article copy

Data Flow

Error Handling

Example Usage

Notes