Icons8 — Agent Skills

Ten Agent Skills that give coding agents taste, first when picking Icons8 artwork and then when looking at what they built with it. icons8 and ouch keep a project on one consistent set instead of a pile of mismatched pieces; the seven that follow check the finished screen and fix what they find from the same catalogue. illustration-animator brings static SVG illustrations to life as looped Lottie animations.

Ships as a Claude Code plugin that bundles the Icons8 MCP server (420,000+ icons across 132 styles). Installing it is the whole setup: sign in through the browser once on first use, and search and high-res PNG are free from there. No API key to paste.

Why

The MCP server is a thin wrapper over the Icons8 search API. It gives an agent a handful of tools and no judgement, and the default behaviour fails in three specific ways:

1. Unfiltered search returns one metaphor in ten styles. Asking for delete twelve times returns the same trash can in twelve different packs — one idea, no alternatives, and whatever gets picked won't match the icon picked five minutes earlier.
2. Ranking is not taste-ranking. settings puts four Apple logos above the plain gear; dashboard puts a car dashboard gauge first. The API matches names and tags — it doesn't know you're building a settings screen.
3. SVG is the slow, paid path. One call per icon, and payloads run from 600 characters to 46,000. PNG previews are free, instant, and need no MCP call at all.

The skill fixes all three: it lists every concept a screen needs before searching, picks one pack for the whole project and locks it in icons8.json, filters every search by that pack so results are ten different metaphors instead of ten styles of one, rejects the brand logos and machine parts that search ranks first, previews on a free PNG contact sheet, and fetches SVG only for the approved final set.

Examples

Ask in plain words. The skills trigger by intent, so you do not have to name them.

• "Add icons to this dashboard, one consistent Icons8 set, 24px."
• "Illustrate the empty states with one Ouch! style."
• "Put an animated illustration in the hero of this landing page."
• "Check this screen: emoji icons, missing images, contrast."
• "Review the button labels and error messages on this signup form."
• "Animate the illustrations in styles/little: looped Lottie and MP4."

Install

Claude Code

/plugin marketplace add icons8/agent-skills
/plugin install icons8@icons8

That registers both the skill and the Icons8 MCP server. Approve the server on first use, sign in when the browser opens, and start asking for icons. /mcp signs in again later if you need it.

OpenAI Codex

codex plugin marketplace add icons8/agent-skills

Then install icons8 from the plugin browser (/plugins, or the Plugins section in the Codex app). The skill triggers by intent — just ask for icons; slash commands are Claude Code-only.

The plugin bundles the MCP server here too, so installing it registers icons8mcp — check with codex mcp list, and sign in with codex mcp login icons8mcp. .codex-plugin/plugin.json points mcpServers at the root ./mcp.json, the file every Agent Plugins v1 client reads. Claude reads its own .mcp.json instead. Both files declare the same server, and CI fails if their URLs differ.

On an older Codex that doesn't read mcpServers from a plugin manifest, add it yourself:

codex mcp add icons8mcp --url https://mcp.icons8.com/mcp/

or in ~/.codex/config.toml:

[mcp_servers.icons8mcp]
url = "https://mcp.icons8.com/mcp/"

Either way the server has to be there: icon ids come from search_icons and nowhere else, so without it the skill reports that it isn't connected rather than guessing an id.

Cursor

Cursor installs plugins from marketplaces. .cursor-plugin/plugin.json is the Cursor manifest, and .cursor-plugin/marketplace.json lists the plugin from the repository root. A team can import this repository as a team marketplace and install icons8 from it.

Cursor finds the skills in skills/. It reads the Icons8 server from both mcp.json and .mcp.json; both files name it icons8mcp, so Cursor lists one server. Sign in with Connect on the server when Cursor asks.

GitHub Copilot CLI

copilot plugin marketplace add icons8/agent-skills
copilot plugin install icons8@icons8

Copilot CLI reads the marketplace from .claude-plugin/marketplace.json and installs the plugin in the Agent Plugins v1 format: the ten skills and the Icons8 server. copilot mcp list shows icons8mcp under the plugin servers.

Any Agent Plugins v1 client

