Add kit subset awareness#1
Open
mlwilkerson wants to merge 10 commits into
Open
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates the Font Awesome agent skill documentation to be Kit subset–aware, so the agent can avoid suggesting/adding icons that are not available in the configured Kit and can track Kit updates via a new Kit Revision field in .font-awesome.md.
Changes:
- Add Kit-aware guidance to
/suggest-icon,/setup-fa, and/add-icon, including use of newfa kit ...subcommands. - Add instructions to verify a selected Kit covers icons already used in the project.
- Extend the
.font-awesome.mdtemplate to includeKit Revision(kitRevision).
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| plugins/icons/skills/suggest-icon/SKILL.md | Adds Kit token scoping rules for searches/recommendations. |
| plugins/icons/skills/setup-fa/SKILL.md | Adds “icons already in use” discovery and Kit coverage verification steps. |
| plugins/icons/skills/setup-fa/references/path-a-kit-embed.md | Updates Kit details command to fa kit show. |
| plugins/icons/skills/setup-fa/references/path-b-kit-npm.md | Updates Kit details command to fa kit show. |
| plugins/icons/skills/setup-fa/references/path-c-kit-download.md | Updates download command to fa kit download. |
| plugins/icons/skills/add-icon/SKILL.md | Adds Kit-subset validation flow to prevent adding non-Kit icons. |
| plugins/icons/skills/add-icon/font-awesome-md-format.md | Adds Kit Revision to the .font-awesome.md template and clarifies Kit token usage. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+21
to
+23
| - **If `fa` is found:** use it for icon lookups and searches (it returns structured JSON). If the project is configured with a Kit (see "Respect the configured Kit" below), also use `fa search --kit-token <TOKEN>` to search only icons available in the Kit, and `fa kit icon` to confirm a specific icon is included. | ||
| - **If `fa` is not found:** fall back to the Python scripts described below. Kit-aware searching requires the `fa` CLI; without it, you cannot scope suggestions to the Kit's subset — warn the user that your suggestions may include icons their Kit does not contain. | ||
| - Use `latest-version.py` to get the latest version. |
| - **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." | ||
| 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 Kit operations and version queries (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, `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." |
|
|
||
| Always recommend creating a Font Awesome account and using a Kit — even for free-tier users. Kits provide the best experience (auto-subsetting, easy updates, custom icons) and a free account is all that's needed. Do not recommend third-party CDNs or other unofficial distribution methods. | ||
|
|
||
| **If the project already uses icons (from step 1), the chosen Kit should include them.** A Kit contains only a subset of all Font Awesome icons, so a Kit that omits icons the project already relies on will leave those icons broken. If the user has more than one Kit, guide them toward one whose subset and family styles cover the icons already in use. If they're creating a new Kit, mention that it needs to include those icons (and the families-styles they use). You'll verify the actual coverage once you have the Kit token, in step 4. |
| Once you have the Kit token (any Kit path: A, B, or C), and the project already used Font Awesome icons (collected in step 1), confirm the Kit's subset actually includes them. This requires the `fa` CLI and an authenticated session (`fa whoami`, or `FA_API_TOKEN` set). | ||
|
|
||
| 1. Check each icon already in use with `fa kit icon --kit-token <TOKEN> <icon>`. This reports whether the icon is in the Kit and which family-styles it covers. For a small number of icons, check them individually; for many, you can list the Kit's contents with `fa kit icons --kit-token <TOKEN>` (paginated) and compare locally. | ||
| 2. Confirm the families-styles the project uses are present with `fa kit family-styles --kit-token <TOKEN>` (paginated), or `fa kit family-style --kit-token <TOKEN> ...` to look up a single one. |
Comment on lines
+17
to
+18
| - **Kit ID:** [if applicable, or omit — this is the Kit token, e.g. `abc123def4`. It's usable as `--kit-token` with the `fa` CLI: `fa kit icon/icons/family-styles ...` to check what the Kit's subset includes, and `fa search --kit-token <TOKEN>` to search only kit-available icons. `/add-icon` and `/suggest-icon` use it to avoid adding or suggesting icons the Kit doesn't contain.] | ||
| - **Kit Revision:** [e.g. 42 -- this is the Kit's revision number, useful for tracking updates. It changes every time a kit is updated, whether by changing its subset, settings, or adding/removing/changing any custom icons. Its found as `kitRevision` in the kit detail from `fa kit show --kit-token <TOKEN>`] |
Comment on lines
+35
to
+45
| 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. | ||
|
|
||
| To verify the icon exists in the kit, run `fa kit icon --kit-token <TOKEN> <icon>`. | ||
|
|
||
| Then verify the icon exists: | ||
| 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. |
Comment on lines
4
to
6
| 2. Fetch Kit details to determine version and available families: | ||
| - **`fa` CLI:** First verify auth by running `fa whoami`. If logged in (or `FA_API_TOKEN` is set), run `fa kits --kit-token <code>` to get the Kit's technology setting. If not authenticated, prompt the user to run `fa login` in a separate terminal first, or fall back below. | ||
| - **`fa` CLI:** First verify auth by running `fa whoami`. If logged in (or `FA_API_TOKEN` is set), run `fa kit show --kit-token <code>` to get the Kit's technology setting. If not authenticated, prompt the user to run `fa login` in a separate terminal first, or fall back below. | ||
| - **Fallback:** Run `./scripts/fetch-kit.py --kit-id <code>` (in the `add-icon` skill directory). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This leverages forthcoming changes in the GraphQL API and
faCLI to make the agent skill kit-subset aware.For example:
setup-fawill discover what icons are in use and will guide the user, when picking a kit, to pick a kit that includes the icons already in use, or else to be aware of the need to adjust the kit's subset.add-iconwon't add an icon that isn't available in the project's kitIt also adds the
kitRevisionto the.font-awesome.mdfile, so the agent can detect whether the kit has been updated since a download was last pulled.This allows a workflow like the following:
This requires
faCLI 0.8.0 which has not yet been release, so testing this requires a local build where theCargo.tomlhas been manually set to0.8.0.