Icons8 Fetcher

Fetch icons, illustrations, and photos from Icons8's library of 1.5M+ assets.

Config

Read config from ~/.claude/skills/icons8/config.json:

{
  "api_key": "",
  "default_count": 10,
  "default_style": "color",
  "default_format": "png",
  "default_size": 128,
  "output_dir": "assets/icons"
}

All fields are optional. The skill works without an API key via the CDN for icons.

Load config silently at the start of every invocation:

cat ~/.claude/skills/icons8/config.json 2>/dev/null || echo '{}'

Available Styles (116 total, most popular listed)

Use WebFetch to see the full list: https://api-icons.icons8.com/api/publicApi/platforms

Phase 1: Parse Input

Determine asset type and query from user input

Format: [type:] query where type is optional.

Also detect style overrides in the input:

• "shopping cart in material style" -> query: "shopping cart", style: "material"
• "3d rocket icon" -> query: "rocket", style: "3d-fluency"

If no input was provided, scan the current directory for context (same as image-fetcher):

Then use AskUserQuestion:

What kind of assets do you need from Icons8?
Options:
- Icons (1.5M+ across 116 styles)
- Illustrations (vector SVG/PNG, multiple artistic styles)
- Photos (500K+ stock photos)

Follow up with: subject/query, preferred style, quantity needed.

Phase 2: Fetch Assets

Route A: Icons (API or CDN)

If API key is configured:

Search endpoint:

curl -s "https://api-icons.icons8.com/api/publicApi/icons?term=QUERY&amount=COUNT&platform=STYLE&language=en-US" \
  -H "Api-Key: API_KEY"

Response fields to extract:

• docs[].id - icon ID
• docs[].name - icon name
• docs[].commonName - display name
• docs[].platform - style code
• docs[].isFree - boolean, whether free to use
• docs[].category - category name
• docs[].tags[] - related tags

Download endpoint (for SVG source):

curl -s "https://api-icons.icons8.com/api/publicApi/icons/ICON_ID" \
  -H "Api-Key: API_KEY"

Response includes icon.svg field with the full SVG source.

If NO API key (CDN fallback, always works):

Icons8 provides a free CDN at img.icons8.com. Use this pattern:

https://img.icons8.com/{style}/{size}/{icon-name}.png

Examples:

• https://img.icons8.com/color/128/shopping-cart.png
• https://img.icons8.com/ios-filled/96/home.png
• https://img.icons8.com/3d-fluency/128/rocket.png
• https://img.icons8.com/material-filled/64/search.png

CDN rules:

• Max free size: 100px (with link attribution) or 512px (with API key)
• Supported sizes: 16, 24, 32, 48, 64, 96, 128, 256, 512
• Icon names use lowercase-hyphenated format: "shopping cart" -> "shopping-cart"
• Format is always PNG via CDN
• Color customization: append color hex to style: https://img.icons8.com/color/128/FF5733/shopping-cart.png

CDN quirks (important):

• Not all icon names match what you'd expect. "notifications" doesn't exist but "bell" does. "heart" exists in "color" but not in "plumpy".
• material-filled is NOT a valid style. Use material or material-outlined instead.
• A failed CDN request returns either:
  • JSON with {"success":false,"error":"...","code":"ICON_NAME_NOT_FOUND"} (wrong icon name)
  • JSON with {"success":false,"error":"...","code":"PLATFORM_ICON_NOT_FOUND"} (icon exists but not in that style)
  • HTML error page from CDN77 (style path doesn't exist at all)
• Always verify downloads with file command. If it's not PNG image data, the download failed.

CDN search strategy (no API key):

1. Convert the user's query to hyphenated format: "shopping cart" -> "shopping-cart"
2. Try the direct CDN URL first with the default style
3. Verify with file command that the result is a valid PNG (not JSON or HTML)
4. If the download failed (JSON error or HTML), use WebSearch to find the correct icon name:

   WebSearch: "site:icons8.com/icon {QUERY}"
   

5. Extract icon slugs from search results (URL pattern: /icon/{id}/{slug})
6. Use those slugs with the CDN pattern
7. If a specific style fails with PLATFORM_ICON_NOT_FOUND, try "color" (most complete style) or suggest alternatives

For multiple icons (when user wants a set), search for variations:

WebSearch: "site:icons8.com/icons/set/{QUERY}/{STYLE}"

Then WebFetch that URL to extract icon names from the page.

Route B: Illustrations

Icons8 illustrations don't have a public CDN. Use WebSearch + WebFetch:

WebSearch: "site:icons8.com/illustrations/illustration/{QUERY}"

Or fetch the illustrations search page:

WebFetch: "https://icons8.com/illustrations/s/{QUERY}"

Extract illustration URLs and metadata from the page. Illustrations are available as SVG and PNG.

If the user has an API key, also try:

curl -s "https://api-icons.icons8.com/api/publicApi/illustrations?term=QUERY&amount=COUNT" \
  -H "Api-Key: API_KEY"

Route C: Photos

Use WebSearch to find Icons8 stock photos:

WebSearch: "site:icons8.com/photos {QUERY}"

Or fetch the search page:

WebFetch: "https://icons8.com/photos/s/{QUERY}"

Extract photo URLs and metadata.

Phase 3: Present Candidates

For Icons:

Found 10 icons for "shopping cart" in Color style:

| # | Name | Style | Free | Preview URL |
|---|------|-------|------|-------------|
| 1 | Shopping Cart | color | Yes | img.icons8.com/color/128/shopping-cart.png |
| 2 | Add Shopping Cart | color | Yes | img.icons8.com/color/128/add-shopping-cart.png |
| 3 | Shopping Cart Loaded | color | Yes | img.icons8.com/color/128/shopping-cart-loaded.png |
...

Want to:
- Download specific ones? (enter numbers: 1, 3, 5)
- Download all?
- See these in a different style? (ios, material, 3d-fluency, etc.)
- Search for something else?

For Illustrations:

Found 5 illustrations for "teamwork":

| # | Title | Style | Format |
|---|-------|-------|--------|
| 1 | Team collaboration | Corporate | SVG, PNG |
| 2 | Remote teamwork | 3D | SVG, PNG |
...

For Photos:

Found 5 photos for "modern office":

| # | Description | Size | Category |
|---|-------------|------|----------|
| 1 | Open plan office with natural light | 1920x1280 | Business |
...

Then ask via AskUserQuestion which to download.

Phase 4: Download & Save

1. Determine output directory based on asset type:

   • Icons: {output_dir}/ (default: assets/icons/)
   • Illustrations: assets/illustrations/
   • Photos: assets/photos/

2. Create the output directory:

mkdir -p ./OUTPUT_DIR

3. Generate filenames:
   • For