article-icons — Claude Code skill: what it does, how to install
article-icons adds clean static SVG icons from the itshover registry into Markdown and HTML documents.
MIT 279 installs ★ 302 updated 2026-09-13
npx skills add smallnest/goal-workflow --skill article-icons -a claude-codeWhat article-icons does
The skill decorates articles formatted in .md, .html, or .mdx using icons from itshover.com. Everything runs through scripts/fetch_icon.py, which pulls the registry item and turns it into standalone SVG markup. There is no build pipeline or React dependency involved.
An offline cache in scripts/icon_names.json indexes 263 verified names. The workflow inspects headings and callouts, matches icons by context rather than pure keywords, confirms the layout plan, and injects the markup. By default, icons inherit text styling via currentColor.
Fetching graphics fails without network access to itshover.com. When a Markdown parser rejects inline HTML tags, the tool falls back to saving files inside assets/icons/ as regular image links.
What it helps with
- map semantic vector icons to document sections
- turn itshover registry components into plain inline SVG
- embed lightweight illustrations into Markdown without node bundlers
Example prompts for the agent
- /article-icons post.md
- Add inline icons to key headings in overview.html
- /article-icons docs/architecture.mdx
How to install article-icons
1Skills CLI (Vercel)
npx skills add smallnest/goal-workflow --skill article-icons -a claude-code2Manually: put the files in place
~/.claude/skills/article-icons/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/article-icons/
1Skills CLI (Vercel)
npx skills add smallnest/goal-workflow --skill article-icons -a codex2Manually: put the files in place
.agents/skills/article-icons/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add smallnest/goal-workflow --skill article-icons -a cursor2Manually: put the files in place
.cursor/skills/article-icons/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install smallnest/goal-workflow skills/article-icons2Manually: put the files in place
.github/skills/article-icons/SKILL.md1Skills CLI (Vercel)
npx skills add smallnest/goal-workflow --skill article-icons -a gemini-cli2Platform CLI
gemini skills install https://github.com/smallnest/goal-workflow --path skills/article-iconsManually: put the files in place
.devin/skills/article-icons/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add smallnest/goal-workflow --skill article-icons -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about article-icons
How to install article-icons in Claude Code?
Run npx skills add smallnest/goal-workflow --skill article-icons -a claude-code. The definition is saved to ~/.claude/skills/article-icons/SKILL.md.
What does the article-icons skill do?
It reads target documents, discovers icons using scripts/fetch_icon.py, and embeds inline SVG alongside titles and highlights.
What are the runtime requirements for article-icons?
You need Python 3 available locally and active internet access to reach itshover.com during asset retrieval.
Source text
SKILL.md · MIT
--- name: article-icons description: "Illustrate an article (Markdown, HTML, etc.) with animated-style icons from itshover.com/icons. Fetches icons as clean inline SVG and places them at section headings, key concepts, lists, and callouts. Triggers on: /article-icons, 配图, 给文章配图标, add icons to article, illustrate with icons." user-invocable: true --- # Article Icons (itshover) Add tasteful icons to an article using the [itshover](https://www.itshover.com/icons) icon set. itshover publishes 263 icons as shadcn registry components; this skill downloads them and converts each into a clean, static, inline **SVG** that drops straight into Markdown or HTML — no React, no `motion`, no build step. ## Triggers Use when the user wants to illustrate a document with icons: - `/article-icons <file>` - "给这篇文章配图标", "给文章配图", "add icons to this article", "illustrate with icons" ## Inputs - **Target file** — the article to illustrate (`.md`, `.html`, `.mdx`, ...). If not given, ask. - **Style preferences** (optional) — color, size, where icons go. Otherwise use sensible defaults below. ## The Tool `scripts/fetch_icon.py` is the only moving part. It fetches an icon and prints static SVG to stdout. ```bash # Get one icon (defaults: size 24, color currentColor, stroke-width 2) python3 scripts/fetch_icon.py heart-icon # Customize python3 scripts/fetch_icon.py rocket-icon --size 32 --color "#d97757" --stroke-width 1.5 # Discover names (do this FIRST — names must match exactly) python3 scripts/fetch_icon.py --list python3 scripts/fetch_icon.py --search arrow python3 scripts/fetch_icon.py --search brand ``` `scripts/icon_names.json` is a cached list of all 263 names for offline reference. Most icon names end in `-icon` (e.g. `heart-icon`, `rocket-icon`, `database-icon`), and brands use `brand-<name>-icon` (e.g. `brand-anthropic-icon`). But the convention is **not** universal — real names include `shield-check`, `credit-card`, `down-chevron`, `apple-brand-logo`, `skull-emoji`. **Never guess a name. Always resolve it with `--search` first** — a wrong guess just wastes a 404. ## Workflow 1. **Read the article.** Identify its structure: title, section headings (`#`/`##`/`<h1>`/`<h2>`), key concepts, list groups, callouts/warnings, and any tech/brand mentions (React, GitHub, AI tools...). 2. **Plan the icon map.** For each placement, choose a semantically matching icon. Match meaning, not just keywords — a "performance" section → `rocket-icon` or `zap-icon`; a "security" section → `shield-icon` or `lock-icon`; a warning callout → `alert-triangle-icon`. Prefer **one consistent icon family** (all outline, one color) so the article looks designed, not decorated. Resolve every name with `--search`. 3. **Confirm the plan** with the user before editing — show the heading→icon mapping. This is cheap and avoids reworking a whole document. 4. **Fetch and embed.** Run `fetch_icon.py` for each chosen icon (parallelize independent fetches) and inline the SVG at its placement. See embedding rules below. 5. **Verify.** Re-read the edited file; for HTML, open it / screenshot to confirm icons render and align. Report the mapping you applied. ## Embedding Rules **HTML** — inline the SVG directly. Wrap heading icons so they align with text: ```html <h2 style="display:flex;align-items:center;gap:.5rem;"> <svg ...>...</svg> Performance </h2> ``` **Markdown** — GitHub-flavored Markdown renders inline HTML, so embed the raw SVG. Keep it on one line and size it small (16–20px) for inline use, 24–28px beside headings: ```markdown ## <svg ... width="22" height="22" ...>...</svg> Getting Started ``` If the target renderer strips inline SVG (some strict Markdown engines do), fall back to saving each SVG into an `assets/icons/` folder next to the article and referencing it: ``. Ask which the user prefers if unsure. ### Defaults - **Size:** 24px beside `h1`, 20–22px beside `h2`/`h3`, 16px inline in text. - **Color:** `currentColor` so icons inherit text color. Override with `--color` only when the user wants accent colors. - **Density:** one icon per heading + a few for genuinely key concepts. Do **not** icon every bullet or sentence — restraint reads as polish. - **Alignment:** always `display:flex;align-items:center;gap:.4–.5rem` for heading icons in HTML. ## Icon Selection Cheatsheet These names are verified to exist, but the set changes — always reconfirm with `--search` before fetching. | Theme | Real icon names | |-------|------| | intro / overview | `book-icon`, `home-icon`, `globe-icon`, `map-pin-icon` | | performance / speed | `rocket-icon`, `gauge-icon`, `clock-icon` | | security | `shield-check`, `lock-icon` | | data / charts | `database`-family via `--search`, `chart-bar-icon`, `chart-line-icon`, `chart-pie-icon`, `cloud-1-icon` | | settings / config | `gear-icon`, `sliders-horizontal-icon` | | warning / note | `triangle-alert-icon`, `info-circle-icon`, `filled-bell-icon` | | success / done | `checked-icon`, `double-check-icon`, `simple-checked-icon` | | ideas | `brain-circuit-icon`, `sparkles-icon`, `star-icon`, `bulb-svg` | | AI / brands | `brand-anthropic-icon`, `brand-gemini-icon`, ... (`--search brand`) | | navigation | `arrow-narrow-*-icon`, `down-chevron`, `right-chevron` | ## Edge Cases | Scenario | Handling | |----------|----------| | Icon name not found (404) | Run `--search <term>`; pick the closest real name. Never invent names. | | Icon won't convert (rare; ~2/263 use a JS map for paths) | Script prints a clear error. Pick an alternative icon with similar meaning. | | No network access | Cannot fetch SVGs; tell the user the skill needs network access to itshover.com. | | Markdown renderer strips inline SVG | Fall back to `assets/icons/*.svg` + image references. | | Article already has icons | Ask whether to replace, supplement, or skip those sections. | | Very long article | Confirm the mapping for the first few sections, then apply the same family consistently throughout. | ## Checklist Before finishing: - [ ] Every icon name was resolved with `--search`/`--list` (no guessed names) - [ ] One consistent icon family/color across the article - [ ] Icons placed at headings + genuinely key points, not everywhere - [ ] Heading icons vertically aligned with text (flex + gap) - [ ] Edited file re-read; HTML visually verified to render - [ ] Mapping summary reported to the user
© smallnest · MIT · smallnest/goal-workflow