The repository root is a conforming Agent Plugins v1 package: plugin.json is the portable manifest, mcp.json declares the Icons8 server, and skills/ is the location the spec fixes for skill discovery. Clients on the compatible clients list pick up both the skill and the server from those files.

In VS Code, no marketplace is needed — run Chat: Install Plugin From Source from the Command Palette and paste the repository URL. What Copilot CLI installs also shows up in VS Code.

.claude-plugin/, .codex-plugin/ and .cursor-plugin/ keep their manifests, because Claude Code isn't on the compatible-clients list yet, and Codex and Cursor read their own. Codex points mcpServers at the root mcp.json. Claude reads .mcp.json, which declares the same server as http: the Claude directory, chat and Cowork accept http and reject the streamable-http name that Agent Plugins v1 requires.

Any agent via npx

Using the community skills installer (installs the bare skill, not the plugin/marketplace):

npx skills add icons8/agent-skills --skill icons8 -a claude-code
# -a codex to target Codex instead, or '*' for every detected agent; add -g for a global install

This route installs the skill alone, so no MCP server is registered — add it for your client following the icons8-mcp README. Until you do, the skill has nothing to search and will say so.

Pick your plan

Free high-res PNG — what the plugin bundles, once you sign in. The server exposes search_icons, list_categories, list_platforms, get_icon_png_url and get_icon_animation, which is everything the skill needs to choose a pack, build the contact sheet, and prototype straight from https://img.icons8.com/?id=…&format=png&size=24. Free icon usage requires attribution — see the Icons8 license.

Animated icons come through get_icon_animation: gif and apng are free, Lottie counts as a paid download. The skill keeps icons static by default and lets one play once on a click or a hover, half a cycle each way on a toggle such as like, or while something loads; never on a loop, and with motion that matches the action.

Full SVG access — subscribe for $15. There is no second setup: the account you already signed in with carries the plan, and get_icon_svg appears alongside the others. The skill's final step then inlines real SVG for the approved set. If the agent still hands back PNG, sign in again so it picks up the new plan — /mcp in Claude Code, codex mcp login icons8mcp in Codex, Connect in Cursor.

A client without OAuth — send an API key instead. The MCP tab of your Icons8 account has the snippet with your key already in it, or write the header by hand:

