zhy-article-illustrator

Purpose

Automatically plan and generate illustrations for any Markdown article. This skill uses "high-polish editorial visuals" as the default global quality baseline: not simple illustrations, not decorative icon collages, nor low-information-density sketches. The system first generates a unified visual bible for the article, then creates structured prompts for each image, ensuring all illustrations in the same article share a consistent stylistic language, while adjusting composition, information focus, and layout based on chapter content.

It is prioritized to be compatible with the Gemini Nano Banana workflow by default, and uses the Xiaomi Gemini compatible interface by default; it also supports Gemini native proxy/relay mode and the official Gemini interface.

When to Use

User requests like "illustrate article", "add images to article"

Called in Step 6 of the

zhy-wechat-writing

skill (

with_illustrations=true

)

Users want to generate high-polish thematic visuals suitable for official account scenarios
Users want to upload local images to Qiniu Cloud to get CDN URLs

Prerequisites

The Markdown article file already exists
At least one available image generation channel is configured:
- Official Gemini direct connection:
```
GEMINI_API_KEY
```
  or
```
GOOGLE_API_KEY
```
- Gemini native proxy/relay:
```
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 (
```
QINIU_ACCESS_KEY
```
  /
```
QINIU_SECRET_KEY
```
  /
```
QINIU_BUCKET
```
  /
```
QINIU_DOMAIN
```
  in the
```
.env
```
  file at the skill root directory)

Workflow

Step 1: Analyze the Article

Goal: Understand the article structure, determine the number, positions, and expression methods of illustrations

Operations:

Read the full content of
```
article_path
```
Parse the article structure: title, chapter headings (
```
##
```
/
```
###
```
), number of paragraphs, positions of code blocks
Identify core information points:
- Key concepts/term explanations -> suitable for infographics
- Comparison/difference descriptions -> suitable for comparison charts
- Step/process descriptions -> suitable for flowcharts
- Architecture/framework descriptions -> suitable for architecture diagrams
- Data/statistics -> suitable for data visualizations
- Scene/narrative descriptions -> suitable for thematic illustrations or editorial scene images
Determine the illustration strategy based on
```
density
```
:
- ```
minimal
```
  : Only add illustrations for 1-2 core information points
- ```
balanced
```
  : Add one illustration for each major chapter at
```
##
```
  level
- ```
rich
```
  : Add one illustration every ~300 words or for each important paragraph
Determine the
```
slug
```
:
- If the user provides
```
slug
```
  : Use it directly
- Otherwise, derive a
```
kebab-case
```
  slug from the article's H1 title
Create the output directory:
```
{article_dir}/illustrations/{slug}/
```

Output: Article structure analysis results, list of illustration positions

Step 2: Generate Visual Bible and Illustration Plan

Goal: Establish a unified visual baseline for the entire article, and generate planning information for each illustration

Operations:

First generate the article-level

visual_bible

and save it to

{article_dir}/illustrations/{slug}/visual-bible.md

The
```
visual_bible
```
must cover:
- ```
quality_baseline
```
  : Uniformly adopt high-polish editorial visual/thematic illustration standards
- ```
visual_theme
```
  : Overall style direction of this article
- ```
color_system
```
  : Primary color, secondary color, accent color, background tendency
- ```
graphic_language
```
  : Graphic style, lines/materials/lighting, information hierarchy methods
- ```
layout_discipline
```
  : Page white space, module density, rhythm between title area and content area
- ```
text_policy
```
  : Simplified Chinese by default; only terms in the
```
english_terms_whitelist
```
  retain English
- ```
negative_rules
```
  : Prohibit simple drawings, childish cartoons, meaningless decorations, garbled English, random style mixing
Then generate outline entries for each illustration position, which must include at least:
- ```
position
```
  : Insertion position (after which chapter/paragraph)
- ```
purpose
```
  : What information this image needs to convey
- ```
image_type
```
  : Comparison chart / Flowchart / Architecture diagram / Data visualization / Scene image / Editorial thematic visual
- ```
core_message
```
  : The unique core expression of this image
- ```
content_blocks
```
  : Content blocks that must appear in the frame
- ```
text_blocks
```
  : Titles, labels, annotations needed in the image (Simplified Chinese by default)
- ```
english_terms_used
```
  : Subset of English terms allowed in this image
- ```
layout_hint
```
  : Layout direction and information partitioning
- ```
filename
```
  : Output filename (format:
```
NN-brief-description.png
```
  )
- ```
alt_text
```
  : Alt text for Markdown images

Save to

{article_dir}/illustrations/{slug}/outline.md

Simultaneously generate independent prompt files for each image, saved to
```
{article_dir}/illustrations/{slug}/prompts/
```

outline.md Format:

yaml

---
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: Generate high-quality image files based on

visual_bible

+ outline

Operations:

Construct structured prompts for each image, which must inherit:
- Global quality baseline: High-polish editorial visuals, not simple drawings
- Article-level
```
visual_bible
```
- Single-image content plan
The prompt must include the following layers:
- ```
Task Positioning
```
  : This is a finished thematic visual directly usable in official account articles
- ```
Style Anchor
```
  : Reuse the unified visual language of this article
- ```
Main Subject
```
  : Core objects, information modules, foreground-middle-ground-background relationships
- ```
Layout Structure
```
  : Organization method of title area, content area, comparison area, process area, data area
- ```
Information Hierarchy
```
  : Priority of main title, secondary labels, supplementary explanations
- ```
Text Rules
```
  : All visible text uses Simplified Chinese by default; only whitelisted terms retain English
- ```
Quality Requirements
```
  : Rich details, clear hierarchy, strong layout sense, avoid template-like effects
- ```
Prohibited Items
```
  : Childish style, vague content, overly decorative, meaningless icon stacking, garbled English
For Nano Banana / Gemini-like models, prioritize optimizing the following features:
- Complete frame information, clear instructions, specific elements
- Text display should be as short and accurate as possible, avoid long paragraphs of explanatory text
- All images in the same article share the same color system, graphic language, and polish level
- Images should look like editorial thematic visuals rather than ordinary illustrations

Save all prompts to the

{article_dir}/illustrations/{slug}/prompts/

Step 4: Upload to Image Hosting (Optional)

Trigger Condition:

upload=true

Goal: Upload generated images to Qiniu Cloud to obtain CDN URLs

Operations:

Check Qiniu Cloud configuration: Read the
```
.env
```
file at the skill root directory

Call the upload script:

bash

bun run scripts/qiniu-upload.ts --file <local path> --key <remote path>

Remote key format:
```
illustrations/{slug}/{filename}
```
Upload one by one, record the CDN URL of each image
If upload fails, retain 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
```
to
```
article.illustrated.md
```
(same directory)
Insert image references at each position specified in the outline:
- If uploaded (has CDN URL):
```
![alt_text](CDN_URL)
```
- If not uploaded:
```
![alt_text](illustrations/{slug}/{filename})
```
For images that failed to generate, insert a placeholder comment:
markdown
```

```
Output completion summary:
- ```
illustrated_article_path
```
- Statistics of success / failure / upload
- List of failed images and reasons

