setup-fa

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

从零开始在项目中搭建Font Awesome。本技能涵盖从检测项目类型、下载Kit或安装依赖包，到编写初始集成代码、创建

.font-awesome.md

文件的全流程，确保后续

/add-icon

命令可立即使用。

suggest-icon

引用的脚本路径相对于

plugins/icons/skills/suggest-icon/

，

add-icon

引用的脚本路径相对于

plugins/icons/skills/add-icon/

，请在对应的目录下运行这些脚本。

Important: bare SVG markup

重要提示：纯SVG标记

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.

切勿根据自身知识或训练数据生成Font Awesome SVG标记（原生
<svg>
元素）。如果搭建过程中需要纯SVG（例如用于验证），请使用

fa icons --version <version> --name <icon> --svg-format html

命令从Font Awesome API获取。此操作需要用户已登录（可通过

fa whoami

查看）或已设置

FA_API_TOKEN

环境变量。

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.

开始前，请检查项目根目录是否已存在

.font-awesome.md

文件。如果存在，说明Font Awesome已经配置完成。请告知用户并询问其是否需要重新配置、更新现有设置，或是有其他目标。如果用户对现有配置有疑问，提供

/fa-help

命令支持；如果用户想要开始使用图标，提供

/add-icon

命令支持。

Tool selection

