# 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

## 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 moves through stages
- **Explainer diagrams** — hand-built flows, timelines, loops 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.

Use the illo skill when the user asks for:

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

## Install

Use one of these, depending on the agent runtime:

```sh
npx skills add tmchow/illo-skill --skill illo
```

```text
/plugin marketplace add tmchow/illo-skill
/plugin install illo@illo-skill
```

```sh
codex plugin marketplace add tmchow/illo-skill
codex plugin add illo@illo-skill
```

```sh
grok plugin marketplace add tmchow/illo-skill
grok plugin install tmchow/illo-skill --trust
```

```sh
gemini extensions install https://github.com/tmchow/illo-skill
gh skill install tmchow/illo-skill illo
hermes skills install tmchow/illo-skill/illo
openclaw skills install illo
```

## 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 three; 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 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.
  - 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/Grok 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 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 advances through stages in one place. Use an **explainer diagram** only when the user asks for flow/structure or when the concept depends on sequence, causality, or transformation. 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 an OpenRouter key. Run `illo.py init` to configure OpenRouter when no subscription CLI is signed in.
- A failed Codex/Grok 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

The illo skill does not currently expose a public MCP server or WebMCP tool. The agent-native interface is the installed skill itself. A future MCP would be useful for actions such as listing packs, installing packs, validating character folders, rendering images, and opening publish PRs.