Agent glyphs skill

Agent Glyphs

An index of every open-source icon library: all Iconify sets plus open libraries outside Iconify (prefix x-…), 400k+ icons. Each icon is measured from its actual drawing and tagged with its meaning in English and Arabic. Icons are fetched from their official source on demand (npm / Iconify API, or this project's release for x- sets), with their licence.

All commands run from this skill's folder. The index (data/atlas.db, ~160 MB; a 33 MB download) downloads automatically on first use. Style matching and previews need: pip install -r requirements.txt (search and export alone need only Python 3.10+).

Workflow

1. Find the target style first — consistency beats the "best" single icon.
   • The project already uses an icon library? Check package.json and stay in it with --set (see the mapping below). Mixing libraries is the most common icon mistake.
   • The person has their own icons (SVGs)? Run scripts/match.py <folder> to find the families that look like them, then search with --like <folder>.
   • Nothing yet? Ask, or choose a coherent family (e.g. lucide, tabler, ph) and keep every icon from it.
2. Search by meaning, with style filters:

   python scripts/search.py "shopping cart" --set lucide
   python scripts/search.py "محفظة" --shape outline --stroke light --corners rounded
   python scripts/search.py "notification" --like tabler          # ranked by look
   python scripts/search.py --cat finance --shape filled --limit 40
   python scripts/search.py "home" --shape outline --color duotone --density balanced
   

   Output: prefix:name, style, weight, corners, category, licence. Use only names returned by the search — never invent icon names.
3. Show before choosing when a person will judge the result (designers, unclear asks): python scripts/preview.py lucide:house tabler:home -o choices.png (or --search "home"), then look at the PNG yourself and share it.
4. Export into the project:

   python scripts/get.py lucide:house lucide:search --out src/icons            # SVG files
   python scripts/get.py ph:bell --format tsx --out src/components/icons        # React (jsx|tsx)
   python scripts/get.py tabler:wallet --stroke 1.5 --size 20 --color "#0F766E" # restyle
   python scripts/get.py mdi:home --stdout                                      # print inline
   

   get.py writes/updates ATTRIBUTION.md next to the files.
5. Fill gaps in a set in one step: python scripts/match.py ./my-icons --need cart wallet "مسجد" (or match.py lucide --need ...).

If the project already depends on the library's own package (e.g. lucide-react), importing from that package is better than copying SVGs — use the search to find the right name, then import it.

Vocabulary (filters and fields)

Field	Values	Meaning
shape	outline, filled, mixed	what the eye sees: lines only, filled areas, or lines with filled parts. An icon named "…-filled" that is drawn with lines is outline
color	mono, duotone, multicolor	one colour, a second lighter tone, or its own fixed colours (multicolor cannot be recoloured with CSS). Combines with shape: an outline icon can be duotone
style	outline, filled, mixed, duotone, multicolor	older single label (--style): the colour when it is not mono, else the shape
weight	number	stroke width as it would be on a 24px icon (Lucide = 2, Heroicons = 1.5)
weight_class	hairline <0.6, thin <1.1, light <1.4, regular <1.75, medium <2.25, bold <2.9, heavy; solid for filled
stroke	thin, light, regular, bold	stroke class on a 24px grid: thin < 1.25 (Phosphor Thin/Light), light ≈ 1.5 (Heroicons, Phosphor), regular ≈ 2 (Lucide, Tabler), bold > 2.15 (Phosphor Bold). --stroke; --weight 1.5 still filters the exact value
corners	rounded, mixed, sharp	how real corners (two straight lines meeting) and line ends are drawn; circles and arcs do not count. An icon with no corners takes its family's value
curves	geometric, balanced, organic	share of the outline that is curved
contrast_class	monoline, moderate, high	variation between thick and thin parts
density_class	airy, balanced, heavy	how much of the canvas is ink (--density); keep one density so icons sit together
container	circle, square, none	icon drawn inside a circle or square
complexity	simple, medium, detailed	amount of detail
cat, cat2	arrows, interface, actions, status, communication, commerce, finance, business, media, files, text, design, devices, development, data, network, ai, security, people, health, transport, maps, weather, nature, food, buildings, home, time, education, sports, culture, tools, shapes, emoji, brands, flags, other

An icon can have two content categories (cat, cat2); --cat matches either. Each label has a confidence (style_conf, weight_conf, corners_conf: high / medium / low). When a choice matters and confidence is not high, look at the preview. Measured accuracy is in ACCURACY.md.

Common packages → --set prefix: lucide-react → lucide · @tabler/icons-react → tabler · @phosphor-icons/react → ph · @heroicons/react → heroicons · @mui/icons-material → ic · Material Symbols → material-symbols · @radix-ui/react-icons → radix-icons · iconoir-react → iconoir · remixicon → ri · react-feather → feather · bootstrap-icons → bi · Font Awesome 6 → fa6-solid / fa6-regular · @fluentui/react-icons → fluent · @mdi/js → mdi · hugeicons → hugeicons · simple-icons → simple-icons (brand logos). Full list: python scripts/sets.py (filter with --search).

Licences — always respect them

• Default results include only licences that allow commercial use: permissive (MIT, Apache, ISC, OFL, CC0…: no obligation beyond keeping the licence) and attribution (CC BY: credit the author — get.py writes it to ATTRIBUTION.md; tell the person).
• --license any also shows share-alike (GPL, CC BY-SA) and non-commercial sets. Use them only when the person explicitly accepts those terms.
• Brand logos (cat=brands) are trademarks: fine to refer to the brand, not to imply endorsement.

Notes

• Right-to-left (Arabic) interfaces: directional icons (arrows, chevrons, back/next, send, undo/redo) must point the other way — export them with get.py --mirror. Do not mirror icons that show real-world objects or clocks/checkmarks.
• Glyphs are Unicode characters, not drawings: Islamic and Arabic characters that no icon library draws (﷽ ﷺ ﷻ ۞ ۩ ﴾ ﴿, honorifics such as ﵁ رضي الله عنه) and related emoji (🕌 🕋 📿 ☪). search.py returns them with the icons (prefix unicode, "kind": "glyph", the char and its codepoint); --kind glyph returns glyphs only, --kind icon still icons only, --kind animated icons that move (SVG animation: line-md, svg-spinners, meteocons…; the exported SVG keeps the animation). Put a glyph in the text as the character itself (or its HTML entity ﷺ / CSS content: "\FDFA"), never as an image or SVG. get.py unicode:<name> prints the character. The character needs no licence; the font that draws it does (Noto Naskh Arabic, Amiri and Scheherazade New are OFL).
• Search by meaning, not exact names. Arabic and English words are expanded through ~3,900 concept groups: synonyms, plurals and dialect or loanwords (سيتنج → settings, داشبورد → dashboard, مسلمين → islam), and closely related things ("مسلم" also finds mosque, crescent, quran). Each JSON result has "match": "same" or "related"; same-meaning icons always rank first. Hamza, "ال", plurals and common suffixes do not matter (سلة = السلة = بالسلة).
• No network for the index? Set AGENT_GLYPHS_DATA to a folder containing atlas.db. Icons are fetched from npm (@iconify-json/<prefix>) or the Iconify API and cached in ~/.cache/agent-glyphs; set ICONIFY_JSON_DIR to use local Iconify JSON files instead.