mage-article-illustrator

name	mage-article-illustrator
description	Analyzes article structure, identifies the positions that truly need visuals, and generates article illustrations with a Type × Style workflow. Use when users ask to illustrate an article, add images into article sections, generate visuals for an article, or 为文章配图.

Article Illustrator

Analyze articles, decide where illustrations are mandatory, and generate images with Type × Style consistency.

Reference Loading Guide

Keep SKILL.md lean and load reference files only when the current step needs them:

• Read references/config/preferences-schema.md only when creating, validating, or editing EXTEND.md.
• Read references/config/first-time-setup.md only when no preference file exists and setup must run.
• Read references/workflow.md only when executing the detailed step-by-step workflow or handling reference-image edge cases.
• Read references/usage.md only when the user needs command syntax, option reminders, or example invocations.
• Read references/prompt-construction.md only when creating or revising saved prompt files in prompts/.
• Read references/styles.md only when selecting or comparing styles.
• Read references/styles/<style>.md only for the specific styles that were selected, recommended, or need clarification.

Two Dimensions

Dimension	Controls	Examples
Type	Information structure	infographic, scene, flowchart, comparison, framework, timeline
Style	Visual aesthetics	notion, warm, minimal, blueprint, watercolor, elegant

Combine freely: --type infographic --style blueprint

Types

Type	Best For
infographic	Data, metrics, technical summaries
scene	Narratives, emotional
flowchart	Processes, workflows, route maps
comparison	Side-by-side, options
framework	Models, architecture, capability maps
timeline	History, evolution

Styles

See references/styles.md for Core Styles, full gallery, and Type × Style compatibility.

Default Generator Strategy

• Default image generator: mage-images-gen
• Normal text-to-image provider order: dashscope → seedream
• Reference-image provider order: google → openai → seedream
• Always save prompt files before generation; do not improvise inline prompts
• For text-heavy technical diagrams, prefer layout-first prompts with explicit text zones and exact visible copy
• For text fidelity issues, strengthen prompt structure first; do not immediately remove text or switch to textless diagrams

File Structure

Output directory follows default_output_dir in EXTEND.md:

• same-dir: {article-dir}/
• imgs-subdir: {article-dir}/imgs/
• illustrations-subdir: {article-dir}/illustrations/
• independent (default recommendation): illustrations/{topic-slug}/

<output-dir>/
├── source-{slug}.{ext}
├── references/              # if provided
│   ├── 01-ref-{slug}.{ext}
│   └── 01-ref-{slug}.md
├── outline.md
├── prompts/
│   └── NN-{type}-{slug}.md
└── NN-{type}-{slug}.png

Slug: 2-4 words, kebab-case. Conflict: append -YYYYMMDD-HHMMSS.

Workflow

Article Illustration Progress:
- [ ] Step 0: Check preferences (EXTEND.md) ⛔ BLOCKING
- [ ] Step 1: Pre-check references + determine output behavior
- [ ] Step 2: Analyze content
- [ ] Step 3: Confirm settings (AskUserQuestion)
- [ ] Step 4: Generate outline
- [ ] Step 5: Generate images with mage-images-gen
- [ ] Step 6: Finalize

Step 0: Load Preferences ⛔ BLOCKING

Check EXTEND.md existence (priority: project → user):

test -f .mage-skills/mage-article-illustrator/EXTEND.md && echo "project"
test -f "$HOME/.mage-skills/mage-article-illustrator/EXTEND.md" && echo "user"

Result	Action
Found	Read, parse, display summary
Not found	⛔ Run first-time-setup

CRITICAL: If no preference file exists, complete setup before asking other workflow questions.

Step 1: Pre-check

Detect and save reference images when the user provides them. Full procedures: references/workflow.md

Step 2: Analyze

Analysis	Output
Content type	Technical / Tutorial / Methodology / Narrative
Purpose	information / visualization / imagination
Core arguments	2-5 main points
Positions	Where illustrations are mandatory

Global illustration rule for all articles:

• require at least 1 illustration for each major chapter / H2 section
• if a chapter is too short for a full illustration, merge it with the nearest adjacent chapter and treat them as one illustrated unit only when the user explicitly approves
• treat missing chapter visuals as an incomplete outline, not as an optional aesthetic issue