工具选择

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 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
```
and
```
fa kit
```
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
fa
is not found: fall back to the Python scripts described below where applicable.
Use
```
latest-version.py
```
to get the latest version.

运行

command -v fa

命令，检查

fa

CLI是否在系统PATH中可用。

fa kit

子命令需要

fa

0.8.0或更高版本支持。如果需要使用

fa kit

子命令，建议用户按照此文档说明升级

fa

：https://docs.fontawesome.com/web/use-with/fa-cli

如果找到
fa
：使用它执行Kit相关操作和版本查询（它会返回结构化JSON）。对于Kit操作（
```
fa kits
```
和
```
fa kit
```
），请先检查认证状态：运行
```
fa whoami
```
查看用户是否已登录。如果已登录，
```
fa kits
```
和
```
fa kit
```
可直接使用；如果未登录但已设置
```
FA_API_TOKEN
```
，也可正常使用；如果两者都不满足，告知用户：“你需要登录Font Awesome CLI才能执行Kit相关操作。请在另一个终端中运行
```
fa login
```
完成登录后，再回到此处重试。”
如果未找到
fa
：在适用场景下改用下文描述的Python脚本。
使用
```
latest-version.py
```
获取最新版本。

Steps

操作步骤

1. Detect the project type

1. 检测项目类型

Use a subagent (via the Agent tool with

subagent_type: "Explore"

) to determine:

Package manager — look for
```
package.json
```
(npm/yarn/pnpm),
```
requirements.txt
```
/
```
pyproject.toml
```
(Python),
```
composer.json
```
(PHP),
```
Gemfile
```
(Ruby), or no package manager (static HTML).
Framework — look for:
- ```
react
```
  ,
```
react-dom
```
  ,
```
next
```
  ,
```
gatsby
```
  in package.json → React
- ```
vue
```
  ,
```
nuxt
```
  in package.json → Vue
- ```
angular.json
```
  or
```
@angular/core
```
  in package.json → Angular
- ```
ember-cli
```
  in package.json → Ember
- ```
svelte
```
  in package.json → Svelte
- ```
wp-content/
```
  ,
```
functions.php
```
  ,
```
style.css
```
  with WordPress theme headers → WordPress
- ```
.html
```
  files with no framework → static HTML
Existing Font Awesome traces — check if Font Awesome is partially installed (old version, broken setup, etc.). Look for
```
@fortawesome
```
packages in
```
package.json
```
, Kit script tags in HTML, CDN links, or Font Awesome CSS/font files.
Icons already in use — collect the set of Font Awesome icons the project already references, with the family and style for each where determinable. Look in class-based markup (
```
fa-solid fa-cart-shopping
```
,
```
fa-sharp fa-regular fa-user
```
), React/Vue imports (
```
faCartShopping
```
→
```
cart-shopping
```
),
```
<FontAwesomeIcon icon={...}>
```
/
```
icon={['far', 'cart-shopping']}
```
usages, sprite
```
<use href="...#icon-name">
```
, and
```
<fa-icon>
```
elements. This list drives the Kit-coverage check in step 4 — capture canonical icon names (kebab-case) and note the family-style when you can infer it.
License clues —
```
fontawesome-pro
```
packages, Pro CDN URLs, or Kit config indicating Pro.
Project structure — where HTML templates live, where CSS/JS entry points are, where components are defined.

If the user passed a

framework

argument, use that instead of auto-detecting.

The subagent should return a structured summary of what it found, including the list of icons already in use (with family-style where known).

使用子Agent（通过Agent工具，设置

subagent_type: "Explore"

）来确定以下信息：

包管理器 — 查找
```
package.json
```
（npm/yarn/pnpm）、
```
requirements.txt
```
/
```
pyproject.toml
```
（Python）、
```
composer.json
```
（PHP）、
```
Gemfile
```
（Ruby），或无包管理器（静态HTML）。
框架 — 查找以下特征：
- package.json中包含
```
react
```
  、
```
react-dom
```
  、
```
next
```
  、
```
gatsby
```
  → React
- package.json中包含
```
vue
```
  、
```
nuxt
```
  → Vue
- 存在
```
angular.json
```
  或package.json中包含
```
@angular/core
```
  → Angular
- package.json中包含
```
ember-cli
```
  → Ember
- package.json中包含
```
svelte
```
  → Svelte
- 存在
```
wp-content/
```
  、
```
functions.php
```
  、带有WordPress主题头的
```
style.css
```
  → WordPress
- 无框架的
```
.html
```
  文件 → 静态HTML
现有Font Awesome痕迹 — 检查是否已部分安装Font Awesome（旧版本、配置损坏等）。查找
```
package.json
```
中的
```
@fortawesome
```
包、HTML中的Kit脚本标签、CDN链接，或Font Awesome CSS/字体文件。
已使用的图标 — 收集项目中已引用的所有Font Awesome图标，尽可能确定每个图标的系列和样式。查找范围包括：基于类的标记（
```
fa-solid fa-cart-shopping
```
、
```
fa-sharp fa-regular fa-user
```
）、React/Vue导入（
```
faCartShopping
```
→
```
cart-shopping
```
）、
```
<FontAwesomeIcon icon={...}>
```
/
```
icon={['far', 'cart-shopping']}
```
用法、雪碧图
```
<use href="...#icon-name">
```
以及
```
<fa-icon>
```
元素。该列表用于第4步的Kit覆盖范围检查——请记录规范的图标名称（短横线命名法），并在可推断时注明系列-样式。
许可证线索 —
```
fontawesome-pro
```
包、Pro版CDN URL，或表明是Pro版的Kit配置。
项目结构 — HTML模板的存放位置、CSS/JS入口点位置、组件定义位置。

如果用户传入了

framework

参数，则使用该参数值，无需自动检测。

子Agent应返回结构化的检测结果摘要，包括已使用的图标列表（已知系列-样式的需注明）。

2. Recommend an integration method

2. 推荐集成方式

Based on the project type and any user preference (

method

argument), recommend one of these approaches. If the user specified a

method

, use that. Otherwise, follow this decision tree:

Has a Font Awesome account/Kit?
├── Yes → Kit (best experience, auto-subsetting, custom icons, easy updates)
│   ├── JS framework (React/Vue/Angular)? → Kit Package via npm (@awesome.me/kit-*)
│   ├── Static HTML / server-rendered? → Kit embed code (script tag or CSS link)
│   └── Desktop app? → Kit download (desktop)
└── No / Unknown
    └── Recommend signing up at https://fontawesome.com (free accounts available)
        then follow the Kit path above.

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 family-styles they use). You'll verify the actual coverage once you have the Kit token, in step 4.

Present the recommendation to the user with a brief explanation of why. Wait for the user to confirm before proceeding — setup involves installing packages or modifying project files.

根据项目类型和用户偏好（

method

参数），推荐以下方案之一。如果用户指定了

method

，则直接使用该方案；否则遵循以下决策树：

Has a Font Awesome account/Kit?
├── Yes → Kit (best experience, auto-subsetting, custom icons, easy updates)
│   ├── JS framework (React/Vue/Angular)? → Kit Package via npm (@awesome.me/kit-*)
│   ├── Static HTML / server-rendered? → Kit embed code (script tag or CSS link)
│   └── Desktop app? → Kit download (desktop)
└── No / Unknown
    └── Recommend signing up at https://fontawesome.com (free accounts available)
        then follow the Kit path above.

始终推荐用户注册Font Awesome账号并使用Kit——即使是免费版用户也不例外。Kit能提供最佳使用体验（自动子集化、更新便捷、支持自定义图标），且仅需一个免费账号即可使用。请勿推荐第三方CDN或其他非官方分发方式。

如果项目已经在使用图标（来自第1步的检测结果），所选的Kit必须包含这些图标。 Kit仅包含全部Font Awesome图标的一个子集，因此如果Kit未包含项目已依赖的图标，这些图标将无法正常显示。如果用户有多个Kit，引导用户选择其子集和系列样式能覆盖已使用图标的那个。如果用户要创建新的Kit，需说明新Kit必须包含这些图标（以及对应的系列-样式）。你将在第4步获取Kit令牌后验证实际的覆盖范围。

向用户展示推荐方案并简要说明原因。请等待用户确认后再继续操作——搭建过程涉及安装依赖包或修改项目文件。

3. Fetch documentation for the chosen method

3. 获取所选方案的文档

Use

WebFetch

to retrieve

https://docs.fontawesome.com/llms.txt

— this is an index of all available documentation pages with URLs and descriptions. Scan the index to find the setup page(s) most relevant to the chosen integration method and framework. Look for URLs containing keywords like

setup

use-kit

packages

host-yourself

use-with/react

use-with/vue

kit-download

, etc.

Then fetch the relevant page(s) using

WebFetch

. When fetching, use a prompt like: "Return the full content of this documentation page as Markdown. Preserve all headings, code blocks, and tables."

This ensures the instructions are current and version-accurate. Do not rely on training data alone for setup instructions — the docs are authoritative.

使用

WebFetch

获取

https://docs.fontawesome.com/llms.txt

——这是所有可用文档页面的索引，包含URL和描述。扫描该索引，找到与所选集成方式和框架最相关的搭建页面。查找包含

setup

、

use-kit

、

packages

、

host-yourself

、

use-with/react

、

use-with/vue

、

kit-download

等关键词的URL。

然后使用

WebFetch

获取相关页面的内容。获取时，使用类似如下的提示词：“以Markdown格式返回此文档页面的完整内容，保留所有标题、代码块和表格。”

这能确保操作说明是最新且版本准确的。请勿仅依赖训练数据提供搭建说明——文档才是权威依据。

4. Execute the setup

4. 执行搭建

Follow the path that matches the chosen method. Each path is documented in a separate reference file under

references/

(relative to this skill's directory). Read the appropriate file for detailed instructions.

Method	Reference file
Kit embed code (script tag or CSS link)	`references/path-a-kit-embed.md`
Kit package via npm ( `@awesome.me/kit-*` )	`references/path-b-kit-npm.md`
Kit download (self-host or desktop)	`references/path-c-kit-download.md`
npm packages without a Kit ( `@fortawesome/*` )	`references/path-d-npm-packages.md`

After completing the path-specific steps, if the method involved installing npm packages (Paths B, D), read

references/path-f-framework-init.md

for framework-specific initialization code.

按照与所选方案匹配的路径操作。每条路径都记录在

references/

目录（相对于本技能的目录）下的单独参考文件中。请阅读对应的文件获取详细操作说明。

方法	参考文件
Kit嵌入代码（script标签或CSS链接）	`references/path-a-kit-embed.md`
通过npm安装Kit包（ `@awesome.me/kit-*` ）	`references/path-b-kit-npm.md`
Kit下载（自托管或桌面端）	`references/path-c-kit-download.md`
不使用Kit的npm包（ `@fortawesome/*` ）	`references/path-d-npm-packages.md`

完成对应路径的步骤后，如果方案涉及安装npm包（路径B、D），请阅读

references/path-f-framework-init.md

获取框架特定的初始化代码。

Verify the Kit covers the icons already in use

验证Kit覆盖已使用的图标

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).

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.
Confirm the family-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.
If any in-use icon (or its family style) is missing from the Kit, warn the user explicitly. List exactly which icons are not covered and in which family styles, for example:
Your project uses
```
fa-thin fa-binoculars
```
and
```
fa-duotone fa-compass
```
, but this Kit doesn't include them:
```
binoculars
```
is missing the thin style, and
```
compass
```
isn't in the Kit at all. Those icons will not render. You can add them to your Kit at https://fontawesome.com/kits and re-run, choose a different Kit that includes them, or proceed and replace them with kit-available alternatives (try
```
/suggest-icon
```
).
Let the user decide how to proceed before finishing setup. Do not silently configure a Kit that omits icons the project already depends on.

If the

fa

CLI isn't available or the user can't authenticate, note that you couldn't verify Kit coverage and that any icons missing from the Kit's subset won't render.

获取Kit令牌后（任何Kit路径：A、B、C），如果项目已经在使用Font Awesome图标（第1步收集的），请确认Kit的子集确实包含这些图标。此操作需要

fa

CLI和已认证的会话（通过

fa whoami

验证，或已设置

FA_API_TOKEN

）。

使用
```
fa kit icon --kit-token <TOKEN> <icon>
```
检查每个已使用的图标。该命令会返回图标是否在Kit中，以及覆盖哪些系列-样式。如果图标数量较少，逐个检查；如果数量较多，可以使用
```
fa kit icons --kit-token <TOKEN>
```
（分页）列出Kit的所有内容，在本地进行比对。
使用
```
fa kit family-styles --kit-token <TOKEN>
```
（分页）确认项目使用的系列-样式是否存在，或使用
```
fa kit family-style --kit-token <TOKEN> ...
```
查询单个系列-样式。
如果有任何正在使用的图标（或其系列样式）不在Kit中，请明确警告用户。准确列出未被覆盖的图标及其对应的系列样式，例如：
你的项目使用了
```
fa-thin fa-binoculars
```
和
```
fa-duotone fa-compass
```
，但该Kit不包含这些图标：
```
binoculars
```
缺少thin样式，
```
compass
```
完全不在Kit中。这些图标将无法渲染。你可以在https://fontawesome.com/kits 将它们添加到你的Kit中然后重新运行，选择另一个包含它们的Kit，或者继续操作并使用Kit中可用的替代图标（可尝试
```
/suggest-icon
```
）。

在完成搭建前，请让用户决定如何继续。切勿在未告知的情况下配置一个缺少项目已依赖图标的Kit。

如果

fa

CLI不可用或用户无法完成认证，请说明你无法验证Kit的覆盖范围，且Kit子集中未包含的任何图标都将无法渲染。

5. Verify the setup

5. 验证搭建结果

Add a test icon to confirm everything is working:

Find a visible template or component in the project.
Add a simple icon (e.g.,
```
fa-check
```
or
```
fa-font-awesome
```
) using the appropriate syntax for the integration method.
Tell the user to preview the page/app to confirm the icon renders.
If they report issues, refer back to the
```
llms.txt
```
index to find the relevant troubleshooting page (look for URLs containing
```
troubleshoot
```
) and fetch it to guide diagnosis.

添加一个测试图标以确认一切正常运行：

在项目中找到一个可见的模板或组件。
使用集成方案对应的语法，添加一个简单的图标（例如
```
fa-check
```
或
```
fa-font-awesome
```
）。
告知用户预览页面/应用，确认图标正常渲染。
如果用户反馈有问题，回到
```
llms.txt
```
索引查找相关的故障排查页面（查找包含
```
troubleshoot
```
的URL）并获取内容，以指导问题诊断。

6. Write

.font-awesome.md

6. 编写

.font-awesome.md

文件

Create

.font-awesome.md

in the project root. Read

font-awesome-md-format.md

(in the

add-icon

skill directory,

plugins/icons/skills/add-icon/

) for the template and format to use. Populate it with everything discovered and configured during setup.

Tell the user: "I've written

.font-awesome.md

with your project's Font Awesome configuration. Commit this file so the team benefits and

/add-icon

works immediately."

在项目根目录创建

.font-awesome.md

文件。请阅读

add-icon

技能目录（

plugins/icons/skills/add-icon/

）下的

font-awesome-md-format.md

文件，了解要使用的模板和格式。将搭建过程中发现和配置的所有信息填入该文件。

告知用户：“我已经编写了

.font-awesome.md

文件，记录了你项目的Font Awesome配置。请提交该文件，以便团队受益，同时

/add-icon

命令可立即使用。”

7. Next steps

7. 后续步骤

After setup is complete, tell the user what they can do next:

Add icons: "Run
```
/add-icon <icon-name>
```
to add any Font Awesome icon to your code."
Find icons: "Run
```
/suggest-icon <concept>
```
to find the right icon for your use case."
Get help: "Run
```
/fa-help <question>
```
to get answers from the official Font Awesome docs."

搭建完成后，告知用户接下来可以进行的操作：

添加图标： “运行
```
/add-icon <icon-name>
```
将任意Font Awesome图标添加到你的代码中。”
查找图标： “运行
```
/suggest-icon <概念>
```
为你的使用场景找到合适的图标。”
获取帮助： “运行
```
/fa-help <问题>
```
从Font Awesome官方文档获取答案。”

setup-fa

Original

Translation

Important: bare SVG markup

重要提示：纯SVG标记

Pre-flight check

前置检查

Tool selection

工具选择

Steps

操作步骤

1. Detect the project type

1. 检测项目类型

2. Recommend an integration method

2. 推荐集成方式

3. Fetch documentation for the chosen method

3. 获取所选方案的文档

4. Execute the setup

4. 执行搭建

Verify the Kit covers the icons already in use

验证Kit覆盖已使用的图标

5. Verify the setup

5. 验证搭建结果

6. Write
`.font-awesome.md`

6. 编写
`.font-awesome.md`
文件

7. Next steps

7. 后续步骤

setup-fa

Original

Translation

Important: bare SVG markup

重要提示：纯SVG标记

Pre-flight check

前置检查

Tool selection

工具选择

Steps

操作步骤

1. Detect the project type

1. 检测项目类型

2. Recommend an integration method

2. 推荐集成方式

3. Fetch documentation for the chosen method

3. 获取所选方案的文档

4. Execute the setup

4. 执行搭建

Verify the Kit covers the icons already in use

验证Kit覆盖已使用的图标

5. Verify the setup

5. 验证搭建结果

6. Write .font-awesome.md

6. 编写.font-awesome.md文件

7. Next steps

7. 后续步骤

6. Write
`.font-awesome.md`

6. 编写
`.font-awesome.md`
文件