Fetch icons, illustrations, and photos from Icons8. Search 1.5M+ icons across 116 styles, vector illustrations, and 500K+ stock photos. Supports API (with key) and free CDN fallback (no key needed).

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)

Style Code	Description
`color`	Colorful flat icons (most popular)
`ios` / `ios-filled`	Apple iOS style, outline and filled
`material` / `material-outlined`	Google Material Design
`fluency`	Microsoft Fluency 3D-like
`3d-fluency`	Full 3D rendered icons
`flat-round`	Flat with rounded shapes
`dusk`	Gradient duotone icons
`plumpy`	Thick-lined colorful icons
`doodle`	Hand-drawn sketch style
`stickers`	Sticker/emoji style
`emoji`	Platform emoji style
`tiny-color`	Small colorful pixel icons
`pastel-glyph`	Soft pastel colored
`cotton`	Soft rounded style
`office`	Microsoft Office style

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.

Prefix	Asset Type	Example
`icon:` or `icons:`	Icons	`icon: shopping cart`
`illustration:` or `illus:`	Illustrations	`illustration: teamwork`
`photo:` or `photos:`	Photos	`photo: modern office`
(no prefix)	Icons (default)	`rocket ship`

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):

Source	What to extract
`README.md`	Project name, description, purpose
`package.json` / `pyproject.toml`	Name, description, keywords
HTML/JSX/TSX files (first 3)	What UI elements exist, what icons might be needed
Existing icons in `assets/`, `public/`, `static/`, `icons/`	What already exists

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):

Convert the user's query to hyphenated format: "shopping cart" -> "shopping-cart"
Try the direct CDN URL first with the default style
Verify with file command that the result is a valid PNG (not JSON or HTML)
If the download failed (JSON error or HTML), use WebSearch to find the correct icon name:
```
WebSearch: "site:icons8.com/icon {QUERY}"
```
Extract icon slugs from search results (URL pattern: /icon/{id}/{slug})
Use those slugs with the CDN pattern
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

Determine output directory based on asset type:
- Icons: {output_dir}/ (default: assets/icons/)
- Illustrations: assets/illustrations/
- Photos: assets/photos/
Create the output directory:

mkdir -p ./OUTPUT_DIR

Generate filenames:
- Format: {icon-name}-{style}.{ext} for icons
- Format: {title-slug}.{ext} for illustrations/photos
- Lowercase, hyphenated, max 60 chars
Download:

Icons via CDN:

curl -sL "https://img.icons8.com/{style}/{size}/{icon-name}.png" -o "./OUTPUT_DIR/{icon-name}-{style}.png"

Icons via API (SVG): Extract the SVG content from the API response and write it directly:

# SVG content from API response
echo 'SVG_CONTENT' > "./OUTPUT_DIR/{icon-name}-{style}.svg"

Illustrations/Photos:

curl -sL "ASSET_URL" -o "./OUTPUT_DIR/FILENAME"

Verify each download:

file "./OUTPUT_DIR/FILENAME"

Confirm it's a valid image file (PNG, SVG, JPEG), not an HTML error page.

If a CDN download returns a placeholder/error (< 1KB or HTML content), note it and try alternate icon name spellings.

Phase 5: Summary

Downloaded 5 icons to ./assets/icons/:

  1. shopping-cart-color.png (128x128, 4.2 KB)
     CDN: img.icons8.com/color/128/shopping-cart.png
  2. add-shopping-cart-color.png (128x128, 3.8 KB)
     CDN: img.icons8.com/color/128/add-shopping-cart.png
  3. shopping-cart-ios-filled.png (128x128, 2.1 KB)
     CDN: img.icons8.com/ios-filled/128/shopping-cart.png

Style: Color, iOS Filled | Format: PNG | Size: 128px

License: Free with link attribution to Icons8 (icons8.com).
For attribution-free use, get an API key at https://icons8.com/pricing

Phase 6: Generate Usage Snippets (Optional)

If the project context suggests web/app development, offer ready-to-use code:

HTML:

<!-- Option 1: Local file -->
<img src="assets/icons/shopping-cart-color.png" alt="Shopping Cart" width="32" height="32">

<!-- Option 2: CDN embed (requires attribution link) -->
<img src="https://img.icons8.com/color/32/shopping-cart.png" alt="Shopping Cart">
<a href="https://icons8.com">Icons by Icons8</a>

React/JSX:

<img src="/assets/icons/shopping-cart-color.png" alt="Shopping Cart" width={32} height={32} />

CSS:

.cart-icon {
  background-image: url('assets/icons/shopping-cart-color.png');
  width: 32px;
  height: 32px;
  background-size: contain;
}

Markdown:

![Shopping Cart](assets/icons/shopping-cart-color.png)

Only show snippets relevant to the detected project type (check for .html, .jsx, .tsx, .vue, .css files).

Batch Mode

If the user requests multiple icons at once (e.g., "I need icons for: home, settings, user, search, notifications"), handle them all in a single run:

Parse the list of icon names
Fetch all icons in the same style for consistency
Download all at once
Present a single summary table

# Batch CDN download example
for icon in home settings user search notifications; do
  curl -sL "https://img.icons8.com/color/128/${icon}.png" -o "./assets/icons/${icon}-color.png"
done

Style Consistency Helper

When fetching multiple icons for the same project, always use the same style across all icons. If the user has already downloaded icons in a specific style, detect that:

ls ./assets/icons/ 2>/dev/null | head -20

If existing icons follow a pattern (e.g., all *-material.png), default to that style for new downloads.

Error Handling

CDN returns 404/placeholder: Try alternate hyphenation or use WebSearch to find the correct slug
API rate limit (1000 req/hr): Note the limit and suggest spacing out requests
Icon not found in requested style: Suggest available styles for that icon
Download produces HTML instead of image: The CDN returned an error page. Check filename was correct, try without special characters
No results for query: Broaden the search terms, suggest related keywords

Licensing Notes

Free tier (CDN, no API key): Icons are free to use with a link to Icons8 (<a href="https://icons8.com">Icons by Icons8</a>)
Paid tier (API key): No attribution required. SVG downloads available. $15/month.
Illustrations: Free with attribution
Photos: Free with attribution (similar to Pexels/Unsplash model)
Always mention the license requirement in the download summary