# illo

> Agent skill for turning articles, posts, and abstract ideas into original editorial illustrations with a recurring character.

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
Characters JSON: https://illo-skill.com/characters.json

## What illo does

illo is an Agent Skills-format skill. It reads a short idea, a social post, or a full article and renders editorial illustrations: hero images, inline article art, square social images, and hand-built explainer diagrams. Images star a recurring character, and each character pack owns its own print look.

Use illo 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
- an explainer diagram when the structure or flow matters
- 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
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:
  - Codex backend: uses a signed-in Codex CLI and its built-in image generation. No separate API key.
  - OpenRouter backend: uses an OpenRouter key stored by `illo.py init` in `~/.config/illo/config.yaml` with mode 600.

## First commands

```text
/illo you are the bottleneck
/illo https://yourblog.com/shipping-discipline hero + 3 images
/illo install mole character pack
/illo "Just taught my kids about taxes by eating 38% of their ice cream" square image using mole character
/illo show the flow for how feature flags move from local dev to production
```

## Characters

Blot ships with the skill. Community character packs live in `tmchow/illo-characters`.

Useful character names on the site include:

- blot: deadpan ink drop; riso; ships with the skill
- blip: screen-faced robot; riso
- pip: small round bird; riso
- cone: traffic cone; riso
- sprout: just-sprouted seed; riso
- bray: bent-wire donkey; riso
- cadence: robot fitness coach; riso
- lumen: light bulb; blueprint
- anvil: anvil; woodcut
- volt: battery; pixel
- mole: plump mole; clay
- stamp: rubber stamp; manila
- lapse: hourglass; chalk
- scope: stout periscope; phosphor
- boss: round shield; enamel
- brew: coffee mug; gouache
- inch: inchworm; chalk
- grit: tardigrade; pixel
- heft: ball-rolling beetle; woodcut
- lure: anglerfish; phosphor
- squall: small storm cloud; chalk
- berg: iceberg; blueprint
- clam: closed clam; gouache
- yoke: placid ox; blueprint
- tug: horseshoe magnet; enamel
- patch: roll of tape; manila
- scrub: eraser wedge; clay
- sift: footed colander; pixel
- nona: nesting doll; woodcut
- stoke: vacuum tube; phosphor
- clack: blank domino; chalk
- dice: one-pip die; pixel
- quill: baby hedgehog; felt
- plume: baby owl; felt
- posy: flower-bud sprite; felt
- pleat: soup dumpling; felt

For a machine-readable list, fetch `/characters.json`.

## Output guidance

Prefer one strong visual metaphor over many props. Use scenes by default. Use an explainer diagram only when the user asks for flow/structure or when the concept depends on sequence, causality, or transformation.

Character packs couple the character with its visual look. Do not treat style as freely swappable between characters.

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.

## Troubleshooting

- If no image backend is configured, use Codex if the Codex CLI is signed in; otherwise run `illo.py init` and configure OpenRouter.
- 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 publishing a character, keep private characters local unless the user explicitly wants a community PR.

## MCP status

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