--- name: icons8 description: "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)." argument-hint: "[type:] [query] e.g. 'icon: shopping cart', 'illustration: teamwork', 'photo: office'" disable-model-invocation: true allowed-tools: Bash, Read, Write, Glob, Grep, WebSearch, WebFetch, AskUserQuestion --- # Icons8 Fetcher Fetch icons, illustrations, and photos from Icons8's library of 1.5M+ assets. ## Config Read config from `~/.claude/skills/icons8/config.json`: ```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: ```bash 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:** ```bash 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): ```bash 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: ```bash 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: ```bash mkdir -p ./OUTPUT_DIR ``` 3. Generate filenames: - Format: `{icon-name}-{style}.{ext}` for icons - Format: `{title-slug}.{ext}` for illustrations/photos - Lowercase, hyphenated, max 60 chars 4. Download: **Icons via CDN:** ```bash 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: ```bash # SVG content from API response echo 'SVG_CONTENT' > "./OUTPUT_DIR/{icon-name}-{style}.svg" ``` **Illustrations/Photos:** ```bash curl -sL "ASSET_URL" -o "./OUTPUT_DIR/FILENAME" ``` 5. Verify each download: ```bash file "./OUTPUT_DIR/FILENAME" ``` Confirm it's a valid image file (PNG, SVG, JPEG), not an HTML error page. 6. 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:** ```html Shopping Cart Shopping Cart Icons by Icons8 ``` **React/JSX:** ```jsx Shopping Cart ``` **CSS:** ```css .cart-icon { background-image: url('assets/icons/shopping-cart-color.png'); width: 32px; height: 32px; background-size: contain; } ``` **Markdown:** ```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: 1. Parse the list of icon names 2. Fetch all icons in the same style for consistency 3. Download all at once 4. Present a single summary table ```bash # 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: ```bash 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 (`Icons by Icons8`) - **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