Add Icon

Add a Font Awesome icon to the user's project. This skill handles icon name resolution, project detection, and code generation for every Font Awesome integration method.

Scripts referenced from suggest-icon are relative to plugins/icons/skills/suggest-icon/. Scripts referenced from add-icon are relative to plugins/icons/skills/add-icon/. Run them from their respective directories.

Tool selection

At the start, run command -v fa to check whether the fa CLI is available on PATH.

The fa kit subcommand requires fa version 0.8.0 or newer. If the fa kit subcommand is needed, recommend the user upgrade fa, using instructions here: https://docs.fontawesome.com/web/use-with/fa-cli

• If `fa` is found: use it for icon lookups and kit fetching (it returns structured JSON). For kit operations (fa kits and fa kit), check auth first: run fa whoami to see if the user is logged in. If logged in, these will work directly. If not logged in but FA_API_TOKEN is set, they will also work. If neither, tell the user: "You need to be logged in to the Font Awesome CLI for kit operations. Run fa login in a separate terminal, then come back here and try again." If they cannot log in, fall back to fetch-kit.py. When the project uses a Kit, fa kit icon --kit-token <TOKEN> <icon> tells you whether a specific icon is in the Kit's subset and which family styles it's available in — use it to avoid adding an icon the Kit doesn't include (see step 3).
• If `fa` is not found: fall back to the Python scripts described below.
• Use latest-version.py to get the latest version.

Steps

1. Resolve the icon name

First, determine whether the project uses a Kit for integrating Font Awesome. If the project has a .font-awesome.md file, read it to determine whether a Kit is in use.

If project uses a Kit

If the project uses a Kit, then verify that the icon exists in the particular Kit's subset. This can only be done with the fa CLI. If the user is not logged in, prompt them to run fa login in a separate terminal first.

If the fa CLI is not available, tell the user that you cannot verify whether the icon is in their Kit's subset. Suggest they install the fa CLI, login with fa login, then re-run this skill.

To verify the icon exists in the kit, run fa kit icon --kit-token <TOKEN> <icon>.

If the icon does not exist, invoke the /suggest-icon skill internally with the user's icon argument as the use-case. Auto-accept the top recommendation without prompting the user to confirm, if there are any recommendations.

If /suggest-icon offers no recommendations, it may be because the Kit's subset does not include any icons similar to the user's query. In that case, search all of Font Awesome (not just the Kit) for similar icons using fa search --version <version> --query <icon>. Let the user know that the icon they requested is not in their Kit's subset, but they could add it to their Kit at https://fontawesome.com/kits.

If project does not use a Kit

If the project does not use a Kit, then to verify the icon exists:

Determine the version of Font Awesome in use. First, try to discover it from .font-awesome.md; otherwise, use latest-version.py to get the latest version. Use this version as <version> in the following commands.

• `fa` CLI: Run fa icons --version <version> --name <icon>. The icon exists if data.release.icon is non-null. The familyStylesByLicense field shows the free/pro breakdown.
• Fallback: Run ./scripts/icon-exists.py --version <version> --icon-name <icon>. Exit code 0 means the icon exists; exit code 1 means it does not.

If the icon does not exist, invoke the /suggest-icon skill internally with the user's icon argument as the use-case. Auto-accept the top recommendation and continue with that icon name. Do not ask the user to confirm — a working icon is better than a broken one.

2. Determine the integration method

Check for a .font-awesome.md file in the project root.

If .font-awesome.md exists

Read it and use the configuration it describes. Skip discovery and proceed to step 3. However, keep the file's contents in mind — if any later step reveals information that is missing or incomplete in the file (e.g., a new import pattern, a family not listed, a wrapper component not documented), you will update it at the end (see step 6).

If .font-awesome.md does not exist

Run a discovery process to figure out how the project uses Font Awesome. Use a subagent (via the Agent tool with subagent_type: "Explore") to perform this discovery. The subagent should search for the following sources (in order of specificity) and return a structured summary of what it found:

1. `package.json` / lock files — look for Font Awesome packages:

• @fortawesome/react-fontawesome → React component integration
• @fortawesome/vue-fontawesome → Vue component integration
• @fortawesome/fontawesome-svg-core → SVG core (used by React/Vue)
• @fortawesome/fontawesome-free or @fortawesome/fontawesome-pro → general SVG+JS or web font
• @fortawesome/free-solid-svg-icons, @fortawesome/pro-solid-svg-icons, etc. → individual icon packages (note the style and license)

1. HTML files / templates — look for:

• Font Awesome Kit script tags: <script src="https://kit.fontawesome.com/XXXXXX.js"...> → Kit (SVG+JS). Extract the kit ID (the token before .js).
• CDN links in <link> tags: cdnjs.cloudflare.com/ajax/libs/font-awesome/ or use.fontawesome.com → Web Fonts+CSS via CDN
• <i class="fa-solid fa-..."> or <i class="fas fa-..."> usage patterns → class-based (Web Fonts+CSS or SVG+JS)

1. Import statements in source files — scan for:

• import { FontAwesomeIcon } → React component
• import { library } from @fortawesome/fontawesome-svg-core → library approach
• Individual icon imports like import { faCoffee } → individual import approach

1. SVG sprite sheets — look for <use href="...sprites/..."> patterns or sprite SVG files.

1. Web Components — look for <fa-icon> custom elements.

1. Other frameworks — look for Angular (angular.json, FontAwesomeModule), Svelte, etc.

The subagent should return: which Font Awesome packages are installed (with versions), any kit IDs found, CDN URLs, the framework integration method, import patterns observed in source files, the license (free vs pro), and any project conventions (wrapper components, default sizing, etc.).

After the subagent returns, if a kit ID was found, fetch the kit details:

• `fa` CLI: Run fa kit show --kit-token <id>. Returns JSON with the kit's version, license, technology, and available families. Requires the user to be logged in (fa whoami returns success) or FA_API_TOKEN to be set. If neither, prompt the user to run fa login in a separate terminal first.
• Fallback: Run ./scripts/fetch-kit.py --kit-id <id> (in the add-icon skill directory) to get the kit's version, license, method, and available families.

After discovery, determine:

• Integration method — the primary way icons are rendered
• Kit ID / CDN URL — if using a kit or CDN
• License — free or pro. Detect from: kit config (via fetch-kit.py), npm package names (fontawesome-free vs fontawesome-pro, free-*-svg-icons vs pro-*-svg-icons), or CDN URL patterns.
• Default style — the most commonly used style in the project (solid, regular, light, thin, duotone). If unclear, default to solid.
• Default family — the most commonly used family (classic, duotone, sharp, sharp-duotone, chisel, etch, graphite, jelly, jelly-duo, jelly-fill, notdog, notdog-duo, slab, slab-press, thumbprint, utility, utility-duo, utility-fill, whiteboard). If unclear, default to classic.