illo is an agent skill that turns your articles and abstract ideas into original editorial illustrations — starring a recurring character you own. Blot ships in the box and draws in riso; every character carries its own print look. No stock art, no prompt fiddling.
Works in Claude Code, Codex, Hermes, and OpenClaw
you type: /illo many inputs become one decision
you get:
articles in, scenes out
Hand it a post and it finds the load-bearing moments — the judgment, the trap, the before/after — and renders each one as a single scene, or a hand-built explainer diagram when the structure is the point. Not one image per paragraph. The ones that matter.
a cast you own
Every image stars a recurring mascot kept on-model by a reference lock. Use Blot, install a community character, or build your own with the guided character builder — one pack, one look, forever yours.
yours to keep — or share
Characters are just folders you own. Keep yours private, install community characters by name, or — if you want — publish your own to the CI-validated packs repo. One PR, renders embedded, and the skill opens it for you.
same idea, four characters
same character, dressed for the destination
A character defines where its accent lives — never the color. Map a destination to a palette once — one plain-text line in your palettes file, like blog → your site's own colors (read straight from your CSS) — and the same mascot ships in bold fluoro pink on X and in your blog's exact link color on your blog, automatically. Never asked twice.
same idea, two registers
A scene makes the reader feel the idea; an explainer lets them trace it — stations, one flow direction, hand-lettered callouts, never a PowerPoint flowchart. Scenes stay the default. Say "show the flow" to opt in, or let the skill earn the diagram when a piece's whole point is the path.
Single scenes, mini-comics, explainer diagrams, any aspect ratio — in your palette or your brand's, resolved automatically by destination.
Two things to bring:
got the Codex CLI signed in? the second one's on the house
A coding agent with a reasoning model
Claude Code, Codex, Hermes, or OpenClaw — running a capable model like Opus or GPT-5.5. After each image renders, the skill shows it back to your model to check it against the idea and re-roll if it's off — so the model has to both reason and see.
An image backend — your call
Whatever agent you run illo in, the image generation goes through one of two backends under the hood. Codex — got the Codex CLI signed in (it comes with a ChatGPT/Codex plan)? Free: illo drives it to render gpt-image-2, no key, drawing on your Codex usage. OpenRouter — a key for model choice (Grok Imagine, Nano Banana, GPT Image, any by name), about a nickel an image.
# any agent — Claude Code, Cursor, Codex, Copilot, Gemini & friends
npx skills add tmchow/illo-skill --skill illo
# native plugin — updates managed by Claude Code
/plugin marketplace add tmchow/illo-skill
/plugin install illo@illo-skill
# native plugin — update with: codex plugin marketplace upgrade
codex plugin marketplace add tmchow/illo-skill
codex plugin add illo@illo-skill
# extension — update with: gemini extensions update illo
gemini extensions install https://github.com/tmchow/illo-skill
# GitHub CLI — update with: gh skill update illo
gh skill install tmchow/illo-skill illo
# Hermes
hermes skills install tmchow/illo-skill/illo
# OpenClaw
openclaw skills install illo
then try:
# a bare idea
/illo
you are the bottleneck
# a whole post — hero plus inline art
/illo
https://yourblog.com/shipping-discipline hero + 3 images
# add a character pack first
/illo install mole
character pack
# then pick a shape and that character
/illo "Just taught
my kids about taxes by eating 38% of their ice cream" square image
using mole character
Character packs from illo-characters. Install any of them by name — /illo install the anvil character — or keep several and switch per run.
a deadpan ink drop · ships with the skill
a screen-faced robot · the original
a small round bird · ships small, often
a traffic cone · blockers & WIP
a just-sprouted seed · growth & compounding
a bent-wire donkey · batch jobs & steady throughput
a light bulb · ideas & plans
an anvil · hard feedback
a battery · energy & recharge
a plump mole · debugging & root-cause digs
a rubber stamp · approvals & sign-off
an hourglass · deadlines & timeboxes
a stout periscope · observability & monitoring
a round shield · security & guarding prod
a coffee mug · deep work & builds brewing
an inchworm · incremental progress & migrations
a tardigrade · resilience & fault tolerance
a ball-rolling beetle · tech debt & the big refactor
an anglerfish · search & retrieval
a small storm cloud · incidents & outages
an iceberg · estimates & hidden complexity
a closed clam · encapsulation & clean APIs
a placid ox · automation & delegation
a horseshoe magnet · dependencies & lockfiles
a roll of tape · hotfixes & workarounds
an eraser wedge · deleting dead code
a footed colander · triage, signal vs noise
a nesting doll · releases & versioning
a vacuum tube · caching & warm starts
a blank domino · cascading failures
a one-pip die · flaky tests & chance
your character here
Build one with the skill — keep it to yourself, or publish it for everyone.
How →Your characters are yours — built and used locally. Publishing to the community is a bonus step, not a requirement.
1
Say /illo make me a mascot. The character builder interviews you, pressure-tests the design, picks a look with you (riso, blueprint, woodcut, pixel — or your own), and renders model-sheet candidates to choose from.
2
It installs as a local pack — a plain folder on your machine — and every render stars it from then on. Private by default; nothing leaves your computer unless you say so.
3
Say /illo publish my character and the skill opens a PR on the community repo with your sheets embedded for one-glance review. Contribution guide →
The skill itself is free and open source — and whatever agent you run it in, the image generation goes through one of two backends. With a Codex or ChatGPT plan it's free: illo drives your signed-in Codex CLI to render gpt-image-2, no per-image charge — it just draws on your Codex usage. Want a choice of models instead? Run it through your own OpenRouter account — pay-per-image, around a nickel each (6–25¢ by model), a full blog post under $0.50.
Barely. With the Codex CLI signed in, nothing — illo detects it
and asks which backend you want the first time. For OpenRouter,
run
illo.py init once to store
your key in
~/.config/illo/config.yaml
(mode 600); illo never reads it from the environment. The same
config also holds optional defaults you'd rather not repeat:
backend, model, default character, a watermark with your handle.
On the Codex backend it's automatic — Codex's built-in gpt-image-2, no model to pick. On OpenRouter you choose: Grok Imagine by default (in testing, the boldest print texture and strongest character lock at the lowest cost), with Nano Banana 2/Pro, GPT Image, or any image-output model on OpenRouter by name.
No. Characters you build are local folders on your machine — private by default. Publishing to the community repo is optional, and you keep authorship and credit when you do.
Anything that speaks the Agent Skills format (SKILL.md): Claude Code, Hermes, OpenClaw, and friends. The engine is a
single stdlib Python script — no installs beyond
python3.