Article Illustrator

MCP Tools

Generate multiple illustrations for an article with structured type and style decisions and bundled generation tooling. Use when the user asks to create illustrations for an article, add images to a post, or generate visuals for sections of a long text.

Install

openclaw skills install article-illustrator-2

Article Illustration (`article-illustrator`)

Reference Images (Important)

If you use reference images (image-to-image / series reference / consistency refs):

Reference images must be public URLs.
HTTPS is strongly recommended.
http:// may work but is insecure and can be blocked by some networks.
Local file paths and data: URLs are not supported by the WeryAI gateway.

Generate multiple illustrations for an article, add images to a post, or generate visuals for sections of a long text — with structured type and style decisions and automatic Markdown insertion.

This article illustration workflow analyzes long-form content, identifies the best illustration positions, generates multiple coordinated images, and can insert those image references back into the article Markdown. Use it when you need to create illustrations for an article, add images to a post, or generate visuals for sections of a long text.

Important: keep the article structure readable, preserve the author's section flow, and only add illustrations where they clarify or strengthen the post.

Scripts:

scripts/scaffold.ts
scripts/build-prompts.ts
scripts/build-batch.ts
scripts/insert-images.ts

Safety & Scope

Network: This skill calls the WeryAI gateway over HTTPS (https://api.weryai.com).
Auth: Uses IMAGE_GEN_API_KEY. The key is never printed. It may be persisted only when you explicitly run npm run setup -- --persist-api-key.
Reference images: Must be public URLs (https:// recommended). http:// may work but is insecure. Local file paths and data: URLs are rejected.
No arbitrary shell: The generation runtime does not execute arbitrary shell commands.
Files written: Output images and optional local config under .image-skills/article-illustrator/ (project) and/or ~/.image-skills/article-illustrator/ (home).

Use Cases

add illustrations to article sections
create visuals for tutorials, methods, reviews, and explainers
keep multiple article images visually consistent

Not a good fit for:

a single cover image
a dense one-page infographic
a sequential comic narrative

Example Prompts

Illustrate my article about habit systems with minimal editorial images
Add visuals to each section of this tutorial post
Generate 4 illustrations for my review article in watercolor style

Core Dimensions

type: what the illustration is doing
style: the visual language

See:

Commands

Script	Purpose
`scripts/scaffold.ts`	Initialize `outline.md` and per-illustration prompts
`scripts/build-prompts.ts`	Regenerate prompts from `outline.md`
`scripts/build-batch.ts`	Generate `batch.json` from illustration prompts
`scripts/insert-images.ts`	Insert image references into article Markdown
`scripts/illustrate-article.mjs`	Run the recommended end-to-end article illustration workflow
`npm run generate`	Generate illustrations
`./scripts/vendor/compression-runtime/scripts/main.ts`	Compress output for delivery

Workflow

Recommended Default Workflow

For normal use, prefer the high-level orchestrator. It keeps outline.md, prompts, batch.json, and generated images on disk for inspection, but runs the full workflow for you:

node {baseDir}/scripts/illustrate-article.mjs \
  --article article.md \
  --output-dir illustrations/topic-slug \
  --project "$(pwd)"

This default path runs:

ensure-ready
scaffold --article
build-prompts
build-batch
generate
insert-images

Use the lower-level commands below when you want to inspect or customize each stage manually.

Step 1: Initialize `outline.md` and Prompt Files

Create the working directory:

${BUN_X} {baseDir}/scripts/scaffold.ts \
  --article article.md \
  --output-dir illustrations/topic-slug \
  --topic "Habit systems" \
  --style minimal \
  --density per-section \
  --lang en \
  --illustrations 3

This creates:

outline.md
prompts/01-framework-topic.md
prompts/02-flowchart-topic.md
prompts/03-summary-topic.md

When --article is provided, outline.md now prefers real Markdown headings from the article and generates Position entries such as after-heading: Why Habit Systems Work. It only falls back to placeholder headings when the article does not provide enough usable headings.

Step 2: Analyze the Article

Extract:

content type: technical, tutorial, narrative, methodology, review
2 to 5 core arguments
where illustrations add the most value
whether each image should explain, visualize structure, or set tone
the user's language, especially if labels or section text appear in the image

Step 3: Choose `type`, `style`, and `density`

Default priorities:

type: mixed
style: minimal
density: per-section

Recommended rules:

technical explanation -> framework or infographic
process explanation -> flowchart
comparative review -> comparison
historical development -> timeline
emotional or narrative writing -> scene

Step 4: Map to the Bundled Runtime

The bundled image runtime currently exposes one structured visual argument, --style, so:

map style to --style
write type, density, and section purpose into the prompt body
prefer batch generation when there are multiple illustrations

Recommended mapping:

illustrator style	runtime `--style`
`minimal`	`editorial`
`notion`	`flat-illustration`
`blueprint`	`infographic`
`watercolor`	`watercolor`
`elegant`	`editorial`
`poster`	`poster`

Step 5: Refine `outline.md`, Then Build Prompts

Save at least:

outline.md
prompts/01-framework-topic.md
prompts/02-scene-topic.md

Each outline entry should include:

Position
Purpose
Visual Content
Filename

Recommended Position syntax:

after-heading: <heading>
before-heading: <heading>
after-text: <snippet>
end

When the outline is ready, generate prompt files automatically:

${BUN_X} {baseDir}/scripts/build-prompts.ts \
  --outline illustrations/topic-slug/outline.md \
  --output-dir illustrations/topic-slug/prompts \
  --topic "Habit systems" \
  --audience "general reader" \
  --style minimal \
  --density per-section \
  --lang en \
  --aspect 16:9

This converts each outline entry into a prompt file such as 01-framework-topic.md or 02-flowchart-topic.md.

Consistency strategy for multi-illustration articles:

create one canonical references/series-reference.png first
treat that image as the source of truth for palette, recurring subject, diagram vocabulary, and composition rhythm
reuse the same shared reference for every illustration task
keep illustration-specific continuity anchors plus previous/next-section context in every prompt
if the shared reference image is missing, do not proceed to final batch generation yet

Step 6: Generate the Shared Series Reference First

Before building the final illustration batch, generate the canonical series reference image:

${BUN_X} {baseDir}/npm run generate \
  --promptfiles illustrations/topic-slug/references/series-reference.md \
  --style minimal \
  --image illustrations/topic-slug/references/series-reference.png \
  --ar 16:9 \
  -m "$M"

This step is the default for multi-illustration articles. Do not skip it when consistency matters.

Step 7: Build `batch.json` and Generate Images

Build a batch file from the outline and prompt directory:

${BUN_X} {baseDir}/scripts/build-batch.ts \
  --outline illustrations/topic-slug/outline.md \
  --prompts illustrations/topic-slug/prompts \
  --output illustrations/topic-slug/batch.json \
  --images-dir illustrations/topic-slug \
  --model "$M"

Then run the bundled image generator:

On first use in a new project, run npm run ensure-ready -- --project <your-project> --workflow article from this skill directory before generation. This reads the doctor report and auto-runs bootstrap if local script dependencies are still missing. If the report shows a missing IMAGE_GEN_API_KEY and the user approves, run npm run setup -- --project <your-project> --workflow article --persist-api-key when the key is already in env, or persist it to .image-skills/article-illustrator/.env on the user's behalf, then continue without leaving this workflow.

When this skill is first connected, tell the user that the default generation model is Nano Banana 2 (GEMINI_3_1_FLASH_IMAGE). Also tell them it can be switched later whenever another model fits the task better.

${BUN_X} {baseDir}/npm run generate --batchfile illustrations/topic-slug/batch.json --json

The bundled generator now uses stability-first batch defaults and safer retry/backoff behavior for rate-limit-like failures. It retries submit failures conservatively, retries status polling without blindly resubmitting the same task, and keeps the initial concurrency biased toward reliability over speed.

If only one illustration is needed, a single direct call is still fine.

Step 8: Insert Images Back into Markdown

After the images are generated, insert references into the article:

${BUN_X} {baseDir}/scripts/insert-images.ts \
  --article article.md \
  --outline illustrations/topic-slug/outline.md \
  --images-dir illustrations/topic-slug

If you do not want to overwrite the original file:

${BUN_X} {baseDir}/scripts/insert-images.ts \
  --article article.md \
  --outline illustrations/topic-slug/outline.md \
  --images-dir illustrations/topic-slug \
  --output article.with-images.md

Default behavior:

if --output is omitted, the original Markdown is backed up first and then updated in place
image insertion follows Position and Filename from outline.md
if the same image path is already referenced, that entry is skipped
missing headings are recoverable by default: --on-missing-anchor end appends the image at the end and reports it in the summary
the command prints a summary so you can see exact inserts vs fallback/skipped/failed entries

Output Convention

Suggested output directory:

illustrations/<topic-slug>/

Suggested minimum files:

outline.md
batch.json
prompts/NN-type-slug.md
NN-type-slug.png
the updated article Markdown

Definition of Done

outline.md and per-illustration prompt files exist in the output directory.
All illustrations are generated and shown alongside their article sections.
The article Markdown is updated with image references via insert-images.ts.
Illustration count, style, and model are stated in the delivery summary.
A compressed webp set is produced for delivery.

Iteration

When the user wants changes after seeing generated illustrations:

Style mismatch ("inconsistent style", "change the style") → change style / --style for all illustrations, rebuild batch, re-generate. Ask if all or specific ones.
Wrong illustration type ("this one should be a flowchart, not a scene") → update the type in outline.md for that entry, rebuild its prompt, re-generate only that image.
Position wrong ("this image should be after that paragraph") → update Position in outline.md, re-run insert-images.ts.
Too many/few illustrations → adjust outline.md, add or remove entries, rebuild affected prompts.
Single image redo → re-generate only that image with --promptfiles prompts/NN-type-slug.md. Keep other images.

After any changes, re-run insert-images.ts to update the article Markdown.

Delivery

When the illustrations are ready:

Show each illustration directly alongside the section it belongs to. Do not just list file paths.
Briefly state: illustration count, style, density.
Confirm the article Markdown has been updated with image references.
Ask if any illustrations need changes or if the user is satisfied.
Auto-compress: once confirmed, run the bundled compression runtime on the illustrations directory for web-optimized versions.

${BUN_X} {baseDir}/./scripts/vendor/compression-runtime/scripts/main.ts illustrations/topic-slug/ -r -f webp -q 80

Internal checklist (for agent): illustration count, type / style / density, model, insert-images status, compression done.

Current Scope

This version of article-illustrator focuses on:

article analysis
illustration planning
prompt and batch organization
automatic Markdown image insertion