# illo skill > Agent skill for turning articles, posts, and abstract ideas into original editorial illustrations with recurring characters. Site: https://illo-skill.com/ Skill repo: https://github.com/tmchow/illo-skill Character packs: https://github.com/tmchow/illo-characters Examples: https://illo-skill.com/examples.html Guide: https://illo-skill.com/guide.html Characters page: https://illo-skill.com/characters.html Characters JSON: https://illo-skill.com/characters.json Developer resources: https://illo-skill.com/developers OpenAPI: https://illo-skill.com/openapi.json Character catalog: https://illo-skill.com/characters.json Catalog API: https://illo-skill.com/api/characters MCP (catalog lookup): https://illo-skill.com/mcp MCP server.json: https://illo-skill.com/server.json MCP server card: https://illo-skill.com/mcp/server-card Well-known MCP: https://illo-skill.com/.well-known/mcp API catalog (RFC 9727): https://illo-skill.com/.well-known/api-catalog CLI pointer: https://illo-skill.com/cli.json Agent instructions: https://illo-skill.com/agent-instructions.md About: https://illo-skill.com/about Contact: https://illo-skill.com/contact Privacy: https://illo-skill.com/privacy ## When to use this Reach for the illo skill when the user wants an original illustration of an idea, not a search for existing artwork. Best-fit jobs: - editorial illustrations for writing, posts, or abstract concepts - a repeatable mascot/character style instead of stock art - a hero image plus inline article images - a visual metaphor for a technical or strategic idea - a surprise / random image (optionally scoped to a focus or character; `--autopick` for schedulers) - an explainer diagram when the structure or flow matters (a flowchart locks labeled stages) - a character cutout or transparent mascot sticker for slides or compositing - an X Article banner / hero at 1536 × 640 - custom character packs for a personal or team visual system How an agent should call this: install with **this host's native plugin or skill manager** (table below — Claude Code, Codex, Grok CLI, Grok Bot, Gemini CLI, Copilot/GitHub CLI, Hermes, OpenClaw, Cursor). Use `npx skills add` only as last resort. Confirm an image backend, then invoke `/illo ` or matching natural language. Install character packs by name from https://illo-skill.com/characters.json (or `GET /api/characters`). There is no image-generation HTTP API — do not invent `/api/render` URLs. ## When not to use this - Photoreal product shots, headshots, or editing an existing photo - Video or animation - Stock-art search or someone else's copyrighted characters - A hosted image-generation API, webhook, OAuth, or checkout — this origin does not expose those. Catalog lookup is public; rendering is the installed skill. ## What the illo skill does illo skill is an Agent Skills-format agent skill. It reads a short idea, a social post, or a full article and renders in one of four registers: - **Editorial scenes** (default) — one caught moment; the mascot performs the idea - **Mini-comics** — 2–4 panels in a single image when the idea is a story beat (fail→fix, before→after) - **Explainer diagrams** — one register for labeled stages, flow, fan-out, timeline, loop, stack, or system slice when the structure is the point - **Character cutouts** — transparent PNG of the mascot alone for downstream overlay (pose only, no scene or text) It also has a **surprise / random mode** for invent-and-render asks ("surprise me", "random"): rolls provenance, builds three saying candidates, lets the user pick or auto-picks with `--autopick`, then renders one image plus a caption-ready line. Images star recurring characters; each character pack carries its own bundled print look. ## Install Prefer the host's **native plugin or skill manager** — same lanes as the [GitHub README](https://github.com/tmchow/illo-skill#install). Use `npx skills add` only when the host has no native lane. | Platform | Install | |---|---| | **Claude Code** | `/plugin marketplace add tmchow/illo-skill` then `/plugin install illo@illo-skill` | | **Codex** | `codex plugin marketplace add tmchow/illo-skill` then `codex plugin add illo@illo-skill` | | **Grok CLI** | `grok plugin marketplace add tmchow/illo-skill` then `grok plugin install tmchow/illo-skill --trust` | | **Grok Bot** | Open https://x.ai/bot/y3uTGY5hkl6iTmE-ZAX02 and add the shared illo template | | **Gemini CLI** | `gemini extensions install https://github.com/tmchow/illo-skill` | | **Copilot / GitHub CLI** | `gh skill install tmchow/illo-skill illo` | | **Hermes** | `hermes skills install tmchow/illo-skill/illo` | | **OpenClaw** | `openclaw skills install illo` | | **Cursor** | `npx skills add tmchow/illo-skill --skill illo` (Cursor Marketplace listing pending review) | | **Other agents / last resort** | `npx skills add tmchow/illo-skill --skill illo` | Grok Bot template: ```text https://x.ai/bot/y3uTGY5hkl6iTmE-ZAX02 ``` Open the link, then Add to Grok Bot to create your own bot from the shared illo template. ## Requirements - A coding agent that can read a `SKILL.md` file and run local scripts. - Python 3. The engine is a single stdlib Python script. - An image backend (one of four; resolved by host capability, or pinned with `--backend`): - Codex backend: uses a signed-in Codex CLI and its built-in image generation (gpt-image-2). No separate API key. - Grok CLI backend: uses a signed-in Grok (xAI) CLI and its built-in image generation. No separate API key. Cannot produce transparent cutouts — cutout renders redirect to Codex or OpenRouter. - Grok Bot backend: uses Grok Bot's built-in Grok image tool. No Grok CLI and no OpenRouter key. Cannot produce transparent cutouts — cutout renders redirect to Codex or OpenRouter. - OpenRouter backend: uses an OpenRouter key stored by `illo.py init` in `~/.config/illo/config.yaml` with mode 600. Model-selectable. Also the opt-in paid fallback when a Codex CLI, Grok CLI, or Grok Bot render fails — only with `--allow-paid-fallback` (never automatic spend). ## First commands ```text /illo you are the bottleneck /illo https://yourblog.com/shipping-discipline hero + 3 images /illo surprise me /illo surprise me with art quote --autopick using bray /illo install mole character pack /illo install all character packs /illo update all character packs /illo how a book gets published explainer diagram /illo using Blip, make a flowchart of how a newsletter issue ships /illo blot cutout waving /illo X Article banner for this post ``` ## Characters Blot ships with the skill. Community character packs live in `tmchow/illo-characters` — **57 community packs** across **17 looks** as of the site catalog (58 mascots including Blot). Fetch the machine-readable list: `https://illo-skill.com/characters.json` Browse the human gallery: `https://illo-skill.com/characters.html` Build your own: `https://illo-skill.com/characters.html#build-character` — say `/illo build a character` for the interactive builder, or fork illo-characters for a repo-native workflow. ## Output guidance Prefer one strong visual metaphor over many props. Use **editorial scenes** by default. Use a **mini-comic** when the idea is a story beat (fail→fix, before→after) in one place — not a named pipeline. Use an **explainer diagram** when the user asks for flow/structure or when the thesis is labeled stages, a flowchart, a timeline, or another traceable type. Specified flowchart / labeled-workflow intention locks labeled stages inside explainer. Use a **character cutout** only when the deliverable is the mascot alone for overlay — not when the ask needs to explain an idea. Route **surprise / random** asks through surprise mode (not the thin-concept Q&A path): three candidates, picker or `--autopick`, one image + saying. Character packs couple the character with its visual look. Do not treat style as freely swappable between characters. Looks in the catalog include riso, blueprint, woodcut, pixel, clay, manila, chalk, phosphor, enamel, gouache, felt, diorama, sketchbook, bricks, fizz, bloom, and snes. For destination-specific colors, map the target destination to a palette once, often from the destination CSS, then keep the same character and accent placement. For an **X Article banner / hero**, use **1536 × 640** (`1536:640`). ## Troubleshooting - If no image backend is configured, the engine resolves in order: a usable Codex CLI, else a usable Grok CLI, else Grok Bot host capability, else an OpenRouter key. In Grok Bot, the skill follows its `init --backend grok-bot --no-key` path after install; outside Grok Bot, run `illo.py init` to configure OpenRouter when no subscription CLI is signed in. - A failed Codex CLI, Grok CLI, or Grok Bot render does not spend OpenRouter money automatically — pass `--allow-paid-fallback` only when the user explicitly permits a paid retry. - If a render is off-concept, rerun with a tighter description of the idea and the desired output shape. - If a character is unavailable, install its pack by name from `tmchow/illo-characters`. - If sharing a character, keep private characters local unless the user explicitly wants a community PR. ## MCP status A **catalog-only** Streamable HTTP MCP lives at https://illo-skill.com/mcp. Tools: `list_character_packs` and `get_character_pack`. They read https://illo-skill.com/characters.json. They do **not** generate images, install packs, or open PRs. Discovery files: - https://illo-skill.com/server.json - https://illo-skill.com/mcp/server-card - https://illo-skill.com/.well-known/mcp - https://illo-skill.com/.well-known/mcp/server-card.json - https://illo-skill.com/.well-known/ai-catalog.json - https://illo-skill.com/.well-known/api-catalog Rendering still happens via the installed skill. ## CLI The engine is `illo.py` in https://github.com/tmchow/illo-skill (`skills/illo/illo.py`). Machine pointer: https://illo-skill.com/cli.json. There is no npm, PyPI, or Homebrew package that calls illo-skill.com to render images. After install, invoke `/illo ` or `illo.py init` for OpenRouter.