# When to use illo skill

This is the agent-instruction file for **illo skill**. HTML: https://illo-skill.com/agent-instructions
Canonical short reference: https://illo-skill.com/llms.txt
Developer index: https://illo-skill.com/developers

## 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 illustration for a blog post, essay, changelog, or abstract claim — one mascot performing the idea
- A hero image plus inline images for a long article (`/illo <url> hero + 3 images`)
- A visual metaphor for a technical or strategic idea (bottlenecks, tradeoffs, scope creep)
- A 2–4 panel mini-comic when the idea is a story beat (fail→fix, before→after)
- An explainer diagram when the user needs labeled stages, a flow, fan-out, timeline, loop, stack, or system slice they can trace
- A transparent character cutout / sticker to overlay on slides or other designs
- An X Article banner at 1536 × 640
- A surprise / random image when they have no thesis (`/illo surprise me`, `--autopick` for schedulers)
- Installing or building a recurring character pack so later images stay on-model

## When not to use this

- Photoreal product photography, headshots, or editing an existing image the user already has
- Video, motion, or animation
- Looking up stock art, brand logos, or someone else's copyrighted characters
- Calling a hosted HTTP **image** API — **illo-skill.com does not expose one**. Public GETs are the character catalog (`/characters.json`, `/api/characters`), OpenAPI (`/openapi.json`), and a catalog-only MCP at `/mcp`. There is no auth token, webhook, or render endpoint. Install the skill and run it locally.
- Generic "make a picture" asks that need a different generator the user already named (Midjourney, a site's own image tool, etc.) unless they also asked for illo's characters or editorial register

## How an agent should call this

1. If the skill is not installed, use **this host's native plugin or skill manager**. That preserves the runtime's update path. Use `npx skills add` only when the host has no native lane. Same table as the [GitHub README](https://github.com/tmchow/illo-skill#install) and https://illo-skill.com/#install:

   | 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** | Paste into Grok Bot (not a terminal command): `Install the illo skill and all community characters.` then `npx skills add tmchow/illo-skill --skill illo -g -y` |
   | **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` |
2. If no image backend: use signed-in Codex CLI or Grok CLI, Grok Bot, or `illo.py init` for OpenRouter. Never spend OpenRouter automatically — `--allow-paid-fallback` only with explicit user permission.
3. Invoke: `/illo <idea>` for a scene; add `mini-comic`, `explainer diagram`, `cutout`, `surprise me`, or `X Article banner` when the user wants that register.
4. Characters: fetch https://illo-skill.com/characters.json (or `GET /api/characters`, or the catalog MCP tools) and `/illo install <name> character pack` when needed.

The full procedure is the skill's own `SKILL.md` after install. This file only answers *whether* and *how* to reach for it.