{
  "mcpServers": {
    "icons8mcp": {
      "type": "http",
      "url": "https://mcp.icons8.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

In Claude Code the same thing is one command:

claude mcp add --transport http icons8mcp https://mcp.icons8.com/mcp/ \
  --header "Authorization: Bearer YOUR_API_KEY"

A key skips the browser entirely, which is what you want on a build server or in CI where nobody is around to sign in. If you set this up with a key before, leave it alone — it still works.

Without a paid plan the skill stays on the PNG path, which is its recommended path for prototyping regardless of plan.

What's inside

plugin.json                   # Agent Plugins v1 manifest — the portable one
mcp.json                      # the server in Agent Plugins v1 format (streamable-http): Codex, v1 clients
.mcp.json                     # the same server in Claude's format (http): Claude Code, chat, Cowork
.claude-plugin/               # Claude manifest, marketplace, and the directory listing icon
.codex-plugin/                # Codex manifest
.cursor-plugin/               # Cursor manifest and marketplace
.agents/plugins/              # Agent Plugins marketplace entry
skills/icons8/
├── SKILL.md                  # the loop, the rejection rules, criteria by context, gotchas
└── references/
    ├── PACKS.md              # which pack for which job, outline+filled pairs, coverage numbers
    ├── VOCABULARY.md         # concept → commonName map, verified visually, plus the traps
    ├── KITS.md               # ready concept lists: SaaS UI, landing, ecommerce, dev docs, analytics
    └── ANIMATION.md          # when an icon may move, motion that matches the action, play-once Lottie
skills/ouch/
├── SKILL.md                  # the sequence, hard rules, the priority ladder, gotchas
├── references/
│   ├── STYLES.md             # the 43-style first tier, the free tier in full, styles by surface
│   ├── SLOTS.md              # slot kits per project type, thin subjects
│   ├── VOCABULARY.md         # state → search query map, measured against the live server
│   ├── LAYOUT.md             # the browser measurements behind the layout rules
│   └── ANIMATION.md          # when a slot earns motion, formats, the source order that plays
└── scripts/measure.py        # ground line, mass offset, saturation: one source of the formulas
skills/icons8-design/         # front door: routes a design request to the skill that owns it
skills/asset-check/           # four mechanical checks on what is on the page
skills/ux-check/              # behaviour, the six states, flows, the accessibility floor
skills/ux-writing/            # every string a user reads, with before/after patterns
skills/ui-polish/             # visual finish: radii, icons, contrast, focus, state styling
skills/motion/                # whether it should animate at all, then every timing value
skills/design-tokens/         # bootstrap a token system, then catch drift in counts
skills/illustration-animator/
├── SKILL.md                  # setup, the three steps, hard time limits
├── references/               # analyze, create, verify, the judge, scene format, style rules
├── engine/                   # Node engine: SVG + scene → Lottie, GIF, MOV, MP4; script checks
└── examples/                 # walking and masking reference scenes

Reference files load on demand, so the cost of having them is close to zero until they're needed.

The four manifests describe the same plugin for four packaging formats, so version and description have to move together. The server is declared in mcp.json and in .mcp.json, one file per format, and the two URLs have to match.

Checking what the agent built

Fetching the right icon is half the job. The other half is what happens to it on the page, and that is what the rest of the skills do.

asset-check is the cheap one and runs on its own once a UI is built or changed: emoji standing in for icons, sections that should carry a picture and carry none, dead placeholder images, and icon imports whose names no longer exist in the library (that last one works on projects that use no Icons8 asset at all). Five more go deeper, one territory each, and icons8-design is the front door that picks between them so a narrow question does not load all of them.

Two properties make them usable rather than noisy. Every rule two skills could raise has exactly one named owner, so one defect produces one finding. And when several run together the reports merge into a single table with one verdict instead of five stacked lists.

They fix as well as report: where a finding is about an icon or an illustration, the replacement comes from the catalogue through the MCP, already in place.

icons8 and ouch do not reference any of this. Asking for an icon stays a one-skill job.

The lock file

One pack per project is the whole point, and it has to survive across sessions and across agents. The skill writes icons8.json next to the project and treats it as binding — no second pack, not even for one extra icon:

{
  "version": 2,
  "icons": {
    "pack": "m_outlined",
    "sizes": [16, 20, 24],
    "color": "currentColor",
    "items": { "settings": { "id": "82535", "commonName": "settings" } }
  },
  "illustrations": {
    "style": "notion-line-art",
    "slots": { "hero": { "id": "6a3d01f2fae3aa473512807f", "file": "assets/hero.svg" } }
  },
  "tokens": { "iconColor": "--foreground", "accent": "--primary", "radius": "--radius" }
}

One file for the whole project: the icon pack, the sizes in use, the illustration style with its slots, and the names of the CSS variables assets are wired to. A lock written in the older shape (pack at the top level) is still read as it was, and a separate ouch.json from earlier releases is folded in on the next write rather than deleted.

Commit it. The next session picks up where this one left off.

Illustrations: the ouch skill

The same discipline for Ouch! illustrations: hero images, empty states, onboarding, 404s and docs spots, from a catalog of 348 styles. What it enforces, each rule earned in test runs rather than declared:

• The picture is about the product, not about the interface. Every slot query carries the product's own noun. Empty states show the missing container (an empty pot for a plant app), never a happy owner of the thing the heading says is absent.
• One style per project, locked in icons8.json under illustrations, with named escapes: an existing page's style always wins, and a public repo filters to free_distribution: true.
• A first-tier shortlist of 43 styles picked by the Icons8 side: a preference with named exits, not a fence. Subject coverage outranks tone, and the skill's priority ladder says in which order the rules give way.
• Contrast gate for non-white backgrounds, and layout rules measured in real browsers: absolute box heights, max-height never upscales a small SVG, ground-line alignment for 3D artwork. scripts/measure.py ships with the skill and does the measuring: Python 3 with Pillow (python3 -m pip install pillow, py -3 -m pip install pillow on Windows, where python.org's installer creates no python3, or uv run the script), plus Chrome or Edge to rasterize SVG. PNG needs no browser.
• Watermarked previews are for choosing; originals are fetched once, for the approved set. Presigned URLs live an hour and never go into a page.
• Motion when the slot earns it. Many styles also ship animated. The skill picks those, fetches the real files through get_illustration_animation, and writes the sources in the order that plays: mp4-hevc first, because Safari answers "probably" for webm too, takes whichever it sees first and then cannot show the transparency. Lottie where the artwork has it.

Server note: the illustration tools (search_illustrations, get_illustration_svg, get_illustration_png_url, get_illustration_animation, list_illustrations_styles, list_illustrations_categories) are live on mcp.icons8.com, the still ones since 2026-09-07 and get_illustration_animation with them. On a connection that does not expose them, the skill says so and stops, per its own rules.

What the plugin connects to

The plugin has no hooks and starts no background process. Everything below happens when a skill runs.

The skills do not send your source code, your files or your conversation to any of these hosts. Icons8 operates all of them; the last one is the Cloudflare R2 storage that holds Icons8 originals. The Icons8 privacy policy covers what the server keeps.

In your project, the skills write icons8.json (the lock file), the asset files you approve, and a sheet.html contact sheet to choose from. They edit your UI code where you ask them to. When a screen gets an animated icon, the page loads the lottie-web player from cdn.jsdelivr.net in the visitor's browser; the plugin itself sends nothing there.

On your machine, the ouch skill can run scripts/measure.py. It reads image files, rasterizes SVG with headless Chrome or Edge, writes rasters to a temporary directory and deletes them on exit. It makes no network request. If you start it with uv run, uv downloads Pillow from PyPI first.

The illustration-animator skill runs a Node engine from its own folder. Its one-time setup prints a plan and installs nothing until you agree. It installs five npm packages pinned by a lockfile (svgpath, lottie-web, paper, puppeteer-core, @puppeteer/browsers) from the npm registry into ~/.animator/, and downloads Chrome for Testing from Google (a pinned build, checked by SHA-256) only when no Chrome, Chromium or Edge is installed. It does not install ffmpeg: when ffmpeg is missing, setup shows the command for you to run. After that it works offline. It reads the SVG files you point it at, writes scenes, animations, rules and samples into that style folder, and renders frames in the system temporary folder.

Animating illustrations: the illustration-animator skill

Point it at a folder of SVG illustrations of one style and it returns looped animations: Lottie JSON GIF and MOV without background, plus MP4 (HEVC with alpha) on macOS. For each illustration it writes a short story (an action and a reaction to it), cuts the drawing into parts that move the way the object works (a wheel rolls, a pen writes, a walking person walks) with joints and tight line masks, builds the animation, then checks it with scripts and a visual judge and fixes what it finds, within hard time limits per illustration. Say " - bad" and why, and the failed technique becomes a rule for the whole style.

The motion rules, style rules and reference scenes were trained on Icons8 animations and illustrations.

It does not need the MCP server or an Icons8 account. It needs Node.js; the first run of engine/bin/setup.js installs what the engine uses (see below).

Requirements

• A client that supports the Agent Skills standard (Claude Code, Codex, VS Code + Copilot, Cursor, …)
• Network access to https://mcp.icons8.com/mcp/
• An Icons8 account, signed in through the browser on first use
• An Icons8 API key only where the client cannot do OAuth, or on CI
• For illustration-animator: Node.js 22.12 or newer, and ffmpeg (its setup shows how to install it)

Support

Report a bug or a wrong icon choice in GitHub Issues. Report a security issue privately through the Icons8 contact page, not in a public issue. For your Icons8 account, plan or billing, use the Icons8 Help Center. The Help Center also explains what the Icons8 MCP server is.

License

Apache-2.0 — see LICENSE and NOTICE.

The license covers this repository, not the icon artwork. Icons are licensed separately under the Icons8 license: free icons require attribution, SVG delivery requires a paid plan. If the assets ship in a product, confirm the license before handing over paid icons.