Claude Cursor Skill

illo

Creates original editorial illustrations where a recurring mascot character performs the idea — one caught scene by default, a hand-built explainer diagram (labeled stages, a fan-out, timeline, loop, or stack) when the structure itself is the point, or a transparent character cut

LLM Mart · 0 points · 66 views 218 listing impressions 0 install-command copies

#image-generation

Download tmchow-illo-skill-skills_illo-0b0abee.zip · 452 KB

Install

skills CLI npx skills add https://github.com/tmchow/illo-skill/tree/main/skills/illo
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install tmchow-illo-skill@llmmart
Git git clone https://github.com/tmchow/illo-skill.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole tmchow/illo-skill collection as a plugin from our marketplace. Git is the plain clone.

README

Illo

illo-skill.com — live examples, character packs, and copy-paste installs. This file is the developer reference (engines, models, cost, API keys).

Turn a concept or an article into original editorial illustrations — flat, bold-lined print-style scenes where a recurring mascot performs the idea. One image says one thing: a key judgment, a flow, a before/after, a trap. It's a deliberate house style, not a generic image generator — closer to a smart, deadpan print zine than to clip art or an infographic.

The methodology is the constant; the character pack and palette are yours to set — and every character pack carries its own print style. Out of the box the mascot is Blot, a deadpan ink-drop in risograph. A built-in character builder designs your own mascot with you (interview — including picking its look from the bundled library of seventeen (below) — then model-sheet candidates → pick → install). Want the same character in another look? Build a style variant pack (blot-woodcut): one pack, one look, so a catalog of characters never turns into a grid of combinations. Palettes stay per-image and resolve by destination: a character defines where its accent lives, never the color. One plain-text line in your palettes file — blog → notes — and anything headed for your blog automatically wears notes, a palette built once by copying your site's real CSS colors into hexes (background → paper, text → ink, link color → accent; re-extract only if you rebrand). Same mascot, fluoro pink on X, your blog's exact orange on the blog — never asked twice. Or pick a named preset, or hand it one brand color and let it derive the rest.

Blot — the default mascot

Invoking: the skill answers to its name — say "illo" ("illo this post", "use illo: draw blip hauling a crate"). It deliberately won't hijack generic requests like "illustrate this post", and it can't know your installed characters' names up front — lead with "illo", then talk characters freely.

Same character, different voice — the bundled woodcut style telling a three-panel story:

Woodcut mini-comic example

And the day job — compressing an abstract concept into one scene that lands in about a second. Hand it "we replatform with zero downtime" and you get the bridge being rebuilt under live traffic:

Zero downtime — rebuilding the bridge under live traffic

One idea per image, the mascot performing the move rather than decorating it, a few short hand-lettered labels — every render is held to that bar, and off-model results get re-rolled before you see them.

Looks

Every character pack picks exactly one look from the bundled library:

Look The voice
riso Grainy halftone risograph — the house default
blueprint White draftsman linework on deep blueprint blue
woodcut Heavy carved relief print on warm cream
pixel Chunky 4-color pixel art
clay Matte stop-motion plasticine diorama
manila Rubber-stamped ink on office manila paper
chalk Dusty chalk on a deep slate board
phosphor Glowing CRT trace on near-black glass
enamel Hard-enamel pin cells with raised metal lines
gouache Flat matte mid-century poster paint
felt Layered hand-cut wool-felt craft
diorama Watercolor-and-ink storybook tabletop diorama
sketchbook Vintage sepia pencil-and-ink editorial sketch
bricks Photoreal toy-brick set — the one photographic look
fizz Psychedelic soda-pop skate-sticker screenprint
bloom Flat cel character in a soft, atmospherically-lit cozy scene
snes 16-bit console sprite editorial with soft dither and game-world staging

Looks are shared infrastructure, deliberately separate from characters: the definitions live in this skill (references/styles/), and a character pack just names one — so a fix to a look immediately improves every pack that uses it, and adding a character never requires touching the skill. Want a look that doesn't exist? Drop a custom style file in ~/.config/illo/styles/<name>.md and use it right away — and if it proves out, PR it into the library here so packs everywhere can reference it.

Prerequisites

