Illo

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, 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"; editorial scene is always the default). 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, and bloom) 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 flowchart, not a UI mockup.

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. | | A sequence — process, 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 traceable structure — "show the flow", "diagram the pipeline", "map the steps", "as an explainer" | The explainer register (references/composition.md, "The explainer register"): a hand-built flow / fan-out / timeline / loop / stack / system slice in the active look, the mascot a working part of it. Also reachable without the phrases when a unit's thesis IS the structure (the register gate). | | Social-ready art | 16:9 (or 1:1), bold ink-punch, watermark with the x handle if configured or asked. | | 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", "update mole", "publish my character" | references/pack-sharing.md — engine packs list/show/install/update, 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. |

Prerequisites

The engine (scripts/illo.py, stdlib Python, no installs) renders through one of two backends; python3 and network access are the only hard requirements.

• 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.

• OpenRouter backend (the universal 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. This is the path on any host without Codex, and the fallback when Codex fails. It is model-selectable** (--model).

Capsule of the backend model (resolution, the Codex-CLI requirement, gpt-image-2 automatic, quota vs. charge, 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/.md — the rest of the look library (blueprint, woodcut, pixel, clay, manila, chalk, phosphor, enamel, gouache, felt, diorama, sketchbook, bricks, fizz, bloom), 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 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) and the explainer's structure types and budget, stagings, turning an idea into a move, 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/backends.md — the dual image engine: how the backend resolves, the Codex-CLI requirement, gpt-image-2 being automatic (no model selection), quota-vs-charge, Windows/WSL, and OpenRouter as the universal 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:

python3 "$SKILL_DIR/scripts/illo.py" doctor

Run it 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 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 Codex CLI) stays exit 0 — readiness follows the resolved backend, not a hardwired key check (references/backends.md).

Config migration — surface the backend choice interactively. 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 Codex. Do not pick for them silently. Surface an interactive choice using the platform's blocking question tool (AskUserQuestion in Claude Code, the equivalent elsewhere): "illo now has two image backends — which would you like?" with two options — Codex (free, uses your Codex subscription; draws on your Codex quota) 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 --no-key, then continue. A brand-new install (no config at all) is ordinary onboarding, not this migration — it does not fire.

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//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 /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.

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

Two kinds of input, handled differently:

• 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, separate the source's rhetorical job from its most drawable detail, lock the main thesis in one sentence (a hero locks the source's 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 / X / deck → sets palette, aspect, 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, neve

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tmchow
• Source: tmchow/illo-skill
• License: MIT
• Homepage: https://illo-skill.com

Install and usage instructions live in the source repository linked above.