For technical tutorials, system explainers, and methodology articles:

• default to per-section density or higher
• prefer summary diagrams, route maps, comparison boards, and architecture maps over decorative scene art
• each illustration should carry one clear takeaway, not just a single icon or concept

CRITICAL: Metaphors → visualize underlying concept, not the literal image.

Full procedures: references/workflow.md

Step 3: Confirm Settings ⚠️

ONE AskUserQuestion, max 4 questions. Q1-Q3 REQUIRED.

Q	Options
Q1: Type	[Recommended], infographic, scene, flowchart, comparison, framework, timeline, mixed
Q2: Density	minimal (1-2), balanced (3-5), per-section minimum (Recommended), rich (6+)
Q3: Style	[Recommended], minimal-flat, sci-fi, hand-drawn, editorial, scene, Other
Q4: Language	When article language differs from EXTEND.md

Full procedures: references/workflow.md

Step 4: Generate Outline

Save outline.md with frontmatter (type, density, style, image_count) and entries:

## Illustration 1
**Position**: [section/paragraph]
**Purpose**: [why]
**Visual Content**: [what]
**Filename**: 01-infographic-concept-name.png

Global outline default:

• each H2 section gets at least 1 planned visual
• do not approve outlines where any major chapter has no image plan

Technical summary default:

• each planned visual must declare one of these roles: summary-board, route-map, comparison, framework, step-flow, pitfall-checklist
• avoid creating multiple near-duplicate images that only rename one label

Full template: references/workflow.md

Step 5: Generate Images

⛔ BLOCKING: Prompt files must be saved before any image generation.

1. For each illustration, create a prompt file per references/prompt-construction.md
2. Save to prompts/NN-{type}-{slug}.md with YAML frontmatter
3. Prompts must use type-specific templates with structured sections (ZONES / LABELS / COLORS / STYLE / ASPECT)
4. LABELS must include article-specific data: actual numbers, terms, metrics, quotes
5. Do not pass ad-hoc inline prompts without saving prompt files first
6. Use mage-images-gen unless the user explicitly requests another image generation skill
7. Without references, prefer dashscope first, then seedream
8. With references, follow mage-images-gen ref-capable provider order: google → openai → seedream
9. Process references according to direct / style / palette
10. Apply watermark if EXTEND.md enables it
11. Generate from saved prompt files; retry once on failure with the next preferred provider for that mode

Text-heavy technical diagram rules:

• define exact visible text before generation; do not leave labels implied
• split visible copy into dedicated text zones such as title, node label, caption bar, or code card
• for technical diagrams, prefer clean printed sans-serif text rather than forcing handwritten lettering
• keep each label isolated; do not pack many unrelated phrases into one crowded block
• for command lines or long English strings, use dedicated wide code cards
• explicitly forbid extra words, random letters, pseudo-text, fake UI labels, and decorative micro-text
• for technical summary articles, include at least 2 of these information carriers in each image: summary bullets, stage labels, comparison criteria, route arrows, decision nodes, checklist items
• avoid "single-point diagrams" that show only one concept floating alone without upstream/downstream context
• when illustrating a chapter, make the image summarize the chapter's conclusion, not merely restate the section title

Full procedures: references/workflow.md

Step 6: Finalize

Insert ![description](path/NN-{type}-{slug}.png) after the corresponding paragraphs.

Article Illustration Complete!
Article: [path] | Type: [type] | Density: [level] | Style: [style]
Images: X/N generated
Location: [directory path]

Image Modification

Action	Steps
Edit	Update prompt → Regenerate → Update reference
Add	Position → Prompt → Generate → Update outline → Insert
Delete	Delete files → Remove reference → Update outline

Extension Support

Custom configuration is stored in EXTEND.md. Supported preferences: watermark, preferred style, language, output directory, and custom styles.

Schema: references/config/preferences-schema.md

References

File	Content
references/workflow.md	Detailed procedures
references/usage.md	Command syntax
references/styles.md	Style gallery
references/prompt-construction.md	Prompt templates
references/config/first-time-setup.md	First-time setup
references/config/preferences-schema.md	Preference schema