Icons8 — Agent Skills

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

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

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 same file Claude Code and every Agent Plugins v1 client
read, so there is one server definition rather than one per format.

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.

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. In GitHub Copilot CLI, copilot plugin install; what it
installs also shows up in VS Code. Cursor installs from marketplaces only, so it needs the plugin
listed in one — either Cursor's registry or a team marketplace imported from a repo.

.claude-plugin/ and .codex-plugin/ keep their manifests, because Claude Code isn't on the
compatible-clients list yet and Codex still reads its own. They no longer keep their own copy of the
server, though: both point mcpServers at the root mcp.json.

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 and get_icon_png_url, 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.

Full SVG access — subscribe for $15. There is no second
setup: the account you already signed in with carries the plan, and a fifth tool, get_icon_svg,
appears alongside the other four. 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 only MCP config; all three manifests point here
.mcp.json                     # symlink to it — the name Claude Code's inventory looks for
.claude-plugin/               # Claude Code manifest + marketplace
.codex-plugin/                # Codex manifest
.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
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
└── 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

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

The three manifests describe the same plugin for three packaging formats, so version and
description have to move together. The server itself is declared once, in mcp.json.

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.

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

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.