Output:

illustrated_article_path

Data Flow

text

article.md
    |
    v
Step 1: Analyze article structure -> List of illustration positions
    |
    v
Step 2: Generate visual-bible.md + outline.md
    |
    v
Step 3: Generate structured prompts -> illustrations/{slug}/*.png
    |
    v
Step 4: (--upload) Upload to Qiniu Cloud -> CDN URLs
    |
    v
Step 5: Insert into copy -> article.illustrated.md

Error Handling

Failure Scenario	Handling Method
Article file does not exist	Report error and exit immediately
Gemini / proxy configuration missing	Prompt the user to configure `IMAGE_PROVIDER` , `IMAGE_API_KEY` , optional `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 `XIAOMI_BASE_URL` / `XIAOMI_IMAGE_SIZE` as needed
Single image generation failed	Retry once; if still failed, record and skip, proceed to the next one
Poor effect due to excessive text	Retry after simplifying the length of titles/labels/annotations
Qiniu Cloud configuration missing	Prompt the user to configure the `.env` file at the skill root directory, skip the upload step
Qiniu Cloud upload failed	Retain local path, record error, proceed to the next image
Slug directory already exists	Use it directly (overwrite files with the same name)

Example Usage

Default Nano Banana style illustrations:

yaml

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 Gemini native proxy:

yaml

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 Xiaomi Gemini compatible interface:

yaml

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:

yaml

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

Notes

The global quality baseline is fixed as high-polish editorial visuals, no simple decorative images are generated
Different articles can have different visual styles, but the same article must share a unified style system
All visible text uses Simplified Chinese by default; only whitelisted terms retain English
Always create a copy (
```
article.illustrated.md
```
), do not modify the original article
Image references force the use of relative paths and
```
/
```
separators (local mode)
Prompts are saved to the
```
prompts/
```
directory for easy tracing and re-generation after manual adjustment

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, image 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
```
; the open-source repository does not preset any private relay addresses

zhy-article-illustrator

NPX Install

Tags

SKILL.md Content (Chinese)

zhy-article-illustrator

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 to Image Hosting (Optional)

Step 5: Insert into Article Copy

Data Flow

Error Handling

Example Usage

Notes