Images are generated by a small bundled script (scripts/illo.py) through one of three engine backends — python3 (standard library only, macOS/Linux) and network access are the only hard requirements. In Grok Bot (Cursor's Grok Bot / the Grok desktop assistant), illo instead uses Grok Bot's built-in Grok image tool as an agent-side transport when no engine backend is explicitly configured:

  • Codex (free for Codex subscribers). If you already have the Codex CLI installed and logged in (codex login), illo can generate through your Codex subscription at no per-image charge — it draws on your Codex usage quota instead. No API key and no token: illo only shells out to your own CLI. Detected automatically; gpt-image-2 is the model (no model selection); unsupported on Windows/WSL.
  • Grok (free for Grok/xAI subscribers). If you have the Grok CLI installed and logged in (grok login), illo can generate through your Grok subscription via its built-in image tool, drawing on your Grok usage quota — same key-free, token-free design as Codex. Handy when illo runs inside the Grok agent. Two limits: no model selection, and no transparent cutouts (Grok returns JPEG with no alpha) — cutouts auto-fall back to Codex or OpenRouter.
  • Grok Bot native (agent-side). In Cursor's Grok Bot / the Grok desktop assistant, the skill instructions route generation to Grok Bot's own built-in Grok image tool with the character sheet attached as a reference. This is not the Grok CLI lane and not a generic host-image-tool fallback: no grok binary, Codex CLI, or OpenRouter key is required unless you explicitly choose one of the engine backends.
  • OpenRouter (paid, direct or explicit fallback). An OpenRouter API key lets illo call OpenRouter's image API directly — the engine path on a host without a subscription CLI. Model-selectable — see Models & cost below. A failed Codex/Grok CLI render never spends money automatically: pass --allow-paid-fallback to explicitly permit that pay-per-image retry. Intentional cutout routing remains automatic.

Setting the key (OpenRouter path)

For the OpenRouter backend, bootstrap the config file once — you type the key at a hidden prompt, and nothing else ever reads or stores it. (The Codex, Grok CLI, and Grok Bot native paths need no OpenRouter key; init offers CLI backends when a usable CLI is detected.)

python3 scripts/illo.py init                  # prompts for the key (hidden),
                                              # writes ~/.config/illo/config.yaml (mode 600)
python3 scripts/illo.py doctor                # check readiness

The config file is the only place the engine reads the key from — deliberately: no environment variables (skill security scanners treat secret-shaped env reads in community skills as exfiltration) and no --api-key-style flags (command-line secrets leak into process listings and shell history). The config (a commented config.yaml) also holds non-secret defaults — model, defaultPalette, defaultCharacter, aspect, and an optional watermark map for attribution. There is no built-in watermark; set your own so it's only ever yours:

python3 scripts/illo.py init --no-key \
  --watermark blog=yoursite.com --watermark x=@yourhandle

The config file is read via PyYAML when installed (python -m pip install 'PyYAML==6.0.2'); without it a minimal built-in parser still reads the flat keys (apiKey, model, …) — only nested settings like watermark need PyYAML. Either way, image generation itself needs no installs.

Cloud & CI environments

In ephemeral workspaces (Claude Code on the web, Codex cloud, GitHub Actions, devcontainers) there's no interactive prompt and the home directory doesn't persist — there, use the platform's own secrets mechanism: add OPENROUTER_API_KEY to the environment's secrets, and materialize the config in the environment's setup hook (Codex environment setup script, devcontainer postCreateCommand, a CI step):

mkdir -p ~/.config/illo
printf 'apiKey: "%s"\n' "$OPENROUTER_API_KEY" > ~/.config/illo/config.yaml
chmod 600 ~/.config/illo/config.yaml

The key stays in the platform's secret store; each fresh workspace gets its config rebuilt at setup time, and the engine still reads only its own file. Adding the secret to the environment is the consent — it's scoped to that workspace and provisioned by you, deliberately, for the tools running there.

Models & cost

Cost depends on the transport. On Codex, Grok CLI, and Grok Bot native there is no per-image charge — generation runs on your Codex or Grok subscription and draws on that quota (image turns consume it faster than text turns), and the image model is automatic (no model selection). On the OpenRouter backend generation is pay-per-image through your OpenRouter account — typically under ten cents per image, and a typical blog post (3–6 finals plus a few re-rolls) lands well under a dollar on the default model. Prices are OpenRouter's and drift — check openrouter.ai/models for current numbers. The model table below applies to the OpenRouter backend.

Model Why you'd pick it Relative cost
Grok Imagine — default The recommendation comes from testing, not loyalty: boldest riso texture, the strongest character lock from the reference sheet, honors 16:9 — and the cheapest of the set. $
Nano Banana 2 The dependable fallback: fast, the most reliable label text, publicly catalogued. $
Nano Banana Pro Richest detail — worth it for hero images. $$
GPT Image 2.5 Flare Fast OpenRouter Images API option for generation and reference-guided edits; see the Flare details. $$
GPT-5.4 Image 2 Strong instruction-following, but pricey and tends to return square regardless of the requested aspect. $$$

Worth knowing:

  • The Grok default is API-reachable but not in OpenRouter's public model list — it works for accounts with access. If a render 404s with "no endpoints found", the skill knows to fall back to Nano Banana 2.
  • Any other OpenRouter image-output model works too — name it in the request ("use Nano Banana Pro for the hero") and the skill maps it. Ask for a model comparison and it renders the same prompt across models into a side-by-side gallery with per-image costs.

Install

Prefer the native lane for your runtime: it installs the same illo skill and keeps you on that platform's managed update path. The generic skills CLI is the fallback for runtimes without a native plugin/skill manager.

Platform Install Update
Claude Code /plugin marketplace add tmchow/illo-skill then /plugin install illo@illo-skill claude plugin update illo, or enable marketplace auto-update
Codex codex plugin marketplace add tmchow/illo-skill then codex plugin add illo@illo-skill codex plugin marketplace upgrade
Grok CLI grok plugin marketplace add tmchow/illo-skill then grok plugin install tmchow/illo-skill --trust grok plugin update illo
Grok Bot tap the illo bot template add the template again after updates
Gemini CLI gemini extensions install https://github.com/tmchow/illo-skill gemini extensions update illo
Copilot / GitHub CLI gh skill install tmchow/illo-skill illo (cross-agent via --agent) gh skill update illo
Hermes hermes skills install tmchow/illo-skill/illo hermes skills update illo
OpenClaw openclaw skills install illo reinstall with the same command
Cursor npx skills add tmchow/illo-skill --skill illo (Cursor Marketplace listing pending review) re-run the installer
Muse (Blip) Paste into your Muse chat: Install the illo skill from https://github.com/tmchow/illo-skill Ask Muse to update the illo skill
Other agents / last resort npx skills add tmchow/illo-skill --skill illo npx skills update

Grok Bot

Open the illo bot template and tap Add to Grok Bot. That creates an illo bot on your account.

From an interactive Hermes session:

/skills install tmchow/illo-skill/illo
/reload-skills
/skill illo

Use the directory identifier, not a raw SKILL.md URL — illo is a multi-file skill (engine script, references, character sheet), and the single-file URL form would install the instructions without the engine.

Releases are tagged v<version> and the version in every native manifest is kept in lockstep with SKILL.md by Release Please and CI.

Use it for

  • Article illustrations — paste a post or doc; it finds the few load-bearing moments (never one image per paragraph), proposes a shot list, and produces a set you can interleave through the piece.
  • A single concept — "illustrate you are the bottleneck" → one deadpan scene that lands one takeaway. If the idea is thin, it asks a couple of quick questions first instead of guessing.
  • Surprise / random — "surprise me", "random", or scoped variants like "surprise me with art quote using bray": rolls provenance (~1/3 verified quote / topical hook / original; a * quote focus forces a cited quote), builds three shareable saying candidates, then lets you pick (or auto-picks the best with --autopick — preferred for schedulers), picks register from the locked saying and a random installed character unless named, and returns one image plus that caption-ready line. Built for casual prompts and scheduled agents alike.
  • Mini-comics — a process, a before→after, a fail→fix told in 2–4 panels inside one image. The best shape when a sequence belongs together — and for social, where one self-contained image beats a thread.
  • Explainer diagrams — when the point is the structure (labeled stages, a fan-out, a timeline, a loop, a layered stack), ask for "the flow", "as labeled stages", "label the steps", "walk the stages", or "an explainer" and the same mascot and look draw it as a hand-built sketch-diagram: named phases, one flow direction, station names plus arrow notes — traceable, but never a PowerPoint / Visio flowchart look. Asking for a flowchart still means labeled stages in the pack's look. A named pipeline or recipe is labeled stages: one connected system, solved for that character, never a new look. The world is invented from the thesis and the pack. The scene stays the default; the diagram register is opt-in or earned by content whose thesis is the structure itself.
  • Character cutouts — transparent PNG of the mascot alone (pose, optional contact objects in touch with the body) for slides, compositing, or handing off to another tool. Codex uses native alpha; the engine keeps chroma as an automatic OpenRouter and explicit compatibility path. Not for explaining an idea — that stays editorial.
  • Your own mascot — the character builder interviews you (or starts from art you already have), pressure-tests the concept against the house guardrails, renders model-sheet candidates, and installs the winner as a named character pack in ~/.config/illo/characters/<name>/. Keep several packs, set a default in the config, and switch per run by name ("use blot"). Every image stars the active character, kept on-model by a reference lock.
  • Community characters — browse and install packs from illo-characters ("install the blip character", or packs install --all to install the catalog locally); installs are pinned, and "update blip" pulls the repo's current version when you want it. Or publish your own: the skill opens a PR there with your model sheet and a scene render embedded for one-glance review. Companies can point packsRepo at a private pack repo instead.
  • Blog / brand-matched art — ~/.config/illo/palettes.md holds your own named palettes (the skill builds one for you by reading your site's CSS: background → paper, text → ink, link color → accent) plus plain-text destination lines like blog → notes. After that, blog posts wear your site's colors and X posts wear the bold house palette — same character, automatically. Or hand it one brand color and it derives a full palette around it.
  • Social-ready art — bold house palette, square or wide, with your handle hand-lettered in as an optional watermark (from your config; never a built-in default).
  • Choosing between options — render variations or run the same prompt across multiple models, then get a self-contained comparison gallery showing each image's model, cost, and prompt.

Throughout, the mascot stays on-model via a reference lock, every image is self-checked against a quality bar (one idea per image, accent restraint, no stray titles, fresh metaphor every time), and aspect ratios cover article (16:9), social (1:1), and vertical formats.

Notes

  • This style is intentionally not photorealism, logos, UI mockups, charts, or generic stock art.
  • Image models approximate exact colors; the skill eyedrops and re-rolls off-target palettes.

In this repo

The skill lives in this directory (skills/illo/). Installers copy it verbatim, so only what every install should ship belongs here. Docs-only images live in _assets/illo/ at the repo root (linked by raw URL). Proven explainer renders used on the repo README are in docs/examples/. Plugin manifests sit at the repo root (.claude-plugin/, .codex-plugin/, .cursor-plugin/, .grok-plugin/, gemini-extension.json).

License & credit

MIT © Trevin Chow. Illo — including the Blot default character and the bundled example artwork — is original work; if you redistribute or build on it, please keep attribution. See NOTICE. Characters you create with the character builder are, of course, yours.


SKILL.md is the agent-facing instructions — you don't need to read it to use the skill.

Skill manifest

Illo

Make original, distinctive editorial illustrations for written content. One image explains one idea: a key judgment, a flow, a before/after, a trap, a loop. A recurring mascot is the one performing the idea in every scene — the subject, never decoration. When one idea advances through stages, it can be a mini-comic: 2–4 panels inside a single image. And when the idea is itself a traceable structure — a pipeline, labeled stages, a fan-out, a timeline, a loop — it can be an explainer: the same mascot and look drawing the structure as a hand-built sketch-diagram with arrows and callouts (references/composition.md, "Two registers" and "Pick the diagram type"; editorial scene is always the default). A named pipeline or recipe is labeled stages inside that register — named phases in order, one connected system, pack-solved for this body, never a new look. Or a character cutout: the mascot alone on a transparent PNG for downstream overlay — pose and contact continuity only, no idea, no text, no environment (references/cutout.md).

This is a configurable house style, not a generic image generator. The methodology is the constant; the character pack and palette are the parameters — and a character pack carries its style with it: one look per pack, chosen from the bundled look library (riso — grainy halftone, ink-layer offset, paper grain, one bold softly-rounded outline — plus blueprint, woodcut, pixel, clay, manila, chalk, phosphor, enamel, gouache, felt, diorama, sketchbook, bricks, fizz, bloom, and snes) or a custom style file. The default mascot is Blot, a deadpan ink-drop in riso. Palettes come from presets, the user's own palette file, or one derived color. Whatever the parameters, it is intentionally not a photo — with one deliberate exception, the bricks look, a toy-brick photography style — not a logo, not a corporate infographic, not a formal boxes-and-diamonds flowchart look, not a UI mockup. Asking for a flowchart still means labeled stages in the pack's look — the formality ban is a look constraint, not a refusal of the word.

Use cases — route the request

The user wants The path
Illustrate an article / post / newsletter / URL Steps 0–7: route the source first (thesis → coverage: hero / hero+set / set / mini-comic — references/composition.md, "Source routing"), then shot list (hero row + anchors), one image per anchor, interleave by placement.
One image for a single concept Step 1 concept branch (up to ~3 quick questions if the idea is thin), then a single image.
Surprise / random — "surprise me", "random", "surprise me with art quote using bray", "surprise me --autopick" Read references/surprise.md in full: Step 0 first, then character + provenance (ignore defaultCharacter; * quote forces a cited quote; else ~1/3 roll), build three safe candidates, interactive picker or auto-pick-best (--autopick preferred for schedulers), then register from the locked saying, then Steps 3–7 as one image. Deliver saying + image. Poster titles default off; mini-comics still get per-panel labels.
A sequence — story beat, before→after, fail→fix One mini-comic when the progression sits in one place (shape routing in references/composition.md — the idea picks the shape, the destination never does). A specified process diagram / flowchart / labeled workflow is labeled stages, not this row.
A traceable structure — "show the flow", "as labeled stages", "label the steps", "walk the stages", "diagram the pipeline", "like that factory diagram", "map the steps", "as an explainer", or specified flowchart / labeled-workflow / process-diagram intention The explainer register (references/composition.md, "Pick the diagram type" and "The explainer register"): a hand-built labeled-stages / flow / fan-out / timeline / loop / stack / system slice in the active look, the mascot a working part of it. Specified flowchart / labeled-workflow / process-diagram intention locks labeled stages in the pack's look — the formal-flowchart ban is a look constraint (no Visio, no title/legend/grid), not a refusal of the word. Labeled stages is a structure type inside explainer, not a new register or look — pack-solve it for the active character before the prompt. BEST when a unit's thesis IS a named pipeline, recipe, or staged process; never the automatic choice for every explainer.
Social-ready art for X posts / article body images 16:9 (or 1:1 when square is explicitly useful), bold ink-punch, watermark with the x handle if configured or asked.
X Article banner / hero image Use the unique banner format: 1536 × 640 px when the user asks for an X Article hero/banner. Prompt and render through the normal illo.py generate image pipeline, with normal, undistorted character/object proportions and crop-safe breathing room. Do not satisfy this by manually compositing or rebuilding crops from another image unless the user explicitly asks for post-processing.
Blog / brand / site-matched art A named or custom palette, or derive the palette from one dominant color (references/palettes.md).
Their own mascot — "make me a character", "use our mascot", "replace Blot" The character builder: read references/character-builder.md in full and follow it end to end.
Community characters — "what characters are available", "install blip", "install all characters", "update mole", "publish my character" references/pack-sharing.md — engine packs list/show/install/update, including packs install --all; publish via a GitHub PR.
A different look — "in blueprint", "woodcut style", "pixel version of blip" Styles travel with character packs: build a style variant pack via references/character-builder.md, "Style variants".
Options to pick from, or "which model is best" Step 5b: --count variations or a model loop → gallery with a recommendation.
Fix an existing image (stray title, recolor, mascot too decorative) Edit prompts in references/prompt-recipe.md, passing the image back as --ref.
Character cutout / transparent PNG / overlay sticker — "just the mascot", "no background", "paste on something else" The cutout register (references/cutout.md): read in full, prompt from references/prompt-recipe.md "Cutout variant", generate with --cutout and --aspect 1:1. OpenRouter cutouts default to GPT Image 2 (not Grok). Not for explaining an idea — reroute to editorial if the ask needs a scene.
Animated idle / bot avatar / looping GIF of the mascot The cutout register plus references/cutout.md, "Idle loop / bot avatar": one transparent 1:1 cutout with --cutout and the character sheet as --ref, then programmatic motion on that PNG.

Prerequisites

The engine (scripts/illo.py, stdlib Python, no installs) renders through one of three engine backends plus two agent-side transports; python3 and network access are the only hard requirements. Grok Bot (Cursor's Grok Bot / the Grok desktop assistant) is an agent-side transport: use its built-in Grok image tool directly, not illo.py generate, when no user config explicitly selects an engine backend. Muse (Meta's personal assistant, Blip) is the other agent-side transport: when you are Blip, build the illo prompt per this skill and call your native image-generation tool with the active character sheet attached as a reference. Other agents that happen to expose some image API must not take either native path — the agent must be able to call its own built-in image tool and be named above.

Running the engine — set $SKILL_DIR inline in each block. Every engine command below is python3 "$SKILL_DIR/scripts/illo.py" …. Set SKILL_DIR to the absolute path of the directory this SKILL.md was loaded from (it contains scripts/illo.py and assets/) in the same command block that uses it — shell state does not persist between separate command runs, so a value set in an earlier block is gone by the next. If the harness does not expose that path, find the installed scripts/illo.py and use its parent; if neither resolves, stop rather than guessing the working directory. The engine self-locates its own bundled assets, so $SKILL_DIR only has to be right enough to launch illo.py and to point --ref at the bundled character sheet.

Write the block flatten-safe — some hosts (Codex observed) collapse a fenced block to one line, turning a newline into a space. Terminate the assignment with ; (SKILL_DIR="…"; — without it, a flattened SKILL_DIR="…" python3 "$SKILL_DIR/…" becomes an env-prefix whose $SKILL_DIR expands to empty before the assignment applies, so the path collapses to /scripts/illo.py). Put no comment on an assignment or command line (a flattened # comments out the rest of the line and the command silently vanishes), and keep each invocation on one line (a flattened \ continuation injects stray arguments). A wrong or unset value makes doctor (Workflow step 0) fail loudly (can't open file …/scripts/illo.py) — the signal to fix the path, not a skill fault.

  • Codex backend (free for Codex subscribers). When the host has a usable Codex CLI — installed, codex login-ed, with the image_generation feature — illo can generate through the user's Codex subscription at no per-image charge (it draws on their Codex quota). No API key, no token: illo only shells out to the user's own CLI. Detected, not assumed; gpt-image-2 is automatic; unsupported on Windows/WSL.
  • Grok CLI backend (free for Grok/xAI subscribers). When the host has a usable Grok CLI — installed and grok login-ed — illo can generate through the user's Grok subscription via grok -p (headless), drawing on their Grok quota. Same env-free, token-free subprocess design as Codex. Grok returns JPEG with no alpha, so it cannot make transparent cutouts — those auto-fall back to a cutout-capable backend. The image tool exposes no model selector.
  • Grok Bot native transport (agent-side, free for Grok Bot users). When you are Grok Bot — specifically Cursor's Grok Bot / the Grok desktop assistant with the built-in Grok image tool — build the illo prompt and call that tool with the active character's model sheet as a reference image. Do not require the Grok CLI, Codex CLI, or an OpenRouter key; do not treat a missing engine backend as a reason to run init. This is not a generic "host image API" rule and not an illo.py --backend value.
  • OpenRouter backend (paid, direct or explicit fallback). Needs an OpenRouter API key in the user's config file — the single credential channel — written once by the user-run init (mode 600). The engine never reads secrets from the environment and never accepts them as command-line arguments. A host without a subscription CLI can select this engine path directly. A failed Codex/Grok CLI render does not spend money automatically: paid fallback requires --allow-paid-fallback. It is model-selectable (--model).

Capsule of the backend/transport model (resolution and precedence, the CLI requirements, the Grok Bot native path, the built-in image tool being automatic, quota vs. charge, cutout limits, Windows/WSL, fallback): read references/backends.md in full before choosing or explaining a backend — the mechanics live there, once.

Setup is the user's job (never enter the key yourself)

Entering an API key is something the user does. Do not type, paste, print, or store the user's key — direct them to bootstrap it:

  • Bootstrap (user runs it): python3 "$SKILL_DIR/scripts/illo.py" init — prompts for the key at a hidden prompt (never echoed) and writes the YAML config ${XDG_CONFIG_HOME:-~/.config}/illo/config.yaml (mode 600). It can also store non-secret defaults: --model, --palette, --aspect, --character, --watermark. Use --no-key to update preferences without touching the stored key. (The config is read via PyYAML when installed; without it a minimal built-in parser still reads the flat keys — apiKey, model, … — so generation needs no installs. Only nested settings like watermark need PyYAML: python -m pip install 'PyYAML==6.0.2'.)
  • Non-secret prefs may be seeded for the user with the same command and --no-key, but the key itself is theirs to enter.

Hermes Agent only: binary asset repair preflight

Some Hermes versions corrupt binary files (the bundled character sheets) when installing multi-file skills from GitHub — text files survive, binaries don't, and a corrupted sheet silently breaks the character lock. Under Hermes Agent, run this once before first use (and whenever doctor reports assets: CORRUPTED):

bash ${HERMES_SKILL_DIR}/scripts/repair-hermes-assets.sh

It verifies every bundled binary against known-good SHA256 hashes (assets/checksums.txt) and re-downloads only mismatched files from pinned, immutable URLs — a no-op when everything checks out. Under Claude Code, Codex, OpenClaw, or any runtime that installs faithfully: skip this; doctor checks asset integrity everywhere and will say if repair is ever needed.

Read these references as needed

Do not load everything at once. Pull the file that matches the step:

  • references/visual-style.md — riso, the house default look: the risograph technique, line language, paper/ink, hard do/don'ts.
  • references/styles/<name>.md — the rest of the look library (blueprint, woodcut, pixel, clay, manila, chalk, phosphor, enamel, gouache, felt, diorama, sketchbook, bricks, fizz, bloom, snes), consumed by character packs. Read the active character's style file in full before generating.
  • references/character.md — the character rules (the load-bearing test, anti-complexity guardrails, value-follows-palette, the interaction model — declared per pack or derived conservatively from the locked design and reference sheet), the default character Blot, and the custom-pack format. Read before any character work.
  • references/character-builder.md — the guided flow for designing and installing a user's own mascot. Read in full before building or replacing a character.
  • references/pack-sharing.md — installing characters from the community repo and publishing a pack via PR. Read before any install/publish request.
  • references/palettes.md — named presets, default resolution, custom palettes, and the derive-a-palette-from-one-color algorithm. Read in full before choosing or deriving any palette.
  • references/composition.md — the two registers (editorial scene / explainer diagram), the diagram-type picker, the explainer's structure types and budget (including labeled stages, arrow notes, and its pack-solve), stagings, turning an idea into a move, the anatomy-action feasibility gate (validate the contact map against the character's interaction model before rendering), the no-recycled-composition rule, and the shot-list format.
  • references/cutout.md — the cutout register: transparent compositing assets, contact continuity, pose vocabulary, and generate flags. Read in full before any cutout request.
  • references/surprise.md — surprise / random mode: preflight-first, scope parse, random character, provenance variety + three saying candidates (optional parallel verify for sourced modes), interactive picker or --autopick / auto-pick-best, full re-roll on refresh, register after the locked saying, saying bar + sense bar, multi-source quote verification, safety-before-offer, headless contract. Read in full before any surprise/random request.
  • references/backends.md — the three-backend image engine plus the Grok Bot native transport: how the engine backend resolves (precedence Codex > Grok > OpenRouter, and the self-identify rule), when Grok Bot bypasses illo.py generate, the Codex/Grok CLI requirements, artifact-first success, the built-in image tool being automatic (no model selection), quota-vs-charge, Grok's no-cutout limit, Windows/WSL, and opt-in paid fallback. Read before choosing or explaining a backend.
  • references/models.md — the model lineup (OpenRouter backend only): friendly-name → OpenRouter id map, traits, aspect caveats, 404/fallback handling. Read before passing any --model.
  • references/prompt-recipe.md — the generation prompt template and the edit/recolor prompts.
  • references/quality-bar.md — the post-generation checklist and iteration rules. Read before delivering.

assets/character-reference.webp is the default character's canonical model sheet — the consistency anchor (used by the engine, below); a custom pack brings its own. Style-calibration examples are not bundled — each style file links its own by URL (fetch when needed): study line density, negative space, and accent restraint. Never copy their compositions — invent a fresh metaphor for the current piece.

Workflow

0. Preflight

Before generating, confirm the engine is ready:

SKILL_DIR="<path to this skill>";
python3 "$SKILL_DIR/scripts/illo.py" doctor

Run the illo.py call standalone — never chained with && — so the displayed exit code is the readiness signal itself (0 = ready): a chained neighbor's failure paints a healthy check as an error.

It reports python, the config path, the resolved model/palette defaults, whether a custom character pack or custom palettes file exists, Codex/Grok CLI detection and the resolved backend/transport, and whether an OpenRouter key is found (without revealing it); exit 0 = the resolved backend is ready. An OpenRouter-only install (no subscription CLI) stays exit 0 — readiness follows the resolved backend, not a hardwired key check (references/backends.md).

Grok Bot native path (agent-side). If you are Grok Bot (Cursor's Grok Bot / the Grok desktop assistant with the built-in Grok image tool) and the user has not explicitly chosen backend: openrouter, backend: codex, or backend: grok, initialize the agent-side transport before relying on doctor:

SKILL_DIR="<path to this skill>";
python3 "$SKILL_DIR/scripts/illo.py" init --backend grok-bot --no-key

Then run doctor normally: exit 0 is meaningful readiness for this path. Missing Codex CLI, Grok CLI, or OpenRouter key are not failures when backend: grok-bot; corrupted assets, unreadable custom packs, malformed palettes, or the wrong SKILL_DIR still fail and must be fixed before rendering. Generate in Step 5 by calling Grok Bot's built-in Grok image tool with the active model sheet reference. This route is only for Grok Bot's own Grok image tool; other agents with unrelated image tools must use the engine backends below.

Short path for Grok Bot: run init --backend grok-bot --no-key once when backend is unset/auto, run doctor for assets/config/packs, use packs commands normally (including packs install --all after install so community characters are local), read the same references, build the same prompt, then call Grok Bot's built-in Grok image tool with the active character reference. Skip illo.py init for OpenRouter unless the user explicitly wants OpenRouter or another engine backend default, and skip illo.py generate unless the user explicitly selected an engine backend.

Muse native path (agent-side). If you are Blip (Meta's personal assistant, Muse) and the user has not explicitly chosen an engine backend (backend: openrouter, backend: codex, or backend: grok), initialize the agent-side transport before relying on doctor:

SKILL_DIR="<path to this skill>";
python3 "$SKILL_DIR/scripts/illo.py" init --backend muse-native --no-key

Then run doctor normally: exit 0 is meaningful readiness for this path. Missing Codex CLI, Grok CLI, or OpenRouter key are not failures when backend: muse-native; corrupted assets, unreadable custom packs, malformed palettes, or the wrong SKILL_DIR still fail and must be fixed before rendering. Generate in Step 5 by calling your native image-generation tool with the active model sheet reference. Unlike Grok Bot, this path can do cutouts: render on the pack's chroma screen and run illo.py keyout (see references/cutout.md). This route is only for Blip's own native image tool; other agents with unrelated image tools must use the engine backends.

Short path for Muse: run init --backend muse-native --no-key once when backend is unset/auto, run doctor for assets/config/packs, use packs commands normally, read the same references, build the same prompt, then call your native image tool with the active character reference. Skip illo.py generate unless the user explicitly selected an engine backend — for a native render, record it with illo.py record (or keyout for cutouts) so it joins the run's manifest.jsonl and galleries.

Config migration — surface the backend choice interactively. When you are going to use illo.py generate, if doctor reports backend: NEEDS CHOICE (or generate hard-stops saying the config "is out of date"), this user's config predates the backend choice — they have an older install and have never been offered a subscription CLI. Do not pick for them silently. Surface an interactive choice using the platform's blocking-question capability (AskUserQuestion in Claude Code, the equivalent elsewhere; where the host has none — e.g. a plain chat session — ask the same one choice as a concise message and wait for the reply, never picking silently): "illo now has image backends/transports — which would you like?" with five options — Codex (free, your Codex subscription), Grok CLI (free, your Grok subscription; no transparent cutouts), Grok Bot (agent-side native tool; use only when you are Grok Bot), Muse (agent-side native tool; use only when you are Blip, Meta's personal assistant), and OpenRouter (pick the model: Grok Imagine, Nano Banana, GPT Image, and others). Persist the answer without touching any existing key: python3 "$SKILL_DIR/scripts/illo.py" init --backend <codex|grok|grok-bot|muse-native|openrouter> --no-key, then continue. A brand-new install (no config at all) is ordinary onboarding, not this migration — it does not fire.

Prefer your own CLI when you are a subscription-CLI agent. The engine's auto-default reads host capability (Codex > Grok > OpenRouter; it can't tell which agent invoked it) — but you know which agent you are. So when you are a subscription-CLI agent and your own CLI is usable on this host, add your own backend flag to generate for non-cutout renders: the Grok CLI agent adds --backend grok, the Codex agent adds --backend codex. This keeps "in Grok CLI, generate with Grok" true even on a host that also has Codex, with no runtime-sniffing in the engine. Cutouts ignore this (Grok can't make them — they auto-fall back). A user's config backend: overrides everything. Resolution and precedence mechanics: references/backends.md.

For Grok Bot, the equivalent self-identify rule happens before generate: when backend is unset/auto, persist backend: grok-bot with init --backend grok-bot --no-key and use the native Grok image tool path above. If the user explicitly configured or requested an engine backend, honor that choice instead of silently switching to Grok Bot native.

For Blip (Muse), the equivalent rule is the same: when backend is unset/auto, persist backend: muse-native with init --backend muse-native --no-key and use the native image tool path. If the user explicitly configured or requested an engine backend, honor that choice instead of silently switching to Muse native.

Read the printed config path before concluding the key is missing: under Hermes, multi-profile setups can resolve HOME/XDG_CONFIG_HOME to another profile's home (e.g. …/profiles/<name>/home/.config/illo/…), so a key that exists looks absent. If the path points at the wrong profile, re-run with the right HERMES_HOME/HOME/XDG_CONFIG_HOME rather than treating the key as missing. If the key is genuinely missing, stop and ask the user to run python3 "$SKILL_DIR/scripts/illo.py" init themselves — do not enter the key for them. In a chat session the user can't run commands where they are, so shrink their host-side step first: run init --no-key yourself (allowed — it scaffolds the config with defaults and a commented # apiKey: placeholder, mode 600, never touching a key), then offer the user two equivalent one-time options on the machine the agent runs on (that host is theirs — it's where they installed the agent): run python3 <resolved absolute $SKILL_DIR>/scripts/illo.py init (hidden prompt), or open ~/.config/illo/config.yaml and fill in the apiKey: line. The key must never transit the chat: never ask for it in a message, and if the user pastes it anyway, do not use it — tell them to revoke that key at openrouter.ai and set a fresh one on the host (the pasted key now lives in chat history and platform servers). Never copy a key from the environment or any other store into the config yourself — the user is the only writer of that line — with one scoped exception: an ephemeral cloud workspace (Claude Code web, Codex cloud, CI) where the user provisioned OPENROUTER_API_KEY through the platform's secrets mechanism. That provisioning is itself the user's deliberate, workspace-scoped consent, and there is no interactive prompt or persistent home for init — so there, seed the config from the workspace secret once (the "Cloud & CI" one-liner in README.md). On a personal machine an ambient env var proves nothing about intent (it may belong to other tools) — the rule stands: never copy it.

Optional pack-freshness offer (preflight, consent-first). When this run will render with an installed community pack (doctor lists packs; installs carry a .version stamp), optionally check freshness: python3 "$SKILL_DIR/scripts/illo.py" packs list flags stale installs ([installed 1.0.0 — 1.0.2 available]). The check may run here, but the offer fires once the active pack is known — after Step 2 resolves the character (or after surprise mode's character roll), immediately before the first render that uses it. If that resolved pack is stale, offer once — via the platform's blocking-question capability, as in the config migration above — to refresh it before rendering, and run packs update <name> only on an explicit yes (updating overwrites the local copy; the hand-edit warning and --as alternative are in references/pack-sharing.md). Never update silently, and never block on this: a "no", an offline host, a registry error, or a headless/scheduler run (e.g. surprise --autopick) all continue with the pinned copy — a pack without a declared ## Interaction model still plans safely via the conservative derivation (references/character.md). Skip the check entirely when no community-installed pack is involved.

1. Read the input — and clarify a thin concept (briefly)

Three kinds of input, handled differently:

  • Surprise / random ("surprise me", "random", "surprise me with art quote using bray", "surprise me --autopick", and close variants) — the ask is invent-and-render, not a supplied thesis. Stop and read references/surprise.md in full, run Step 0 first, then resolve character and provenance there (ignore defaultCharacter; random character when unnamed), build three saying candidates and lock one via picker or auto-pick-best, pick register from the locked saying, then continue Steps 3–7 as one image — Steps 0 and 2 are skipped in that render pass because preflight and pack are already done. Do not enter the thin-concept Q&A path below. A prompt that already names a concrete idea ("illustrate 'you are the bottleneck'") is not surprise mode even if it also says "surprise me".

  • A URL / article / paste / long post carries its own context — but never generate from the first vivid detail. Route it first (references/composition.md, "Source routing"): classify the source's shape and genre, infer the requested artifact's job (what this image must do for its audience), separate that job from the source's most drawable mechanism, lock the main thesis in one sentence (a hero locks the source/artifact job, not its loudest evidence — the genre guardrails say what each genre heroes), then pick the coverage — hero, hero + per-section set (the full article job), set, mini-comic, or shot list first. Sets need placements: compact sources (a tweet, one concept) never yield a set — their multi-beat form is the mini-comic. Pull the load-bearing moments — the few places that turn on a judgment, a loop, an input→output, a before/after, or a trap — never one image per paragraph. The text already says what it's about, so don't interrogate the user, with one exception: a materially multi-beat source (long article, postmortem, multi-claim launch) gets a single coverage question before any multi-image spend — unless the user already named the coverage. A lone image from a multi-beat source is a hero, delivered saying so — not as coverage of the piece.

  • A bare concept or one-liner (e.g. "illustrate 'you are the bottleneck'") usually underspecifies the picture. Ask up to ~3 quick questions — only the ones that change the output — then build. Draw from:

    • the single takeaway (what should the reader conclude?),
    • where it's headed (blog / deck / X post / X article body / X Article banner → sets palette, aspect, pixel normalization, and watermark),
    • the shape: one image (the default), a mini-comic (2–4 panels in one image — only when the idea itself advances through stages), or several separate images — plus any must-include element or constraint. The shape follows the idea, never the destination (references/composition.md).

    Keep it to one short round, then proceed. Skip the questions entirely if the user already gave enough, said "just make it" / "single shot", or the answer is obvious from context. Never block a clear request by asking.

2. Resolve the character

Surprise / random mode: skip this step — character was already resolved in references/surprise.md (named pack, or random among installed + Blot; never defaultCharacter). Continue at Step 3+.

Installed packs live under ${XDG_CONFIG_HOME:-~/.config}/illo/characters/ (format and location details: references/character.md); doctor lists what's installed. A user can keep several and pick per run. First match wins:

  1. Explicit request — "use
  2. Config default — defaultCharacter from the user config, if set.
  3. Shipped default — Blot (spec in references/character.md, model sheet assets/character-reference.webp).

Once resolved, read the pack's character.md and use its prompt spec, value rules, optional Cutout chroma: compatibility preference, and reference.png everywhere the default's would be used.

When rerouting an article set to a new character — especially after a weak attempt, or for a technical/platform essay — read references/article-set-character-reroute.md in full before planning or rendering. Do the legibility preflight there before spending renders.

If the user wants a new character, that is the character builder (references/character-builder.md); if they want someone else's, packs install from the community repo (references/pack-sharing.md). Either way, install first, then continue here.

3. Plan (shot list) — when asked to plan, or for anything multi-image

If the user wants planning ("where should this be illustrated", "shot list"), output a shot list before generating. Per image: placement, the one idea, the artifact job, the register (editorial unless the row passes the explainer gate), the staging (or structure type — pick per references/composition.md, "Pick the diagram type"), what the mascot is doing, the palette, and the text hierarchy — primary read/title when the artifact needs one, plus short supporting labels/callouts within the per-register budgets in references/composition.md. Let the anchor count drive how many (bands and the never-pad rule are in references/composition.md). When a stretch of the piece advances through stages in one place, plan a single mini-comic image there instead of several — the mini-comic-vs-separate routing is in references/composition.md.

For article-set character reroutes, add the mandatory preflight fields from references/article-set-character-reroute.md before any render: section claim, visual object/action, and reader mapping. Reject rows that need a private metaphor glossary or more than one conceptual substitution.

4. Resolve the palette (the style is the character's)

Style is not separately resolvable: the active character's pack carries it — the Style: line in its character.md names a bundled look (references/styles/<name>.md, riso in visual-style.md) or a custom one at ${XDG_CONFIG_HOME:-~/.config}/illo/styles/<name>.md; absent line = riso. Blot is riso. For any non-riso style, read its file in full: it supplies the STYLE and LINE LANGUAGE prompt blocks, the palette mapping, the character treatment, and extra QA checks. A request for the same character in a different look is a variant-pack build (route table) — never restyle on the fly.

Palette: read references/palettes.md in full and resolve there — it holds the resolution order (explicit request, then destination cue via the user's palettes file, then config default, then house ink-punch), the named presets, custom palettes, and the derive-a-palette-from-one-color algorithm. End with concrete hex values; when the pack's style isn't riso, run them through that style's palette mapping.

5. Generate — reference-locked, one metaphor per image

Cutout branch. When the request routed to the cutout register, read references/cutout.md in full first — it covers backend-aware transparency (Codex native alpha by default; chroma compatibility for OpenRouter or explicit --chroma), registration-locked silhouette (no ink-layer offset), --cutout /--aspect 1:1, OpenRouter --image-config, and manifest cutout_alpha disclosure. Build the prompt from references/prompt-recipe.md, "Cutout variant" — not the editorial template — and omit manual BACKGROUND: / output-format instructions; the engine appends the contract for the backend that actually runs. Pass --chroma only to force a compatibility reroll. Use only the character model sheet as --ref (no editorial style anchor, no watermark). QA against the cutout section of references/quality-bar.md. Skip the editorial shot-list / thesis steps.

Editorial and explainer. When the locked type is labeled stages, run the pack-solve scratch in references/composition.md ("Labeled stages — skeleton, then pack-solve") before writing the prompt — stage list → operator stage → contact map → bind; do not invent a look. Build a full prompt per image from references/prompt-recipe.md (scene + structure + communication hierarchy + style + the active character's spec + resolved palette hexes + the per-register text budget), write it to a file, and render it. Pass the active character's model sheet as --ref every time — that reference conditioning is what keeps the mascot on-model; style and palette come from the prompt, so both stays swappable. A pack's sheet is born in its own style, so sheet and style always match — no cross-style reference juggling. (Under Hermes Agent, the asset-repair preflight above must have run before the first --ref use — a corrupted sheet conditions every render on garbage.)

Grok Bot native render. If you are Grok Bot and the native path from Step 0 applies, do not run illo.py generate. Use the same full prompt recipe, same aspect ratio, same character lock, same style-anchor rule for sets, and call Grok Bot's built-in Grok image tool. Attach the active character's model sheet as a reference image (assets/character-reference.webp for Blot, or the pack's reference.png); for later images in a set, also attach the accepted style anchor image. Ask the tool to save/return the generated file and treat that saved path as the engine JSON .path equivalent for QA and delivery. Grok Bot's image tool is the same Grok image-model class as the Grok CLI transport: no model selector, no OpenRouter billing, and no alpha channel. Transparent cutouts stay off this path; route them to a cutout-capable engine backend instead, or stop and ask for that backend to be configured.

Muse native render. If you are Blip (Meta's personal assistant, Muse) and the native path from Step 0 applies, do not run illo.py generate. Use the same full prompt recipe, same aspect ratio, same character lock, same style-anchor rule for sets, and call your native image-generation tool. Attach the active character's model sheet as a reference image (assets/character-reference.webp for Blot, or the pack's reference.png); for later images in a set, also attach the accepted style anchor image. Up to four native image calls may be batched in one response — beyond that, continue in a follow-up. Save each returned file under the run dir, then record it with illo.py record (see its usage), which appends a muse-native manifest row with the label and prompt so it joins galleries like engine renders. Treat the recorded path as the engine JSON .path equivalent for QA and delivery.

Unlike Grok Bot, this path can do cutouts: ask the native tool for the pack's flat chroma screen (the pack declares green or magenta), then run illo.py keyout <screen.png> --chroma <green|magenta> --out <final.png> to produce a transparent PNG — see references/cutout.md for the chroma selection, QA, and the opaque-fallback rule. There is no model selector and no OpenRouter billing on this path; --model does not apply.

Set SKILL_DIR inline (see Prerequisites), and use the bundled sheet as REF — or the active pack's reference.png for a custom character. Add --model <id> to override the config/default model for this image (OpenRouter backend only):

SKILL_DIR="<path to this skill>";
REF="$SKILL_DIR/assets/character-reference.webp";
python3 "$SKILL_DIR/scripts/illo.py" generate --prompt-file /tmp/shot-01.txt --ref "$REF" --aspect 16:9 --out "assets/<slug>-illustrations/01-topic.png"

For engine renders, illo.py generate prints a JSON line per image ({path, backend, model, id, cost, width, height, label, prompt}; backend is codex, grok, or openrouter, and model/id/cost are OpenRouter-only — they are null on a CLI-served record (Codex or Grok). cost is null unless --cost is passed — gallery backfills it) and appends the same record to <out-dir>/manifest.jsonl. Read .path — it may differ from --out: the engine names the file by the actual encoding (some models return JPEG bytes, so a requested .png lands as .jpg). Use .width/.height to catch a square when 16:9 was requested (re-roll). A failed Codex/Grok CLI render stops by default even when an OpenRouter key is configured. Add --allow-paid-fallback only when the user has explicitly approved a pay-per-image retry. Direct --backend openrouter renders and the intentional Grok-cutout redirect remain direct routes and do not need this flag. Generate each image separately — never combine ideas into one canvas. Default aspect is 16:9; use 1:1 for square social, 9:16/4:5 for vertical, and 1536:640 for an X Article banner / hero. For X Article banners, the platform target is 1536 × 640 px. Generate through the normal image pipeline; do not manually composite or rebuild the scene from crops as a substitute for an illo render. Check .width/.height, and only do final post-processing when it is a non-distorting resize/crop that preserves normal proportions and all essential information. Never stretch or squash the art to force exact dimensions. Pass --label for a caption that shows in the gallery.

Sets read as one artist. For any multi-image set, the first image that passes the full quality bar (and, for a hero in a rerouted article set, passes the thesis-legibility gate in references/article-set-character-reroute.md; never anchor on an unvetted render — a failed anchor, e.g. an off-palette ground or illegible metaphor, would propagate its failure set-wide) becomes the set's style anchor: pass it as a second --ref after the character sheet for every later image in the set and for every re-roll of a set member, so line weight, halftone density, and flat-vs-dimensional treatment stay consistent throughout. The same trick locks style for a one-off: add any finished example as a second --ref.

Model choice (OpenRouter backend only). --model and config model: are an OpenRouter-only axis — on Codex, Grok CLI, Grok Bot native, and Muse native the image model is automatic and --model does not apply (references/backends.md). For the OpenRouter path, read references/models.md in full before passing any --model (or whenever the user names a model in plain language or asks for "best quality" / "cheapest"): it holds the friendly-name → OpenRouter id map, per-model traits, the aspect-ratio caveat, and the 404/fallback handling. Resolution is --model > config model > built-in default.

Watermark / attribution (optional, off by default). The skill ships with no default watermark — the text comes only from the user's watermark config map (read from the config file) or an explicit request, so installers never inherit someone else's handle. The resolution order, the prompt line to append, and the two-render caveat are in references/prompt-recipe.md.

5b. Batches & comparison (only when it helps)

Default to ONE image. Fan out only when the user asks for options/comparison or the piece is important enough to be worth it — and say first what each image costs: on the Codex backend it draws on the user's Codex quota (no per-image charge), on Grok CLI or Grok Bot native it draws on the user's Grok quota, on Muse native it uses the agent's built-in image tool (no OpenRouter billing), and on the OpenRouter backend it bills their OpenRouter account (typically under ten cents per image, varying by model). Keep N small (2–4). Orchestrate the loop with the engine's primitives:

newrun prints a fresh run dir (/tmp/illo/<runid>) into RUN. Record the user's VERBATIM request (URL, pasted text, concept) to request.txt — the gallery shows it as provenance so anyone can tell what the run was for. Adapt each generate line below to a real path and run it on its own:

SKILL_DIR="<path to this skill>";
RUN=$(python3 "$SKILL_DIR/scripts/illo.py" newrun);
printf '%s' "<the verbatim request>" > "$RUN/request.txt"
# (a) VARIATIONS — same prompt+model, pick-the-best:
python3 .../illo.py generate --prompt-file p.txt --ref <ref> --count 4 --label "draft→ship" --out "$RUN/v.png"
# (b) MODEL COMPARISON — loop the SAME prompt over the chosen models
#     (full OpenRouter ids from references/models.md):
for m in <model-id-1> <model-id-2>; do
  python3 .../illo.py generate --prompt-file p.txt --ref <ref> --model "$m" --label "$m" --out "$RUN/$(basename $m).png"; done
# (c) CONCEPT VARIATIONS — different prompts (different stagings) for one idea:
python3 .../illo.py generate --prompt-file staging-A.txt --ref <ref> --label "as a funnel" --out "$RUN/a.png"
python3 .../illo.py generate --prompt-file staging-B.txt --ref <ref> --label "as a crossing" --out "$RUN/b.png"

python3 "$SKILL_DIR/scripts/illo.py" gallery "$RUN" --title "<the piece or request>" --open
# always pass --title so a saved gallery stays identifiable later;
# add --embed for a single portable file (images inlined)

Every generate self-records to $RUN/manifest.jsonl; gallery assembles them into one page with each image's label, model, dimensions, cost, and a collapsible prompt — the prompt toggle is what makes concept-variation comparison readable (the prompt is the variable). Always present the gallery with a recommendation, not a raw dump — and in a chat session, present the labeled candidates directly in the chat instead of a gallery (delivery routing in step 7). Multi-model failures are per-image (an unavailable model errors that one render only); keep the rest.

6. QA and iterate

Check every image against references/quality-bar.md. Re-roll or edit when the mascot is decorative or off its locked spec, the body is wrong-value for the palette, label text sits on a colored fill, the accent has spread past the character's accent part + 1–2 elements, an unwanted title bar appears, the composition copies an example, or text is misspelled. Subject scale varies run-to-run — re-roll if the subject is tiny (check .width/.height in the JSON: a square back when 16:9 was requested → re-roll). When a re-roll supersedes a render, rebuild any delivery gallery with --exclude <superseded label> (repeatable) so rejected rolls don't appear in the review artifact.

7. Deliver — match the session's medium

Copy finals next to the user's work when appropriate; never overwrite existing assets without being asked. Filenames carry the role — they are the only metadata that survives a document attachment, so make them self-identifying: 00-hero-<slug>.png for the hero, then 01-<section-slug>.png, 02-<section-slug>.png, … for anchors in piece order (assets/<slug>-illustrations/). Then report: how many images, the palette used, which are strongest vs optional — and for any multi-image job, a placement map: one line per image naming the file, its role (hero, or after which section), and the one idea it lands, so the user can drop each file where it belongs without re-deriving the plan. Deliver the images themselves the way this session can actually show them:

  • Filesystem sessions (IDE/terminal agents — Claude Code, Codex, Cursor): report each final's absolute path (the engine's JSON .path is already absolute) and present the gallery for multi-image runs. The file on disk already is the original — never emit [[as_document]] here: it's a Hermes gateway token, literal noise in any other runtime. If the runtime has its own in-chat file delivery, use that.

  • Grok Bot native sessions: deliver the file returned by Grok Bot's built-in image tool inline/as an attachment in chat, and include its saved file path in the same role that engine renders use .path. The returned file is the original for this transport; do not ask the user to configure OpenRouter just to retrieve it.

  • Muse native sessions: deliver the file returned by your native image tool as a sandbox://workspace/... link in chat, and include its saved file path in the same role that engine renders use .path. Record every delivered image with illo.py record (or keyout for cutouts) so the run's manifest.jsonl and galleries stay complete. The returned file is the original for this transport; do not ask the user to configure OpenRouter just to retrieve it.

  • Chat sessions (the user is on a messaging surface — Hermes over Telegram/Discord/WhatsApp, or any chat surface with lossy media delivery — and cannot open local files): a path alone is not a complete deliverable; the image must land in the chat, and a final must arrive as the original file. Platform photo delivery recompresses images — exactly what destroys riso grain, halftone texture, ink-layer offset, and fine hand-lettering — so finals are delivered as document attachments. On Hermes, tag each final with an explicit MEDIA: attachment tag — the tag is MEDIA: immediately followed by the absolute path, no space — and the literal directive [[as_document]] in the same reply. Do not rely on a bare absolute path for a final: bare paths can pass through to the user as literal text instead of being dispatched as an attachment.

    MEDIA:/absolute/path/to/final.jpg
    [[as_document]]
    

    Candidate/options rounds may use normal inline photo delivery when quick glances help — say so ("preview — original file to follow") — but a final is never delivered that way. Skip the HTML gallery in chat — the user has no easy way to open or host it; send the labeled finals directly with the recommendation as text, and only build gallery --embed (one self-contained file) if a portable artifact is explicitly requested, delivering it with [[as_document]].

Before the final reply in a chat session, check:

  • every final's path came from the engine's JSON .path, not the requested --out (the actual extension may differ);
  • every final appears as an explicit MEDIA:/absolute/path attachment tag in the reply;
  • [[as_document]] is in the reply unless this is explicitly preview-only;
  • rejected/re-rolled candidates are excluded from delivery;
  • the text says what was made — character, palette, strongest final, and for sets the placement map (which file is the hero, which follows which section) — without implementation noise.

Output discipline

Pre-generation planning is short and concrete. Post-generation, let the images speak — report what was made and where, not style theory. Keep labels few and short; the fewer words baked into an image, the more reliably it renders.

Talk like a person doing the work, not a recap of this file. Never narrate workflow steps or jargon in chat: doctor, preflight, provenance, register, saying bar, thesis, backend, or "doctor's green." Status, if any, is ordinary speech, not a liturgy of steps. When surprise mode picks an unnamed character, introduce the character once in plain English — pack name plus what they are ("Inch, the chalk inchworm") — then show the lines and ask which one. Never status-ping with the name alone ("Inch."), say "Still Inch," or ask "which one should

Files (illo-skill)
  • assets
    • character-reference-pixel.png 106.8 KB · in bundle
    • character-reference.webp 165.1 KB · in bundle
    • checksums.txt 416 B
      Loading…
  • references
    • styles
      • bloom.md 5.5 KB
        Loading…
      • blueprint.md 2.9 KB
        Loading…
      • bricks.md 6.5 KB
        Loading…
      • chalk.md 2.8 KB
        Loading…
      • clay.md 3.6 KB
        Loading…
      • diorama.md 5.4 KB
        Loading…
      • enamel.md 3.9 KB
        Loading…
      • felt.md 5.4 KB
        Loading…
      • fizz.md 5.2 KB
        Loading…
      • gouache.md 3.1 KB
        Loading…
      • manila.md 3.2 KB
        Loading…
      • phosphor.md 3 KB
        Loading…
      • pixel.md 2.9 KB
        Loading…
      • sketchbook.md 6.8 KB
        Loading…
      • snes.md 8.4 KB
        Loading…
      • woodcut.md 2.6 KB
        Loading…
    • article-set-character-reroute.md 3.8 KB
      Loading…
    • backends.md 19.8 KB
      Loading…
    • character-builder.md 13.1 KB
      Loading…
    • character.md 11.1 KB
      Loading…
    • composition.md 34.2 KB
      Loading…
    • cutout.md 15.8 KB
      Loading…
    • models.md 6.5 KB
      Loading…
    • pack-sharing.md 6.5 KB
      Loading…
    • palettes.md 5.3 KB
      Loading…
    • prompt-recipe.md 17.4 KB
      Loading…
    • quality-bar.md 18.1 KB
      Loading…
    • surprise.md 28.1 KB
      Loading…
    • visual-style.md 3.4 KB
      Loading…
  • scripts
    • diagram_route.py 24.6 KB
      Loading…
    • illo.py 105.1 KB
      Loading…
    • repair-hermes-assets.sh 2.1 KB
      Loading…
  • NOTICE 703 B · in bundle
  • README.md 18.7 KB
    # Illo
    
    **[illo-skill.com](https://illo-skill.com)** — live examples, character packs,
    and copy-paste installs. This file is the developer reference (engines,
    models, cost, API keys).
    
    Turn a concept or an article into original **editorial illustrations** —
    flat, bold-lined print-style scenes where a recurring mascot performs the
    idea. One image says one thing: a key judgment, a flow, a before/after, a
    trap. It's a deliberate house style, not a generic image generator — closer
    to a smart, deadpan print zine than to clip art or an infographic.
    
    The methodology is the constant; **the character pack and palette are yours
    to set** — and every character pack carries its own print style. Out of the
    box the mascot is **Blot**, a deadpan ink-drop in **risograph**. A built-in
    **character builder** designs your own mascot with you (interview — including
    picking its look from the bundled library of seventeen ([below](#looks)) — then
    model-sheet candidates → pick → install). Want the same
    character in another look? Build a *style variant pack* (`blot-woodcut`):
    one pack, one look, so a catalog of characters never turns into a grid of
    combinations. Palettes stay per-image and resolve by **destination**: a
    character defines *where* its accent lives, never the color. One plain-text
    line in your palettes file — `blog → notes` — and anything headed for your
    blog automatically wears `notes`, a palette built once by copying your
    site's real CSS colors into hexes (background → paper, text → ink, link
    color → accent; re-extract only if you rebrand). Same mascot, fluoro pink
    on X, your blog's exact orange on the blog — never asked twice. Or pick a
    named preset, or hand it one brand color and let it derive the rest.
    
    ![Blot — the default mascot](assets/character-reference.webp)
    
    > **Invoking:** the skill answers to its name — say **"illo"** ("illo this
    > post", "use illo: draw blip hauling a crate"). It deliberately won't hijack
    > generic requests like "illustrate this post", and it can't know your
    > installed characters' names up front — lead with "illo", then talk
    > characters freely.
    
    Same character, different voice — the bundled woodcut style telling a
    three-panel story:
    
    ![Woodcut mini-comic example](https://raw.githubusercontent.com/tmchow/illo-skill/main/_assets/illo/styles/woodcut-minicomic.png)
    
    And the day job — compressing an abstract concept into one scene that lands
    in about a second. Hand it *"we replatform with zero downtime"* and you get
    the bridge being rebuilt under live traffic:
    
    ![Zero downtime — rebuilding the bridge under live traffic](https://raw.githubusercontent.com/tmchow/illo-skill/main/_assets/illo/05-bridgeswap-ink-punch.png)
    
    One idea per image, the mascot *performing* the move rather than decorating
    it, a few short hand-lettered labels — every render is held to that
    bar, and off-model results get re-rolled before you see them.
    
    ## Looks
    
    Every character pack picks exactly one look from the bundled library:
    
    | Look | The voice |
    |---|---|
    | **riso** | Grainy halftone risograph — the house default |
    | **blueprint** | White draftsman linework on deep blueprint blue |
    | **woodcut** | Heavy carved relief print on warm cream |
    | **pixel** | Chunky 4-color pixel art |
    | **clay** | Matte stop-motion plasticine diorama |
    | **manila** | Rubber-stamped ink on office manila paper |
    | **chalk** | Dusty chalk on a deep slate board |
    | **phosphor** | Glowing CRT trace on near-black glass |
    | **enamel** | Hard-enamel pin cells with raised metal lines |
    | **gouache** | Flat matte mid-century poster paint |
    | **felt** | Layered hand-cut wool-felt craft |
    | **diorama** | Watercolor-and-ink storybook tabletop diorama |
    | **sketchbook** | Vintage sepia pencil-and-ink editorial sketch |
    | **bricks** | Photoreal toy-brick set — the one photographic look |
    | **fizz** | Psychedelic soda-pop skate-sticker screenprint |
    | **bloom** | Flat cel character in a soft, atmospherically-lit cozy scene |
    | **snes** | 16-bit console sprite editorial with soft dither and game-world staging |
    
    Looks are shared infrastructure, deliberately separate from characters: the
    definitions live in this skill (`references/styles/`), and a character pack
    just names one — so a fix to a look immediately improves every pack that
    uses it, and adding a character never requires touching the skill. Want a
    look that doesn't exist? Drop a custom style file in
    `~/.config/illo/styles/<name>.md` and use it right away — and if it proves
    out, PR it into the library here so packs everywhere can reference it.
    
    ## Prerequisites
    
    Images are generated by a small bundled script (`scripts/illo.py`) through one
    of **three engine backends** — `python3` (standard library only, macOS/Linux)
    and network access are the only hard requirements. In **Grok Bot** (Cursor's
    Grok Bot / the Grok desktop assistant), illo instead uses Grok Bot's built-in
    Grok image tool as an agent-side transport when no engine backend is explicitly
    configured:
    
    - **Codex (free for Codex subscribers).** If you already have the
      **[Codex CLI](https://github.com/openai/codex)** installed and logged in
      (`codex login`), illo can generate through your Codex subscription at no
      per-image charge — it draws on your Codex usage quota instead. No API key
      and no token: illo only shells out to your own CLI. Detected automatically;
      gpt-image-2 is the model (no model selection); unsupported on Windows/WSL.
    - **Grok (free for Grok/xAI subscribers).** If you have the **Grok CLI**
      installed and logged in (`grok login`), illo can generate through your Grok
      subscription via its built-in image tool, drawing on your Grok usage quota —
      same key-free, token-free design as Codex. Handy when illo runs inside the
      Grok agent. Two limits: no model selection, and **no transparent cutouts**
      (Grok returns JPEG with no alpha) — cutouts auto-fall back to Codex or
      OpenRouter.
    - **Grok Bot native (agent-side).** In Cursor's Grok Bot / the Grok desktop
      assistant, the skill instructions route generation to Grok Bot's own built-in
      Grok image tool with the character sheet attached as a reference. This is not
      the Grok CLI lane and not a generic host-image-tool fallback: no `grok`
      binary, Codex CLI, or OpenRouter key is required unless you explicitly choose
      one of the engine backends.
    - **OpenRouter (paid, direct or explicit fallback).** An
      **[OpenRouter](https://openrouter.ai) API key** lets illo call OpenRouter's
      image API directly — the engine path on a host without a subscription CLI.
      **Model-selectable** — see [Models & cost](#models--cost) below. A failed
      Codex/Grok CLI render never spends money automatically: pass
      `--allow-paid-fallback` to explicitly permit that pay-per-image retry.
      Intentional cutout routing remains automatic.
    
    ### Setting the key (OpenRouter path)
    
    For the OpenRouter backend, bootstrap the config file once — you type the key
    at a hidden prompt, and nothing else ever reads or stores it. (The Codex, Grok
    CLI, and Grok Bot native paths need no OpenRouter key; `init` offers CLI
    backends when a usable CLI is detected.)
    
    ```bash
    python3 scripts/illo.py init                  # prompts for the key (hidden),
                                                  # writes ~/.config/illo/config.yaml (mode 600)
    python3 scripts/illo.py doctor                # check readiness
    ```
    
    The config file is the **only** place the engine reads the key from —
    deliberately: no environment variables (skill security scanners treat
    secret-shaped env reads in community skills as exfiltration) and no
    `--api-key`-style flags (command-line secrets leak into process listings
    and shell history). The config (a commented
    `config.yaml`) also holds non-secret defaults — `model`, `defaultPalette`,
    `defaultCharacter`, `aspect`, and an optional `watermark` map for
    attribution.
    There is **no built-in watermark**; set your own so it's only ever yours:
    
    ```bash
    python3 scripts/illo.py init --no-key \
      --watermark blog=yoursite.com --watermark x=@yourhandle
    ```
    
    > The config file is read via **PyYAML** when installed
    > (`python -m pip install 'PyYAML==6.0.2'`); without it a minimal built-in
    > parser still reads the flat keys (`apiKey`, `model`, …) — only nested
    > settings like `watermark` need PyYAML. Either way, image generation
    > itself needs no installs.
    
    ### Cloud & CI environments
    
    In ephemeral workspaces (Claude Code on the web, Codex cloud, GitHub
    Actions, devcontainers) there's no interactive prompt and the home
    directory doesn't persist — there, use the platform's own secrets
    mechanism: add `OPENROUTER_API_KEY` to the environment's secrets, and
    materialize the config in the environment's **setup hook** (Codex
    environment setup script, devcontainer `postCreateCommand`, a CI step):
    
    ```bash
    mkdir -p ~/.config/illo
    printf 'apiKey: "%s"\n' "$OPENROUTER_API_KEY" > ~/.config/illo/config.yaml
    chmod 600 ~/.config/illo/config.yaml
    ```
    
    The key stays in the platform's secret store; each fresh workspace gets
    its config rebuilt at setup time, and the engine still reads only its
    own file. Adding the secret to the environment is the consent — it's
    scoped to that workspace and provisioned by you, deliberately, for the
    tools running there.
    
    ## Models & cost
    
    Cost depends on the transport. On **Codex**, **Grok CLI**, and **Grok Bot
    native** there is **no per-image charge** — generation runs on your Codex or
    Grok subscription and draws on that quota (image turns consume it faster than
    text turns), and the image model is automatic (no model selection). On the
    **OpenRouter** backend generation is **pay-per-image through your OpenRouter
    account** — typically **under ten cents per image**, and a typical blog post
    (3–6 finals plus a few re-rolls) lands well under a dollar on the default model.
    Prices are
    OpenRouter's and drift — check
    [openrouter.ai/models](https://openrouter.ai/models) for current numbers. The
    model table below applies to the OpenRouter backend.
    
    | Model | Why you'd pick it | Relative cost |
    |---|---|---|
    | **Grok Imagine** — *default* | The recommendation comes from testing, not loyalty: boldest riso texture, the strongest character lock from the reference sheet, honors 16:9 — and the cheapest of the set. | $ |
    | Nano Banana 2 | The dependable fallback: fast, the most reliable label text, publicly catalogued. | $ |
    | Nano Banana Pro | Richest detail — worth it for hero images. | $$ |
    | GPT Image 2.5 Flare | Fast OpenRouter Images API option for generation and reference-guided edits; see the [Flare details](references/models.md#flare-through-openrouter). | $$ |
    | GPT-5.4 Image 2 | Strong instruction-following, but pricey and tends to return square regardless of the requested aspect. | $$$ |
    
    Worth knowing:
    
    - **The Grok default is API-reachable but not in OpenRouter's public model
      list** — it works for accounts with access. If a render 404s with "no
      endpoints found", the skill knows to fall back to Nano Banana 2.
    - Any other OpenRouter **image-output** model works too — name it in the
      request ("use Nano Banana Pro for the hero") and the skill maps it. Ask
      for a model comparison and it renders the same prompt across models into
      a side-by-side gallery with per-image costs.
    
    ## Install
    
    Prefer the native lane for your runtime: it installs the same `illo` skill and
    keeps you on that platform's managed update path. The generic skills CLI is
    the fallback for runtimes without a native plugin/skill manager.
    
    | Platform | Install | Update |
    | --- | --- | --- |
    | **Claude Code** | `/plugin marketplace add tmchow/illo-skill` then `/plugin install illo@illo-skill` | `claude plugin update illo`, or enable marketplace auto-update |
    | **Codex** | `codex plugin marketplace add tmchow/illo-skill` then `codex plugin add illo@illo-skill` | `codex plugin marketplace upgrade` |
    | **Grok CLI** | `grok plugin marketplace add tmchow/illo-skill` then `grok plugin install tmchow/illo-skill --trust` | `grok plugin update illo` |
    | **Grok Bot** | tap [the illo bot template](https://x.ai/bot/y3uTGY5hkl6iTmE-ZAX02) | add the template again after updates |
    | **Gemini CLI** | `gemini extensions install https://github.com/tmchow/illo-skill` | `gemini extensions update illo` |
    | **Copilot / GitHub CLI** | `gh skill install tmchow/illo-skill illo` (cross-agent via `--agent`) | `gh skill update illo` |
    | **Hermes** | `hermes skills install tmchow/illo-skill/illo` | `hermes skills update illo` |
    | **OpenClaw** | `openclaw skills install illo` | reinstall with the same command |
    | **Cursor** | `npx skills add tmchow/illo-skill --skill illo` (Cursor Marketplace listing pending review) | re-run the installer |
    | **Muse (Blip)** | Paste into your Muse chat: `Install the illo skill from https://github.com/tmchow/illo-skill` | Ask Muse to update the illo skill |
    | **Other agents / last resort** | `npx skills add tmchow/illo-skill --skill illo` | `npx skills update` |
    
    ### Grok Bot
    
    Open the [illo bot template](https://x.ai/bot/y3uTGY5hkl6iTmE-ZAX02) and tap **Add to Grok Bot**. That creates an illo bot on your account.
    
    From an interactive Hermes session:
    
    ```text
    /skills install tmchow/illo-skill/illo
    /reload-skills
    /skill illo
    ```
    
    > Use the directory identifier, not a raw `SKILL.md` URL — illo is a
    > multi-file skill (engine script, references, character sheet), and the
    > single-file URL form would install the instructions without the engine.
    
    Releases are tagged `v<version>` and the version in every native manifest is
    kept in lockstep with `SKILL.md` by Release Please and CI.
    
    ## Use it for
    
    - **Article illustrations** — paste a post or doc; it finds the few
      load-bearing moments (never one image per paragraph), proposes a shot list,
      and produces a set you can interleave through the piece.
    - **A single concept** — "illustrate *you are the bottleneck*" → one deadpan
      scene that lands one takeaway. If the idea is thin, it asks a couple of quick
      questions first instead of guessing.
    - **Surprise / random** — "surprise me", "random", or scoped variants like
      "surprise me with art quote using bray": rolls provenance (~1/3 verified
      quote / topical hook / original; a `* quote` focus forces a cited quote),
      builds three shareable saying candidates, then lets you pick (or
      auto-picks the best with `--autopick` — preferred for schedulers), picks
      register from the locked saying and a random installed character unless
      named, and returns one image plus that caption-ready line. Built for casual
      prompts and scheduled agents alike.
    - **Mini-comics** — a process, a before→after, a fail→fix told in 2–4 panels
      inside one image. The best shape when a sequence belongs together — and for
      social, where one self-contained image beats a thread.
    - **Explainer diagrams** — when the point *is* the structure (labeled
      stages, a fan-out, a timeline, a loop, a layered stack), ask for "the
      flow", "as labeled stages", "label the steps", "walk the stages", or
      "an explainer" and the same mascot and look draw it as a hand-built
      sketch-diagram: named phases, one flow direction, station names plus
      arrow notes — traceable, but never a PowerPoint / Visio flowchart look.
      Asking for a flowchart still means labeled stages in the pack's look.
      A named pipeline or recipe is labeled stages: one connected system,
      solved for that character, never a new look. The world is invented
      from the thesis and the pack. The scene stays the default; the
      diagram register is opt-in or earned by content whose thesis is the
      structure itself.
    - **Character cutouts** — transparent PNG of the mascot alone (pose, optional
      contact objects in touch with the body) for slides, compositing, or handing
      off to another tool. Codex uses native alpha; the engine keeps chroma as an
      automatic OpenRouter and explicit compatibility path. Not for explaining an
      idea — that stays editorial.
    - **Your own mascot** — the character builder interviews you (or starts from
      art you already have), pressure-tests the concept against the house
      guardrails, renders model-sheet candidates, and installs the winner as a
      named character pack in `~/.config/illo/characters/<name>/`. Keep several
      packs, set a default in the config, and switch per run by name ("use
      blot"). Every image stars the active character, kept on-model by a
      reference lock.
    - **Community characters** — browse and install packs from
      [illo-characters](https://github.com/tmchow/illo-characters) ("install the
      blip character", or `packs install --all` to install the catalog locally);
      installs are pinned, and "update blip" pulls the repo's
      current version when you want it. Or publish your own: the skill opens a PR there with your
      model sheet and a scene render embedded for one-glance review. Companies
      can point `packsRepo` at a private pack repo instead.
    - **Blog / brand-matched art** — `~/.config/illo/palettes.md` holds your own
      named palettes (the skill builds one for you by reading your site's CSS:
      background → paper, text → ink, link color → accent) plus plain-text
      destination lines like `blog → notes`. After that, blog posts wear your
      site's colors and X posts wear the bold house palette — same character,
      automatically. Or hand it one brand color and it derives a full palette
      around it.
    - **Social-ready art** — bold house palette, square or wide, with your handle
      hand-lettered in as an optional watermark (from your config; never a built-in
      default).
    - **Choosing between options** — render variations or run the same prompt
      across multiple models, then get a **self-contained comparison gallery**
      showing each image's model, cost, and prompt.
    
    Throughout, the mascot stays on-model via a **reference lock**, every image is
    self-checked against a quality bar (one idea per image, accent restraint, no
    stray titles, fresh metaphor every time), and aspect ratios cover article
    (16:9), social (1:1), and vertical formats.
    
    ## Notes
    
    - This style is intentionally **not** photorealism, logos, UI mockups, charts,
      or generic stock art.
    - Image models approximate exact colors; the skill eyedrops and re-rolls
      off-target palettes.
    
    ## In this repo
    
    The skill lives in this directory (`skills/illo/`). Installers copy it
    verbatim, so only what every install should ship belongs here. Docs-only
    images live in [`_assets/illo/`](../../_assets/illo/) at the repo root
    (linked by raw URL). Proven explainer renders used on the repo README are in
    [`docs/examples/`](../../docs/examples/). Plugin manifests sit at the repo
    root (`.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`,
    `.grok-plugin/`, `gemini-extension.json`).
    
    ## License & credit
    
    MIT © Trevin Chow. Illo — including the **Blot** default character and the
    bundled example artwork — is original work; if you redistribute or build on
    it, please keep attribution. See [`NOTICE`](NOTICE). Characters you create
    with the character builder are, of course, yours.
    
    ---
    
    `SKILL.md` is the agent-facing instructions — you don't need to read it to use
    the skill.
    
  • SKILL.md 51.7 KB
    ---
    name: illo
    description: >-
      Creates original editorial illustrations where a recurring mascot
      character performs the idea — one caught scene by default, a hand-built
      explainer diagram (labeled stages, a fan-out, timeline, loop, or stack) when the
      structure itself is the point, or a transparent character cutout
      (pose-only compositing asset, no scene or text) — in one of seventeen bundled
      looks (sixteen print, plus a photoreal toy-brick set). Also handles
      "surprise me" / "random" (optionally scoped to a focus or character): rolls
      provenance, builds three saying candidates, picks via interactive choice or
      auto-pick-best (`--autopick`), and renders one image. Triggers only when
      the skill is directly invoked or "illo" is requested; never on generic
      illustrate / draw / make-an-image requests.
    # x-release-please-start-version
    version: 0.37.0
    # x-release-please-end
    argument-hint: "[idea or article URL] | build a character | install <character> | surprise me [focus] [--autopick] [using character]"
    author: Trevin Chow
    license: MIT
    metadata:
      hermes:
        tags: [illustration, riso, image-generation, editorial, mascot, codex, grok, openrouter, muse]
        category: creative
        requires_toolsets: [terminal]
      openclaw:
        emoji: "🎨"
        homepage: https://illo-skill.com
        os: [macos, linux]
        requires:
          bins: [python3]
    ---
    
    # Illo
    
    Make original, distinctive editorial illustrations for written content. One
    image explains one idea: a key judgment, a flow, a before/after, a trap, a
    loop. A **recurring mascot** is the one performing the idea in every scene —
    the subject, never decoration. When one idea advances through stages, it can
    be a **mini-comic**: 2–4 panels inside a single image. And when the idea is
    itself a traceable structure — a pipeline, labeled stages, a fan-out, a
    timeline, a loop — it can be an **explainer**: the same mascot and look
    drawing the structure as a hand-built sketch-diagram with arrows and
    callouts (`references/composition.md`, "Two registers" and "Pick the
    diagram type"; editorial scene is always the default). A named pipeline
    or recipe is **labeled stages** inside that register — named phases in
    order, one connected system, pack-solved for this body, never a new look.
    Or a **character cutout**: the mascot alone on a transparent PNG for downstream overlay
    — pose and contact continuity only, no idea, no text, no environment
    (`references/cutout.md`).
    
    This is a configurable house style, not a generic image generator. The
    **methodology is the constant**; the **character pack and palette are the
    parameters** — and a character pack carries its **style** with it: one look
    per pack, chosen from the bundled look library (riso — grainy halftone,
    ink-layer offset, paper grain, one bold softly-rounded outline — plus
    blueprint, woodcut, pixel, clay, manila, chalk, phosphor, enamel,
    gouache, felt, diorama, sketchbook, bricks, fizz, bloom, and snes) or a custom style file. The default mascot is
    **Blot**, a deadpan ink-drop in riso. Palettes come
    from presets, the user's own palette file, or one derived color. Whatever the
    parameters, it is intentionally not a photo — with one deliberate exception, the
    `bricks` look, a toy-brick photography style — not a logo, not a corporate
    infographic, not a formal boxes-and-diamonds flowchart look, not a UI
    mockup. Asking for a flowchart still means labeled stages in the pack's
    look — the formality ban is a look constraint, not a refusal of the word.
    
    ## Use cases — route the request
    
    | The user wants | The path |
    |---|---|
    | **Illustrate an article / post / newsletter / URL** | Steps 0–7: route the source first (thesis → coverage: hero / hero+set / set / mini-comic — `references/composition.md`, "Source routing"), then shot list (hero row + anchors), one image per anchor, interleave by placement. |
    | **One image for a single concept** | Step 1 concept branch (up to ~3 quick questions if the idea is thin), then a single image. |
    | **Surprise / random** — "surprise me", "random", "surprise me with art quote using bray", "surprise me --autopick" | Read `references/surprise.md` in full: Step 0 first, then character + provenance (ignore `defaultCharacter`; `* quote` forces a cited quote; else ~1/3 roll), build **three** safe candidates, interactive picker or auto-pick-best (`--autopick` preferred for schedulers), then register from the locked saying, then Steps 3–7 as one image. Deliver saying + image. Poster titles default off; mini-comics still get per-panel labels. |
    | **A sequence — story beat, before→after, fail→fix** | One **mini-comic** when the progression sits in one place (shape routing in `references/composition.md` — the idea picks the shape, the destination never does). A specified process diagram / flowchart / labeled workflow is labeled stages, not this row. |
    | **A traceable structure** — "show the flow", "as labeled stages", "label the steps", "walk the stages", "diagram the pipeline", "like that factory diagram", "map the steps", "as an explainer", or specified flowchart / labeled-workflow / process-diagram intention | The **explainer register** (`references/composition.md`, "Pick the diagram type" and "The explainer register"): a hand-built labeled-stages / flow / fan-out / timeline / loop / stack / system slice in the active look, the mascot a working part of it. Specified flowchart / labeled-workflow / process-diagram intention locks **labeled stages** in the pack's look — the formal-flowchart ban is a look constraint (no Visio, no title/legend/grid), not a refusal of the word. Labeled stages is a structure type inside explainer, not a new register or look — pack-solve it for the active character before the prompt. BEST when a unit's thesis IS a named pipeline, recipe, or staged process; never the automatic choice for every explainer. |
    | **Social-ready art for X posts / article body images** | 16:9 (or 1:1 when square is explicitly useful), bold `ink-punch`, watermark with the `x` handle if configured or asked. |
    | **X Article banner / hero image** | Use the unique banner format: **1536 × 640 px** when the user asks for an X Article hero/banner. Prompt and render through the normal `illo.py generate` image pipeline, with normal, undistorted character/object proportions and crop-safe breathing room. Do not satisfy this by manually compositing or rebuilding crops from another image unless the user explicitly asks for post-processing. |
    | **Blog / brand / site-matched art** | A named or custom palette, or derive the palette from one dominant color (`references/palettes.md`). |
    | **Their own mascot** — "make me a character", "use our mascot", "replace Blot" | The character builder: read `references/character-builder.md` in full and follow it end to end. |
    | **Community characters** — "what characters are available", "install blip", "install all characters", "update mole", "publish my character" | `references/pack-sharing.md` — engine `packs list/show/install/update`, including `packs install --all`; publish via a GitHub PR. |
    | **A different look** — "in blueprint", "woodcut style", "pixel version of blip" | Styles travel with character packs: build a **style variant pack** via `references/character-builder.md`, "Style variants". |
    | **Options to pick from, or "which model is best"** | Step 5b: `--count` variations or a model loop → `gallery` with a recommendation. |
    | **Fix an existing image** (stray title, recolor, mascot too decorative) | Edit prompts in `references/prompt-recipe.md`, passing the image back as `--ref`. |
    | **Character cutout / transparent PNG / overlay sticker** — "just the mascot", "no background", "paste on something else" | The **cutout register** (`references/cutout.md`): read in full, prompt from `references/prompt-recipe.md` "Cutout variant", generate with `--cutout` and `--aspect 1:1`. OpenRouter cutouts default to GPT Image 2 (not Grok). Not for explaining an idea — reroute to editorial if the ask needs a scene. |
    | **Animated idle / bot avatar / looping GIF of the mascot** | The **cutout register** plus `references/cutout.md`, "Idle loop / bot avatar": one transparent 1:1 cutout with `--cutout` and the character sheet as `--ref`, then programmatic motion on that PNG. |
    
    ## Prerequisites
    
    The engine (`scripts/illo.py`, stdlib Python, no installs) renders through one
    of **three engine backends** plus **two agent-side transports**; `python3` and
    network access are the only hard requirements. **Grok Bot** (Cursor's Grok
    Bot / the Grok desktop assistant) is an agent-side transport: use its built-in
    Grok image tool directly, not `illo.py generate`, when no user config
    explicitly selects an engine backend. **Muse** (Meta's personal assistant,
    Blip) is the other agent-side transport: when *you* are Blip, build the illo
    prompt per this skill and call your native image-generation tool with the
    active character sheet attached as a reference. Other agents that happen to
    expose some image API must not take either native path — the agent must be
    able to call its own built-in image tool *and* be named above.
    
    **Running the engine — set `$SKILL_DIR` inline in each block.** Every engine
    command below is `python3 "$SKILL_DIR/scripts/illo.py" …`. Set `SKILL_DIR` to the
    absolute path of the directory this `SKILL.md` was loaded from (it contains
    `scripts/illo.py` and `assets/`) **in the same command block that uses it** — shell
    state does not persist between separate command runs, so a value set in an earlier
    block is gone by the next. If the harness does not expose that path, find the
    installed `scripts/illo.py` and use its parent; if neither resolves, stop rather
    than guessing the working directory. The engine self-locates its own bundled
    assets, so `$SKILL_DIR` only has to be right enough to launch `illo.py` and to
    point `--ref` at the bundled character sheet.
    
    Write the block **flatten-safe** — some hosts (Codex observed) collapse a fenced
    block to one line, turning a newline into a space. Terminate the assignment with
    `;` (`SKILL_DIR="…";` — without it, a flattened `SKILL_DIR="…" python3 "$SKILL_DIR/…"`
    becomes an env-prefix whose `$SKILL_DIR` expands to empty **before** the assignment
    applies, so the path collapses to `/scripts/illo.py`). Put **no comment on an
    assignment or command line** (a flattened `#` comments out the rest of the line and
    the command silently vanishes), and keep each invocation on **one line** (a
    flattened `\` continuation injects stray arguments). A wrong or unset value makes
    `doctor` (Workflow step 0) fail loudly (`can't open file …/scripts/illo.py`) — the
    signal to fix the path, not a skill fault.
    
    - **Codex backend (free for Codex subscribers).** When the host has a usable
      **Codex CLI** — installed, `codex login`-ed, with the `image_generation`
      feature — illo can generate through the user's Codex subscription at no
      per-image charge (it draws on their Codex quota). No API key, no token: illo
      only shells out to the user's own CLI. Detected, not assumed; gpt-image-2 is
      automatic; unsupported on Windows/WSL.
    - **Grok CLI backend (free for Grok/xAI subscribers).** When the host has a usable
      **Grok CLI** — installed and `grok login`-ed — illo can generate through the
      user's Grok subscription via `grok -p` (headless), drawing on their Grok
      quota. Same env-free, token-free subprocess design as Codex. **Grok returns
      JPEG with no alpha, so it cannot make transparent cutouts** — those auto-fall
      back to a cutout-capable backend. The image tool exposes no model selector.
    - **Grok Bot native transport (agent-side, free for Grok Bot users).** When
      **you are Grok Bot** — specifically Cursor's Grok Bot / the Grok desktop
      assistant with the built-in Grok image tool — build the illo prompt and call
      that tool with the active character's model sheet as a reference image. Do
      not require the Grok CLI, Codex CLI, or an OpenRouter key; do not treat a
      missing engine backend as a reason to run `init`. This is not a generic
      "host image API" rule and not an `illo.py --backend` value.
    - **OpenRouter backend (paid, direct or explicit fallback).** Needs an
      **OpenRouter API key** in the user's config file — the **single credential
      channel** — written once by the user-run `init` (mode 600). The engine never
      reads secrets from the environment and never accepts them as command-line
      arguments. A host without a subscription CLI can select this engine path directly.
      A failed Codex/Grok CLI render does **not** spend money automatically: paid
      fallback requires `--allow-paid-fallback`. It is **model-selectable**
      (`--model`).
    
    Capsule of the backend/transport model (resolution and precedence, the CLI
    requirements, the Grok Bot native path, the built-in image tool being
    automatic, quota vs. charge, cutout limits, Windows/WSL, fallback): **read
    `references/backends.md` in full before choosing or explaining a backend** —
    the mechanics live there, once.
    
    ### Setup is the user's job (never enter the key yourself)
    
    Entering an API key is something the **user** does. Do not type, paste, print,
    or store the user's key — direct them to bootstrap it:
    
    - **Bootstrap (user runs it):** `python3 "$SKILL_DIR/scripts/illo.py" init` —
      prompts for the key at a hidden prompt (never echoed) and writes the
      YAML config `${XDG_CONFIG_HOME:-~/.config}/illo/config.yaml` (mode 600). It
      can also store non-secret defaults: `--model`, `--palette`, `--aspect`,
      `--character`, `--watermark`. Use `--no-key` to update preferences without
      touching the stored key. (The config is read via PyYAML when installed;
      without it a minimal built-in parser still reads the flat keys — `apiKey`,
      `model`, … — so generation needs no installs. Only nested settings like
      `watermark` need PyYAML: `python -m pip install 'PyYAML==6.0.2'`.)
    - **Non-secret prefs may be seeded** for the user with the same command and
      `--no-key`, but the key itself is theirs to enter.
    
    ### Hermes Agent only: binary asset repair preflight
    
    Some Hermes versions corrupt binary files (the bundled character sheets) when
    installing multi-file skills from GitHub — text files survive, binaries don't,
    and a corrupted sheet silently breaks the character lock. **Under Hermes
    Agent**, run this once before first use (and whenever `doctor` reports
    `assets: CORRUPTED`):
    
    ```bash
    bash ${HERMES_SKILL_DIR}/scripts/repair-hermes-assets.sh
    ```
    
    It verifies every bundled binary against known-good SHA256 hashes
    (`assets/checksums.txt`) and re-downloads only mismatched files from pinned,
    immutable URLs — a no-op when everything checks out. Under Claude Code,
    Codex, OpenClaw, or any runtime that installs faithfully: skip this; `doctor`
    checks asset integrity everywhere and will say if repair is ever needed.
    
    ## Read these references as needed
    
    Do not load everything at once. Pull the file that matches the step:
    
    - `references/visual-style.md` — riso, the house default look: the risograph technique, line language, paper/ink, hard do/don'ts.
    - `references/styles/<name>.md` — the rest of the look library (`blueprint`, `woodcut`, `pixel`, `clay`, `manila`, `chalk`, `phosphor`, `enamel`, `gouache`, `felt`, `diorama`, `sketchbook`, `bricks`, `fizz`, `bloom`, `snes`), consumed by character packs. Read the active character's style file in full before generating.
    - `references/character.md` — the character rules (the load-bearing test, anti-complexity guardrails, value-follows-palette, the **interaction model** — declared per pack or derived conservatively from the locked design and reference sheet), the default character **Blot**, and the custom-pack format. Read before any character work.
    - `references/character-builder.md` — the guided flow for designing and installing a user's own mascot. Read in full before building or replacing a character.
    - `references/pack-sharing.md` — installing characters from the community repo and publishing a pack via PR. Read before any install/publish request.
    - `references/palettes.md` — named presets, default resolution, custom palettes, **and the derive-a-palette-from-one-color algorithm**. Read in full before choosing or deriving any palette.
    - `references/composition.md` — the two registers (editorial scene / explainer diagram), the diagram-type picker, the explainer's structure types and budget (including labeled stages, arrow notes, and its pack-solve), stagings, turning an idea into a move, the **anatomy-action feasibility gate** (validate the contact map against the character's interaction model before rendering), the no-recycled-composition rule, and the shot-list format.
    - `references/cutout.md` — the cutout register: transparent compositing assets, contact continuity, pose vocabulary, and generate flags. Read in full before any cutout request.
    - `references/surprise.md` — surprise / random mode: preflight-first, scope parse, random character, provenance variety + three saying candidates (optional parallel verify for sourced modes), interactive picker or `--autopick` / auto-pick-best, full re-roll on refresh, register after the locked saying, saying bar + sense bar, multi-source quote verification, safety-before-offer, headless contract. Read in full before any surprise/random request.
    - `references/backends.md` — the three-backend image engine plus the Grok Bot native transport: how the engine backend resolves (precedence Codex > Grok > OpenRouter, and the self-identify rule), when Grok Bot bypasses `illo.py generate`, the Codex/Grok CLI requirements, artifact-first success, the built-in image tool being automatic (no model selection), quota-vs-charge, Grok's no-cutout limit, Windows/WSL, and opt-in paid fallback. Read before choosing or explaining a backend.
    - `references/models.md` — the model lineup (**OpenRouter backend only**): friendly-name → OpenRouter id map, traits, aspect caveats, 404/fallback handling. Read before passing any `--model`.
    - `references/prompt-recipe.md` — the generation prompt template and the edit/recolor prompts.
    - `references/quality-bar.md` — the post-generation checklist and iteration rules. Read before delivering.
    
    `assets/character-reference.webp` is the default character's canonical model
    sheet — the consistency anchor (used by the engine, below); a custom pack
    brings its own. Style-calibration examples are **not bundled** — each style
    file links its own by URL (fetch when needed): study line density, negative
    space, and accent restraint. **Never copy their compositions** — invent a
    fresh metaphor for the current piece.
    
    ## Workflow
    
    ### 0. Preflight
    
    Before generating, confirm the engine is ready:
    
    ```bash
    SKILL_DIR="<path to this skill>";
    python3 "$SKILL_DIR/scripts/illo.py" doctor
    ```
    
    Run the `illo.py` call standalone — never chained with `&&` — so the displayed exit code is
    the readiness signal itself (0 = ready): a chained neighbor's failure paints
    a healthy check as an error.
    
    It reports python, the config path, the resolved model/palette defaults,
    whether a **custom character pack** or **custom palettes file** exists,
    **Codex/Grok CLI detection and the resolved backend/transport**, and whether an
    OpenRouter key is found (without revealing it); exit 0 = the resolved backend
    is ready. An OpenRouter-only install (no subscription CLI) stays exit 0 —
    readiness follows the resolved backend, not a hardwired key check
    (`references/backends.md`).
    
    **Grok Bot native path (agent-side).** If you are **Grok Bot** (Cursor's Grok
    Bot / the Grok desktop assistant with the built-in Grok image tool) and the
    user has not explicitly chosen `backend: openrouter`, `backend: codex`, or
    `backend: grok`, initialize the agent-side transport before relying on
    `doctor`:
    
    ```bash
    SKILL_DIR="<path to this skill>";
    python3 "$SKILL_DIR/scripts/illo.py" init --backend grok-bot --no-key
    ```
    
    Then run `doctor` normally: exit 0 is meaningful readiness for this path.
    Missing Codex CLI, Grok CLI, or OpenRouter key are not failures when
    `backend: grok-bot`; corrupted assets, unreadable custom packs, malformed
    palettes, or the wrong `SKILL_DIR` still fail and must be fixed before
    rendering. Generate in Step 5 by calling Grok Bot's built-in Grok image tool
    with the active model sheet reference. This route is only for Grok Bot's own
    Grok image tool; other agents with unrelated image tools must use the engine
    backends below.
    
    Short path for Grok Bot: run `init --backend grok-bot --no-key` once when
    backend is unset/auto, run `doctor` for assets/config/packs, use `packs`
    commands normally (including `packs install --all` after install so community
    characters are local), read the same references, build the same prompt, then
    call Grok Bot's built-in Grok image tool with the active character reference.
    Skip `illo.py init` for OpenRouter unless the user explicitly wants OpenRouter
    or another engine backend default, and skip `illo.py generate` unless the user
    explicitly selected an engine backend.
    
    **Muse native path (agent-side).** If you are **Blip** (Meta's personal
    assistant, Muse) and the user has not explicitly chosen an engine backend
    (`backend: openrouter`, `backend: codex`, or `backend: grok`), initialize the
    agent-side transport before relying on `doctor`:
    
    ```bash
    SKILL_DIR="<path to this skill>";
    python3 "$SKILL_DIR/scripts/illo.py" init --backend muse-native --no-key
    ```
    
    Then run `doctor` normally: exit 0 is meaningful readiness for this path.
    Missing Codex CLI, Grok CLI, or OpenRouter key are not failures when
    `backend: muse-native`; corrupted assets, unreadable custom packs, malformed
    palettes, or the wrong `SKILL_DIR` still fail and must be fixed before
    rendering. Generate in Step 5 by calling your native image-generation tool
    with the active model sheet reference. Unlike Grok Bot, this path **can** do
    cutouts: render on the pack's chroma screen and run `illo.py keyout` (see
    `references/cutout.md`). This route is only for Blip's own native image tool;
    other agents with unrelated image tools must use the engine backends.
    
    Short path for Muse: run `init --backend muse-native --no-key` once when
    backend is unset/auto, run `doctor` for assets/config/packs, use `packs`
    commands normally, read the same references, build the same prompt, then call
    your native image tool with the active character reference. Skip
    `illo.py generate` unless the user explicitly selected an engine backend —
    for a native render, record it with `illo.py record` (or `keyout` for
    cutouts) so it joins the run's `manifest.jsonl` and galleries.
    
    **Config migration — surface the backend choice interactively.** When you are
    going to use `illo.py generate`, if `doctor` reports `backend: NEEDS CHOICE`
    (or `generate` hard-stops saying the config "is out of date"), this user's
    config predates the backend choice — they have an older install and have never
    been offered a subscription CLI. Do **not** pick for them silently. Surface an
    **interactive choice** using the platform's
    blocking-question capability (`AskUserQuestion` in Claude Code, the equivalent
    elsewhere; where the host has none — e.g. a plain chat session — ask the same one
    choice as a concise message and wait for the reply, never picking silently):
    "illo now has image backends/transports — which would you like?" with five
    options — **Codex** (free, your Codex subscription), **Grok CLI** (free, your
    Grok subscription; no transparent cutouts), **Grok Bot** (agent-side native
    tool; use only when you are Grok Bot), **Muse** (agent-side native tool; use
    only when you are Blip, Meta's personal assistant), and **OpenRouter** (pick
    the model: Grok Imagine, Nano Banana, GPT Image, and others). Persist the answer without
    touching any existing key:
    `python3 "$SKILL_DIR/scripts/illo.py" init --backend <codex|grok|grok-bot|muse-native|openrouter> --no-key`,
    then continue. A brand-new install (no config at all) is ordinary onboarding,
    not this migration — it does not fire.
    
    **Prefer your own CLI when you are a subscription-CLI agent.** The engine's
    auto-default reads *host* capability (**Codex > Grok > OpenRouter**; it can't
    tell which agent invoked it) — but **you know which agent you are**. So when you
    are a subscription-CLI agent and your own CLI is usable on this host, add your
    own backend flag to `generate` for non-cutout renders: the **Grok CLI agent**
    adds `--backend grok`, the **Codex agent** adds `--backend codex`. This keeps
    "in Grok CLI, generate with Grok" true even on a host that also has Codex, with
    no runtime-sniffing in the engine. Cutouts ignore this (Grok can't make them —
    they auto-fall back). A user's config `backend:` overrides everything.
    Resolution and precedence mechanics: `references/backends.md`.
    
    For Grok Bot, the equivalent self-identify rule happens **before** `generate`:
    when backend is unset/auto, persist `backend: grok-bot` with
    `init --backend grok-bot --no-key` and use the native Grok image tool path
    above. If the user explicitly configured or requested an engine backend, honor
    that choice instead of silently switching to Grok Bot native.
    
    For Blip (Muse), the equivalent rule is the same: when backend is unset/auto,
    persist `backend: muse-native` with `init --backend muse-native --no-key` and
    use the native image tool path. If the user explicitly configured or requested
    an engine backend, honor that choice instead of silently switching to Muse
    native.
    
    Read the printed **config path** before concluding
    the key is missing: under Hermes,
    multi-profile setups can resolve `HOME`/`XDG_CONFIG_HOME` to *another*
    profile's home (e.g. `…/profiles/<name>/home/.config/illo/…`), so a key
    that exists looks absent. If the path points at the wrong profile, re-run
    with the right `HERMES_HOME`/`HOME`/`XDG_CONFIG_HOME` rather than treating
    the key as missing. If the key is genuinely
    **missing**, stop and ask the user to run
    `python3 "$SKILL_DIR/scripts/illo.py" init` themselves — do not enter the
    key for them. In a **chat session** the user can't run commands where they
    are, so shrink their host-side step first: run `init --no-key` yourself
    (allowed — it scaffolds the config with defaults and a commented `# apiKey:`
    placeholder, mode 600, never touching a key), then offer the user two
    equivalent one-time options **on the machine the agent runs on** (that host
    is theirs — it's where they installed the agent): run
    `python3 <resolved absolute $SKILL_DIR>/scripts/illo.py init` (hidden
    prompt), or open `~/.config/illo/config.yaml` and fill in the `apiKey:`
    line. The key must never transit the chat: never ask for it in a message,
    and if the user pastes it anyway, do not use it — tell them to revoke that
    key at openrouter.ai and set a fresh one on the host (the pasted key now
    lives in chat history and platform servers). Never copy a key from the
    environment or any other store into the config yourself — the user is the
    only writer of that line — with **one scoped exception**: an ephemeral
    cloud workspace (Claude Code web, Codex cloud, CI) where the user
    provisioned `OPENROUTER_API_KEY` through the platform's secrets mechanism.
    That provisioning is itself the user's deliberate, workspace-scoped
    consent, and there is no interactive prompt or persistent home for `init` —
    so there, seed the config from the workspace secret once (the "Cloud & CI"
    one-liner in README.md). On a personal machine an ambient env var proves
    nothing about intent (it may belong to other tools) — the rule stands:
    never copy it.
    
    **Optional pack-freshness offer (preflight, consent-first).** When this run
    will render with an installed community pack (`doctor` lists packs; installs
    carry a `.version` stamp), optionally check freshness:
    `python3 "$SKILL_DIR/scripts/illo.py" packs list` flags stale installs
    (`[installed 1.0.0 — 1.0.2 available]`). The check may run here, but the
    **offer fires once the active pack is known** — after Step 2 resolves the
    character (or after surprise mode's character roll), immediately before
    the first render that uses it. If that resolved pack is stale, offer
    **once** — via the platform's blocking-question capability, as
    in the config migration above — to refresh it before rendering, and run
    `packs update <name>` only on an explicit yes (updating overwrites the
    local copy; the hand-edit warning and `--as` alternative are in
    `references/pack-sharing.md`). Never update silently, and never block on
    this: a "no", an offline host, a registry error, or a headless/scheduler
    run (e.g. surprise `--autopick`) all continue with the pinned copy — a pack
    without a declared `## Interaction model` still plans safely via the
    conservative derivation (`references/character.md`). Skip the check
    entirely when no community-installed pack is involved.
    
    ### 1. Read the input — and clarify a thin concept (briefly)
    
    Three kinds of input, handled differently:
    
    - **Surprise / random** ("surprise me", "random", "surprise me with art quote
      using bray", "surprise me --autopick", and close variants) — the ask is
      invent-and-render, not a supplied thesis. **Stop and read
      `references/surprise.md` in full**, run Step 0 first, then resolve character
      and provenance there (ignore `defaultCharacter`; random character when
      unnamed), build three saying candidates and lock one via picker or
      auto-pick-best, pick register from the locked saying, then continue Steps
      3–7 as one image — Steps 0 and 2 are skipped in that render pass because
      preflight and pack are already done. Do not enter the thin-concept Q&A path
      below. A prompt that already names a concrete idea ("illustrate 'you are
      the bottleneck'") is **not** surprise mode even if it also says "surprise
      me".
    - **A URL / article / paste / long post** carries its own context — but
      never generate from the first vivid detail. Route it first
      (`references/composition.md`, "Source routing"): classify the source's
      **shape and genre**, infer the **requested artifact's job** (what this
      image must do for its audience), separate that job from the source's most
      drawable mechanism, **lock the main thesis in one sentence** (a hero locks
      the source/artifact job, not its loudest evidence — the genre guardrails
      say what each genre heroes), then pick the coverage — hero, hero +
      per-section set (the full article job), set, mini-comic, or shot list
      first. Sets need placements: compact sources (a tweet, one
      concept) never yield a set — their multi-beat form is the mini-comic. Pull the **load-bearing moments** —
      the few places that turn on a judgment, a loop, an input→output, a
      before/after, or a trap — never one image per paragraph. The text already
      says what it's about, so don't interrogate the user, with **one
      exception**: a materially multi-beat source (long article, postmortem,
      multi-claim launch) gets a single coverage question before any
      multi-image spend — unless the user already named the coverage. A lone
      image from a multi-beat source is a **hero**, delivered saying so — not
      as coverage of the piece.
    - **A bare concept or one-liner** (e.g. "illustrate 'you are the bottleneck'")
      usually underspecifies the picture. Ask **up to ~3 quick questions — only the
      ones that change the output — then build.** Draw from:
      - the single takeaway (what should the reader conclude?),
      - where it's headed (blog / deck / X post / X article body / X Article banner → sets palette, aspect, pixel normalization, and watermark),
      - the shape: one image (the default), a **mini-comic** (2–4 panels in one
        image — only when the idea itself advances through stages), or several
        separate images — plus any must-include element or constraint. The shape
        follows the idea, never the destination (`references/composition.md`).
    
      Keep it to **one short round**, then proceed. **Skip the questions entirely**
      if the user already gave enough, said "just make it" / "single shot", or
      the answer is obvious from context. Never block a clear request by asking.
    
    ### 2. Resolve the character
    
    **Surprise / random mode:** skip this step — character was already resolved
    in `references/surprise.md` (named pack, or random among installed + Blot;
    never `defaultCharacter`). Continue at Step 3+.
    
    Installed packs live under `${XDG_CONFIG_HOME:-~/.config}/illo/characters/`
    (format and location details: `references/character.md`); `doctor` lists
    what's installed. A user can keep several and pick per run. First match
    wins:
    
    1. **Explicit request** — "use <pack name>", "as <name>": that pack (or the
       shipped default when asked for by name, `blot`). When the word matches no
       pack name, resolve by **approximation**: match it against each installed
       pack's `Aliases:` line and subject (the `character.md` opening line and
       Locked design **Body**) — `doctor` prints names + aliases, so this needs
       no file reads in the common case — and against catalog `description`s
       (`packs list`). So "use ox" finds a pack subtitled an ox (e.g. `yoke`).
       On one clear match, use it and name it; on several, ask which; on none,
       say so before falling through.
    2. **Config default** — `defaultCharacter` from the user config, if set.
    3. **Shipped default** — **Blot** (spec in `references/character.md`, model
       sheet `assets/character-reference.webp`).
    
    Once resolved, read the pack's `character.md` and use its prompt spec, value
    rules, optional **`Cutout chroma:`** compatibility preference, and
    `reference.png` everywhere the default's would be used.
    
    When rerouting an article set to a new character — especially after a weak
    attempt, or for a technical/platform essay — read
    `references/article-set-character-reroute.md` in full before planning or
    rendering. Do the legibility preflight there before spending renders.
    
    If the user wants a *new* character, that is the character builder
    (`references/character-builder.md`); if they want someone else's, packs
    install from the community repo (`references/pack-sharing.md`). Either way,
    install first, then continue here.
    
    ### 3. Plan (shot list) — when asked to plan, or for anything multi-image
    
    If the user wants planning ("where should this be illustrated", "shot list"),
    output a shot list before generating. Per image: placement, the one idea,
    the artifact job, the register (editorial unless the row passes the explainer
    gate), the staging (or structure type — pick per `references/composition.md`,
    "Pick the diagram type"), **what the mascot is doing**, the
    palette, and the text hierarchy — primary read/title when the artifact needs
    one, plus short supporting labels/callouts within the per-register budgets in
    `references/composition.md`. Let the anchor count drive how many (bands and the never-pad
    rule are in `references/composition.md`). When a stretch of the piece advances
    through stages **in one place**, plan a single mini-comic image there instead
    of several — the mini-comic-vs-separate routing is in
    `references/composition.md`.
    
    For article-set character reroutes, add the mandatory preflight fields from
    `references/article-set-character-reroute.md` before any render: section claim,
    visual object/action, and reader mapping. Reject rows that need a private
    metaphor glossary or more than one conceptual substitution.
    
    ### 4. Resolve the palette (the style is the character's)
    
    **Style** is not separately resolvable: the active character's pack carries
    it — the `Style:` line in its `character.md` names a bundled look
    (`references/styles/<name>.md`, riso in `visual-style.md`) or a custom one at
    `${XDG_CONFIG_HOME:-~/.config}/illo/styles/<name>.md`; absent line = riso.
    Blot is riso. For any non-riso style, read its file in full: it supplies the
    STYLE and LINE LANGUAGE prompt blocks, the palette mapping, the character
    treatment, and extra QA checks. A request for the same character in a
    *different* look is a variant-pack build (route table) — never restyle on the
    fly.
    
    **Palette**: read `references/palettes.md` in full and resolve there — it
    holds the resolution order (explicit request, then destination cue via the
    user's palettes file, then config default, then house `ink-punch`), the named
    presets, custom palettes, and the derive-a-palette-from-one-color algorithm.
    End with **concrete hex values**; when the pack's style isn't riso, run them
    through that style's palette mapping.
    
    ### 5. Generate — reference-locked, one metaphor per image
    
    **Cutout branch.** When the request routed to the cutout register, read
    `references/cutout.md` in full first — it covers backend-aware transparency
    (Codex native alpha by default; chroma compatibility for OpenRouter or explicit
    `--chroma`), **registration-locked silhouette** (no ink-layer offset),
    **`--cutout`** /**`--aspect 1:1`**, OpenRouter **`--image-config`**, and manifest
    **`cutout_alpha`** disclosure. Build the prompt from
    `references/prompt-recipe.md`, "Cutout variant" — not the editorial template —
    and omit manual `BACKGROUND:` / output-format instructions; the engine appends
    the contract for the backend that actually runs. Pass `--chroma` only to force
    a compatibility reroll. Use only the character model sheet as `--ref` (no
    editorial style anchor, no watermark). QA against the cutout section of
    `references/quality-bar.md`. Skip the editorial shot-list / thesis steps.
    
    **Editorial and explainer.** When the locked type is labeled stages, run the
    pack-solve scratch in `references/composition.md` ("Labeled stages — skeleton,
    then pack-solve") before writing the prompt — stage list → operator
    stage → contact map → bind; do not invent a look. Build a full prompt per
    image from
    `references/prompt-recipe.md` (scene + structure + communication hierarchy +
    style + the active character's spec + resolved palette hexes + the
    per-register text budget), write it to a file, and render it. **Pass the active character's
    model sheet as `--ref` every time** — that reference conditioning is what
    keeps the mascot on-model; style and palette come from the prompt, so both
    stays swappable. A pack's sheet is born in its own style, so sheet and style
    always match — no cross-style reference juggling. (Under Hermes Agent, the
    asset-repair preflight above must have run before the first `--ref` use —
    a corrupted sheet conditions every render on garbage.)
    
    **Grok Bot native render.** If you are Grok Bot and the native path from Step 0
    applies, do **not** run `illo.py generate`. Use the same full prompt recipe,
    same aspect ratio, same character lock, same style-anchor rule for sets, and
    call Grok Bot's built-in Grok image tool. Attach the active character's model
    sheet as a reference image (`assets/character-reference.webp` for Blot, or the
    pack's `reference.png`); for later images in a set, also attach the accepted
    style anchor image. Ask the tool to save/return the generated file and treat
    that saved path as the engine JSON `.path` equivalent for QA and delivery.
    Grok Bot's image tool is the same Grok image-model class as the Grok CLI
    transport: no model selector, no OpenRouter billing, and no alpha channel.
    Transparent cutouts stay off this path; route them to a cutout-capable engine
    backend instead, or stop and ask for that backend to be configured.
    
    **Muse native render.** If you are Blip (Meta's personal assistant, Muse)
    and the native path from Step 0 applies, do **not** run `illo.py generate`.
    Use the same full prompt recipe, same aspect ratio, same character lock, same
    style-anchor rule for sets, and call your native image-generation tool.
    Attach the active character's model sheet as a reference image
    (`assets/character-reference.webp` for Blot, or the pack's `reference.png`);
    for later images in a set, also attach the accepted style anchor image. Up to
    four native image calls may be batched in one response — beyond that, continue
    in a follow-up. Save each returned file under the run dir, then record it with
    `illo.py record` (see its usage), which appends a `muse-native` manifest row
    with the label and prompt so it joins galleries like engine renders. Treat
    the recorded path as the engine JSON `.path` equivalent for QA and delivery.
    
    Unlike Grok Bot, this path **can** do cutouts: ask the native tool for the
    pack's flat chroma screen (the pack declares `green` or `magenta`), then run
    `illo.py keyout <screen.png> --chroma <green|magenta> --out <final.png>` to
    produce a transparent PNG — see `references/cutout.md` for the chroma
    selection, QA, and the opaque-fallback rule. There is no model selector and
    no OpenRouter billing on this path; `--model` does not apply.
    
    Set `SKILL_DIR` inline (see Prerequisites), and use the bundled sheet as `REF` — or
    the active pack's `reference.png` for a custom character. Add `--model <id>` to
    override the config/default model for this image (OpenRouter backend only):
    
    ```bash
    SKILL_DIR="<path to this skill>";
    REF="$SKILL_DIR/assets/character-reference.webp";
    python3 "$SKILL_DIR/scripts/illo.py" generate --prompt-file /tmp/shot-01.txt --ref "$REF" --aspect 16:9 --out "assets/<slug>-illustrations/01-topic.png"
    ```
    
    For engine renders, `illo.py generate` prints a **JSON line per image**
    (`{path, backend, model, id, cost, width, height, label, prompt}`; `backend` is
    `codex`, `grok`, or `openrouter`, and `model`/`id`/`cost` are OpenRouter-only —
    they are null on a CLI-served record (Codex or Grok). `cost` is null unless
    `--cost` is passed — `gallery` backfills it) and appends the same record to
    `<out-dir>/manifest.jsonl`.
    Read `.path` — it may differ from `--out`: the engine names the file by the
    actual encoding (some models return JPEG bytes, so a requested `.png` lands
    as `.jpg`). Use `.width/.height` to catch a square when 16:9 was requested
    (re-roll). A failed Codex/Grok CLI render stops by default even when an OpenRouter
    key is configured. Add `--allow-paid-fallback` only when the user has explicitly
    approved a pay-per-image retry. Direct `--backend openrouter` renders and the
    intentional Grok-cutout redirect remain direct routes and do not need this flag.
    Generate each image **separately** — never combine ideas into one canvas. Default
    aspect is 16:9; use `1:1` for square social, `9:16`/`4:5` for vertical, and
    `1536:640` for an **X Article banner / hero**. For X Article banners, the
    platform target is **1536 × 640 px**. Generate through the normal image
    pipeline; do not manually composite or rebuild the scene from crops as a
    substitute for an illo render. Check `.width/.height`, and only do final
    post-processing when it is a non-distorting resize/crop that preserves normal
    proportions and all essential information. Never stretch or squash the art to
    force exact dimensions. Pass `--label` for a caption that shows in the gallery.
    
    **Sets read as one artist.** For any multi-image set, the first image that
    **passes the full quality bar** (and, for a hero in a rerouted article set,
    passes the thesis-legibility gate in
    `references/article-set-character-reroute.md`; never anchor on an unvetted
    render — a failed anchor, e.g. an off-palette ground or illegible metaphor,
    would propagate its failure set-wide) becomes the set's **style anchor**: pass
    it as a second `--ref` after the character sheet for every later image in the
    set and for every re-roll of a set member, so line weight, halftone density,
    and flat-vs-dimensional treatment stay consistent throughout. The same trick
    locks style for a one-off: add any finished example as a second `--ref`.
    
    **Model choice (OpenRouter backend only).** `--model` and config `model:` are
    an **OpenRouter-only** axis — on Codex, Grok CLI, Grok Bot native, and Muse
    native the image model is automatic and `--model` does not apply (`references/backends.md`). For
    the OpenRouter path, read `references/models.md` in full before passing any
    `--model` (or whenever the user names a model in plain language or asks for
    "best quality" / "cheapest"): it holds the friendly-name → OpenRouter id map,
    per-model traits, the aspect-ratio caveat, and the 404/fallback handling.
    Resolution is `--model` > config `model` > built-in default.
    
    **Watermark / attribution (optional, off by default).** The skill ships with
    **no** default watermark — the text comes only from the user's `watermark`
    config map (read from the config file) or an explicit request, so installers
    never inherit someone else's handle. The resolution order, the prompt line to
    append, and the two-render caveat are in `references/prompt-recipe.md`.
    
    ### 5b. Batches & comparison (only when it helps)
    
    **Default to ONE image.** Fan out only when the user asks for options/comparison
    or the piece is important enough to be worth it — and **say first what each
    image costs**: on the Codex backend it draws on the user's Codex quota (no
    per-image charge), on Grok CLI or Grok Bot native it draws on the user's Grok
    quota, on Muse native it uses the agent's built-in image tool (no OpenRouter
    billing), and on the OpenRouter backend it bills their OpenRouter account
    (typically under ten cents per image, varying by model). Keep N small (2–4).
    Orchestrate the loop with the engine's primitives:
    
    `newrun` prints a fresh run dir (`/tmp/illo/<runid>`) into `RUN`. Record the user's
    VERBATIM request (URL, pasted text, concept) to `request.txt` — the gallery shows
    it as provenance so anyone can tell what the run was for. Adapt each `generate`
    line below to a real path and run it on its own:
    
    ```bash
    SKILL_DIR="<path to this skill>";
    RUN=$(python3 "$SKILL_DIR/scripts/illo.py" newrun);
    printf '%s' "<the verbatim request>" > "$RUN/request.txt"
    # (a) VARIATIONS — same prompt+model, pick-the-best:
    python3 .../illo.py generate --prompt-file p.txt --ref <ref> --count 4 --label "draft→ship" --out "$RUN/v.png"
    # (b) MODEL COMPARISON — loop the SAME prompt over the chosen models
    #     (full OpenRouter ids from references/models.md):
    for m in <model-id-1> <model-id-2>; do
      python3 .../illo.py generate --prompt-file p.txt --ref <ref> --model "$m" --label "$m" --out "$RUN/$(basename $m).png"; done
    # (c) CONCEPT VARIATIONS — different prompts (different stagings) for one idea:
    python3 .../illo.py generate --prompt-file staging-A.txt --ref <ref> --label "as a funnel" --out "$RUN/a.png"
    python3 .../illo.py generate --prompt-file staging-B.txt --ref <ref> --label "as a crossing" --out "$RUN/b.png"
    
    python3 "$SKILL_DIR/scripts/illo.py" gallery "$RUN" --title "<the piece or request>" --open
    # always pass --title so a saved gallery stays identifiable later;
    # add --embed for a single portable file (images inlined)
    ```
    
    Every `generate` self-records to `$RUN/manifest.jsonl`; `gallery` assembles them
    into one page with each image's **label, model, dimensions, cost, and a
    collapsible prompt** — the prompt toggle is what makes concept-variation
    comparison readable (the prompt is the variable). Always present the gallery
    **with a recommendation**, not a raw dump — and in a chat session, present
    the labeled candidates directly in the chat instead of a gallery (delivery
    routing in step 7). Multi-model failures are per-image
    (an unavailable model errors that one render only); keep the rest.
    
    ### 6. QA and iterate
    
    Check every image against `references/quality-bar.md`. Re-roll or edit when the
    mascot is decorative or off its locked spec, the body is wrong-value for the
    palette, label text sits on a colored fill, the accent has spread past the
    character's accent part + 1–2 elements, an unwanted title bar appears, the
    composition copies an example, or text is misspelled. Subject scale varies
    run-to-run — re-roll if the subject is tiny (check `.width/.height` in the
    JSON: a square back when 16:9 was requested → re-roll). When a re-roll
    supersedes a render, rebuild any delivery gallery with
    `--exclude <superseded label>` (repeatable) so rejected rolls don't appear in
    the review artifact.
    
    ### 7. Deliver — match the session's medium
    
    Copy finals next to the user's work when appropriate; never overwrite
    existing assets without being asked. **Filenames carry the role** — they
    are the only metadata that survives a document attachment, so make them
    self-identifying: `00-hero-<slug>.png` for the hero, then
    `01-<section-slug>.png`, `02-<section-slug>.png`, … for anchors in piece
    order (`assets/<slug>-illustrations/`). Then report: how many images, the
    palette used, which are strongest vs optional — and for any multi-image
    job, a **placement map**: one line per image naming the file, its role
    (hero, or after which section), and the one idea it lands, so the user can
    drop each file where it belongs without re-deriving the plan. Deliver the
    images themselves the way this session can actually show them:
    
    - **Filesystem sessions** (IDE/terminal agents — Claude Code, Codex,
      Cursor): report each final's **absolute path** (the engine's JSON `.path`
      is already absolute) and present the gallery for multi-image runs. The
      file on disk already *is* the original — never emit `[[as_document]]`
      here: it's a Hermes gateway token, literal noise in any other runtime.
      If the runtime has its own in-chat file delivery, use that.
    - **Grok Bot native sessions:** deliver the file returned by Grok Bot's
      built-in image tool inline/as an attachment in chat, and include its saved
      file path in the same role that engine renders use `.path`. The returned
      file is the original for this transport; do not ask the user to configure
      OpenRouter just to retrieve it.
    - **Muse native sessions:** deliver the file returned by your native image
      tool as a `sandbox://workspace/...` link in chat, and include its saved
      file path in the same role that engine renders use `.path`. Record every
      delivered image with `illo.py record` (or `keyout` for cutouts) so the
      run's `manifest.jsonl` and galleries stay complete. The returned file is
      the original for this transport; do not ask the user to configure
      OpenRouter just to retrieve it.
    - **Chat sessions** (the user is on a messaging surface — Hermes over
      Telegram/Discord/WhatsApp, or any chat surface with lossy media delivery —
      and cannot open local files): a path alone is not a complete deliverable;
      the image must land **in the chat**, and a *final* must arrive as the
      **original file**. Platform photo delivery recompresses images — exactly
      what destroys riso grain, halftone texture, ink-layer offset, and fine
      hand-lettering — so **finals are delivered as document attachments**. On
      Hermes, tag each final with an explicit `MEDIA:` attachment tag — the tag
      is `MEDIA:` immediately followed by the absolute path, no space — and the
      literal directive `[[as_document]]` in the same reply. Do **not** rely on
      a bare absolute path for a final: bare paths can pass through to the user
      as literal text instead of being dispatched as an attachment.
    
      ```text
      MEDIA:/absolute/path/to/final.jpg
      [[as_document]]
      ```
    
      Candidate/options rounds may use normal inline photo delivery when quick
      glances help — say so ("preview — original file to follow") — but a
      final is never delivered that way. **Skip the HTML
      gallery in chat** — the user has no easy way to open or host it; send the
      labeled finals directly with the recommendation as text, and only build
      `gallery --embed` (one self-contained file) if a portable artifact is
      explicitly requested, delivering it with `[[as_document]]`.
    
    Before the final reply in a chat session, check:
    
    - every final's path came from the engine's JSON `.path`, not the requested
      `--out` (the actual extension may differ);
    - every final appears as an explicit `MEDIA:/absolute/path` attachment tag
      in the reply;
    - `[[as_document]]` is in the reply unless this is explicitly preview-only;
    - rejected/re-rolled candidates are excluded from delivery;
    - the text says what was made — character, palette, strongest final, and
      for sets the placement map (which file is the hero, which follows which
      section) — without implementation noise.
    
    ## Output discipline
    
    Pre-generation planning is short and concrete. Post-generation, let the images
    speak — report what was made and where, not style theory. Keep labels few and
    short; the fewer words baked into an image, the more reliably it renders.
    
    Talk like a person doing the work, not a recap of this file. Never narrate
    workflow steps or jargon in chat: doctor, preflight, provenance, register,
    saying bar, thesis, backend, or "doctor's green." Status, if any, is ordinary
    speech, not a liturgy of steps. When surprise mode picks an unnamed character,
    introduce the character once in plain English — pack name plus what they are
    ("Inch, the chalk inchworm") — then show the lines and ask which one. Never
    status-ping with the name alone ("Inch."), say "Still Inch," or ask "which one
    should <name> draw?" The user hears the result — character, sayings / image,
    what was made — not the procedure.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.