setup-fa

Set up Font Awesome in a project from scratch. This skill handles everything from detecting the project type, through downloading a Kit or installing packages, to writing the initial integration code and creating .font-awesome.md so that /add-icon works immediately afterward.

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.

Important: bare SVG markup

Never generate Font Awesome SVG markup (raw <svg> elements) from your own knowledge or training data. If a bare SVG is needed during setup (e.g., for verification), fetch it from the Font Awesome API using fa icons --version <version> --name <icon> --svg-format html. This requires the user to be logged in (fa whoami) or FA_API_TOKEN to be set.

Pre-flight check

Before starting, check whether .font-awesome.md already exists in the project root. If it does, Font Awesome is already configured. Tell the user and ask if they want to reconfigure, update their setup, or if they had a different goal. Offer /fa-help if they have a question about their existing setup, or /add-icon if they want to start using icons.

Tool selection

Run command -v fa to check whether the fa CLI is available on PATH.

• If fa is found: use it for Kit operations and version queries (it returns structured JSON). For kit operations (fa kits), check auth first: run fa whoami to see if the user is logged in. If logged in, fa kits will work directly. If not logged in but FA_API_TOKEN is set, fa kits 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 fa is not found: fall back to the Python scripts described below where applicable.
• latest-version.py (in the suggest-icon skill directory) is always used for version detection.