mcpField
A
add-icon

add-icon

github.com/fortawesomeデザイン・UI4582 回インストール17 週間前に更新
リポジトリ

add-icon について

アイコン名を解決し、既存の統合方式を判別して、それに合わせたコードを生成する Font Awesome 用スキルです。Kit の対象範囲を確認し、プロジェクトの既存パターンに沿ってコードを作成します。

主な機能

  1. 01アイコン名の解決と確認
  2. 02Font Awesome 統合方式の判別
  3. 03Kit の対象アイコン確認
  4. 04既存のプロジェクトパターンに沿ったコード生成
  5. 05設定を `.font-awesome.md` に記録

活用シーン

  1. 01Font Awesome を使うプロジェクトにアイコンを追加
  2. 02設定済み Kit にアイコンが含まれるか確認
  3. 03プロジェクトの統合方式に合わせてアイコンコードを作成

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/fortawesome/fontawesome-agent-tools --skill add-icon

インストール後、Claude Code で/add-iconを入力して読み込まれたか確認します。

同梱ファイルfont-awesome-md-format.mdscripts/fetch-kit.py

詳細

ユーザーのプロジェクトに Font Awesome アイコンを追加します。このスキルでは、すべての Font Awesome 統合方法について、アイコン名の解決、プロジェクトの検出、コードの生成を行います。

suggest-icon から参照されるスクリプトは plugins/icons/skills/suggest-icon/ からの相対パスです。add-icon から参照されるスクリプトは plugins/icons/skills/add-icon/ からの相対パスです。それぞれのディレクトリから実行してください。

ツールの選択

最初に command -v fa を実行して、fa CLI が PATH で利用可能か確認してください。

fa kit サブコマンドには、バージョン 0.8.0 以降の fa が必要です。fa kit サブコマンドが必要な場合は、こちらの手順に従って fa をアップグレードするようユーザーに案内してください：https://docs.fontawesome.com/web/use-with/fa-cli

  • fa が見つかった場合： アイコンの検索と Kit の取得には fa を使用してください（構造化 JSON が返されます）。Kit の操作（fa kits と fa kit）を行う場合は、最初に認証を確認してください。fa whoami を実行して、ユーザーがログインしているか確認します。ログイン済みであれば、これらの操作をそのまま実行できます。ログインしていなくても、FA_API_TOKEN が設定されていれば実行できます。どちらにも該当しない場合は、ユーザーに次のように伝えてください：「Kit の操作には Font Awesome CLI へのログインが必要です。別のターミナルで fa login を実行してから、ここに戻ってもう一度お試しください。」ログインできない場合は、fetch-kit.py に切り替えてください。プロジェクトが Kit を使用している場合、fa kit icon --kit-token <TOKEN> <icon> を実行すると、特定のアイコンが Kit のサブセットに含まれているか、また利用可能なファミリースタイルがわかります。これは、Kit に含まれていないアイコンを追加しないために使用してください（手順 3 を参照）。
  • fa が見つからない場合： 以下で説明する Python スクリプトに切り替えてください。
  • 最新バージョンの取得には latest-version.py を使用してください。

手順

1. アイコン名を解決する

まず、プロジェクトで Font Awesome の統合に Kit を使用しているか確認してください。プロジェクトに .font-awesome.md ファイルがある場合は、それを読んで Kit が使用されているか確認してください。

プロジェクトが Kit を使用している場合

プロジェクトが Kit を使用している場合は、アイコンがその Kit のサブセットに含まれていることを確認してください。これを確認できるのは fa CLI だけです。ユーザーがログインしていない場合は、最初に別のターミナルで fa login を実行するよう案内してください。

fa CLI が利用できない場合は、アイコンが Kit のサブセットに含まれているか確認できないことをユーザーに伝えてください。fa CLI をインストールし、fa login でログインしてから、このスキルを再実行するよう提案してください。

Kit にアイコンが含まれているか確認するには、fa kit icon --kit-token <TOKEN> <icon> を実行してください。

アイコンが含まれていない場合は、ユーザーの icon 引数をユースケースとして、/suggest-icon スキルを内部的に呼び出してください。候補があれば、確認を求めずに最上位の候補を自動的に採用してください。

/suggest-icon が候補を提示しない場合は、Kit のサブセットにユーザーのクエリと類似するアイコンが含まれていない可能性があります。その場合は、fa search --version <version> --query <icon> を使用して、Kit だけでなく Font Awesome 全体から類似するアイコンを検索してください。ユーザーが指定したアイコンは Kit のサブセットに含まれていないことと、https://fontawesome.com/kits で Kit に追加できることを伝えてください。

プロジェクトが Kit を使用していない場合

プロジェクトが Kit を使用していない場合は、アイコンが存在することを確認してください。

使用中の Font Awesome のバージョンを特定します。最初に .font-awesome.md から確認し、そこに記載がなければ latest-version.py を使用して最新バージョンを取得します。以下のコマンドでは、このバージョンを <version> として使用してください。

  • fa CLI： fa icons --version <version> --name <icon> を実行してください。data.release.icon が null でなければ、アイコンは存在します。familyStylesByLicense フィールドには、Free と Pro の内訳が表示されます。
  • フォールバック： ./scripts/icon-exists.py --version <version> --icon-name <icon> を実行してください。終了コード 0 はアイコンが存在することを、終了コード 1 は存在しないことを示します。

アイコンが存在しない場合は、ユーザーの icon 引数をユースケースとして、/suggest-icon スキルを内部的に呼び出してください。最上位の候補を自動的に採用し、そのアイコン名で続行してください。ユーザーに確認を求めないでください。動作するアイコンを使うほうが、動作しないアイコンを使うより適切です。

2. 統合方法を確認する

プロジェクトのルートに .font-awesome.md ファイルがあるか確認します。

.font-awesome.md がある場合

ファイルを読み、記載されている設定を使用します。調査は省略し、ステップ 3 に進みます。ただし、ファイルの内容は覚えておいてください。後続のステップで、ファイルに記載されていない情報や不完全な情報（例：新しいインポートパターン、記載されていないファミリー、説明のないラッパーコンポーネント）が判明した場合は、最後にファイルを更新します（ステップ 6 を参照）。

.font-awesome.md がない場合

プロジェクトで Font Awesome がどのように使用されているかを把握するため、調査を行います。この調査には、サブエージェント（subagent_type: "Explore" を指定した Agent ツール経由）を使用します。サブエージェントは、以下の情報源を詳細度の高い順に検索し、見つかった内容を構造化してまとめます。

  1. package.json / ロックファイル — Font Awesome パッケージを確認します。

    • @fortawesome/react-fontawesome → React コンポーネント統合
    • @fortawesome/vue-fontawesome → Vue コンポーネント統合
    • @fortawesome/fontawesome-svg-core → SVG コア（React/Vue で使用）
    • @fortawesome/fontawesome-free または @fortawesome/fontawesome-pro → 汎用 SVG+JS またはウェブフォント
    • @fortawesome/free-solid-svg-icons、@fortawesome/pro-solid-svg-icons など → 個別のアイコンパッケージ（スタイルとライセンスも記録します）

  2. HTML ファイル / テンプレート — 以下を確認します。

    • Font Awesome Kit のスクリプトタグ：<script src="https://kit.fontawesome.com/XXXXXX.js"...> → Kit（SVG+JS）。Kit ID（.js より前のトークン）を抽出します。
    • <link> タグ内の CDN リンク：cdnjs.cloudflare.com/ajax/libs/font-awesome/ または use.fontawesome.com → CDN 経由の Web Fonts+CSS
    • <i class="fa-solid fa-..."> または <i class="fas fa-..."> の使用パターン → クラスベース（Web Fonts+CSS または SVG+JS）

  3. ソースファイル内のインポート文 — 以下を検索します。

    • import { FontAwesomeIcon } → React コンポーネント
    • import { library } from @fortawesome/fontawesome-svg-core → ライブラリー方式
    • import { faCoffee } のような個別のアイコンのインポート → 個別インポート方式

  4. SVG スプライトシート — <use href="...sprites/..."> のパターン、またはスプライト SVG ファイルを確認します。

  5. ウェブコンポーネント — <fa-icon> カスタム要素を確認します。

  6. その他のフレームワーク — Angular（angular.json、FontAwesomeModule）、Svelte などを確認します。

サブエージェントは、インストールされている Font Awesome パッケージ（バージョンを含む）、見つかった Kit ID、CDN URL、フレームワーク統合方法、ソースファイルで確認されたインポートパターン、ライセンス（free または pro）、およびプロジェクトの規約（ラッパーコンポーネント、デフォルトのサイズ指定など）を報告します。

サブエージェントからの報告後、Kit ID が見つかった場合は、Kit の詳細を取得します。

  • fa CLI： fa kit show --kit-token <id> を実行します。Kit のバージョン、ライセンス、テクノロジー、利用可能なファミリーを含む JSON が返されます。実行には、ユーザーがログイン済みである（fa whoami が成功する）か、FA_API_TOKEN が設定されている必要があります。どちらも満たされていない場合は、先に別のターミナルで fa login を実行するようユーザーに依頼します。
  • 代替手段： add-icon スキルディレクトリで ./scripts/fetch-kit.py --kit-id <id> を実行し、Kit のバージョン、ライセンス、方式、利用可能なファミリーを取得します。

調査後、以下を判断します。

  • 統合方法 — アイコンのレンダリングに使用する主な方法
  • Kit ID / CDN URL — Kit または CDN を使用している場合
  • ライセンス — free または pro。次の情報から判定します：Kit の設定（fetch-kit.py 経由）、npm パッケージ名（fontawesome-free と fontawesome-pro、free-*-svg-icons と pro-*-svg-icons）、または CDN URL のパターン。
  • デフォルトのスタイル — プロジェクトで最もよく使われているスタイル（solid、regular、light、thin、duotone）。判別できない場合は、solid をデフォルトにします。
  • デフォルトのファミリー — プロジェクトで最もよく使われているファミリー（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）。判別できない場合は、classic をデフォルトにします。
  • 利用可能なファミリー — プロジェクトが利用できるファミリーの一覧。Kit の場合は、fetch-kit.py の出力を使用します。npm の場合は、インストール済みパッケージから推定します。free ユーザーが利用できるのは classic のみです。
  • インポートパターン — JS フレームワークの場合：ファイルごとの個別インポートか、ライブラリへの登録か
  • バージョン — 使用中の Font Awesome のバージョン
  • プロジェクトの規約 — 確認されたラッパーコンポーネント、標準のサイズ指定、またはパターン

結果をプロジェクトのルートにある .font-awesome.md に書き込みます。このスキルのディレクトリ（plugins/icons/skills/add-icon/）にある font-awesome-md-format.md を読み、使用するテンプレートとフォーマットを確認してください。

ユーザーには次のように伝えてください："I've written .font-awesome.md with your project's Font Awesome configuration. You should commit this file so the team benefits and future icon additions are faster."

次のステップに進む前に、必ず .font-awesome.md を書き込んでください。 残りのステップはこのファイルに依存します。調査しても意味のある .font-awesome.md を作成するのに十分な情報が得られない場合は、そこで作業を止め、続行する前に Font Awesome の設定についてユーザーに確認してください。

3. アイコンのスタイルとファミリーを決定する

スタイル — 次の優先順位に従います。

  1. ユーザーが style 引数を渡した場合は、それを使用します。
  2. そうでない場合は、.font-awesome.md に記載されたデフォルトのスタイルを使用します。
  3. どちらも指定されていない場合は、solid をデフォルトにします。

ファミリー — 次の優先順位に従います。

  1. ユーザーがファミリーを明示的に指定した場合は、それを使用します。
  2. そうでない場合は、.font-awesome.md に記載されたデフォルトのファミリーを使用します。
  3. どちらも指定されていない場合は、classic をデフォルトにします。

.font-awesome.md に Kit ID（Kit トークン）が記録されている場合、プロジェクトのアイコンは Kit から提供されており、Kit に含まれるのは Font Awesome の全アイコンの一部のみです。Kit に含まれていないアイコンを追加しないでください — 表示されません。

プロジェクトが Kit を使用しているかどうかに基づき、選択したスタイルとファミリーでそのアイコンを利用できることを確認してください。

プロジェクトが Kit を使用している場合

ステップ 1「アイコン名の解決」で実行した fa kit icon --kit-token <TOKEN> <icon> の出力を再利用します。そこでアイコン名を解決するために使用した出力を、選択したファミリーとスタイルでアイコンを利用できるか確認する際にも使用できます。

選択したファミリーとスタイルでそのアイコンを利用できず、別のファミリーとスタイルなら利用できる場合は、その旨をユーザーに伝え、利用可能な別のファミリーとスタイルを使うか、Kit のサブセットに不足しているものを追加するかを尋ねてください。

アイコンが Kit にまったく含まれていない場合は、コードを生成する前に作業を止めてください。そのアイコンが Kit のサブセットに含まれていないことをユーザーに伝え、次の 2 つの方法を提示してください：（a）https://fontawesome.com/kits でアイコンを Kit に追加して再実行する、または（b）Kit で利用可能な代替アイコンを選ぶ — /suggest-icon（Kit 対応）を実行して候補を探せます。Kit にないアイコンを黙って追加しないでください。

Kit に含まれるアイコンを一覧するには、fa kit family-styles --kit-token <TOKEN> で利用可能なファミリーとスタイルを確認でき、fa kit icons --kit-token <TOKEN> で利用可能なアイコンのバリエーション（特定のファミリーとスタイルに属するアイコン）を一覧できます。どちらもページ分割されたクエリです。

プロジェクトで Kit を使用していない場合

icon-exists.py を実行します。出力には、利用可能なファミリーとスタイルが表示されます。リクエストされたスタイルまたはファミリーでアイコンを利用できない場合は、その旨をユーザーに伝え、利用可能な代替案を提案します。また、選択したファミリーがプロジェクトの利用可能なファミリー一覧に含まれていることも確認します。含まれていない場合は、ユーザーに警告します。

4. コードを生成する

.font-awesome.md に記載された統合方法に基づいて、適切なコードを生成します。各方法のパターンを以下に示します。プロジェクト内で確認できる慣例に合わせ、すでに確立されたパターンがある場合は新たなパターンを導入しないでください。

React（@fortawesome/react-fontawesome）

個別インポート（プロジェクトでこのパターンが使われている場合に推奨）：

import { faCartShopping } from '@fortawesome/pro-solid-svg-icons'
// or @fortawesome/free-solid-svg-icons for free icons

<FontAwesomeIcon icon={faCartShopping} />

インポート名は、アイコン名をキャメルケースにし、先頭に fa を付けたものです。例：cart-shopping → faCartShopping。

パッケージ名は、@fortawesome/{free|pro}-{style}-svg-icons のパターンに従います。例：

  • @fortawesome/free-solid-svg-icons
  • @fortawesome/pro-regular-svg-icons
  • @fortawesome/pro-duotone-svg-icons
  • @fortawesome/sharp-solid-svg-icons
  • @fortawesome/sharp-duotone-svg-icons

ライブラリー方式（プロジェクトでアイコンをグローバルに登録している場合）：

// In the library setup file:
import { library } from '@fortawesome/fontawesome-svg-core'
import { faCartShopping } from '@fortawesome/pro-solid-svg-icons'
library.add(faCartShopping)

// In components — use string reference:
<FontAwesomeIcon icon="cart-shopping" />
// or with explicit prefix for non-solid styles:
<FontAwesomeIcon icon={['far', 'cart-shopping']} />

スタイルの接頭辞：fas（solid）、far（regular）、fal（light）、fat（thin）、fad（duotone）、fass（sharp solid）、fasr（sharp regular）、fasl（sharp light）、fast（sharp thin）、fasd（sharp duotone）。

Vue（@fortawesome/vue-fontawesome）

React と同様ですが、Vue コンポーネントの構文を使用します。

<font-awesome-icon :icon="['fas', 'cart-shopping']" />

インポートには、React と同じパッケージ名と命名規則を使用します。

SVG+JS Kit（<script src="https://kit.fontawesome.com/...">）
<i class="fa-solid fa-cart-shopping"></i>

クラスのパターンはファミリーによって異なります。

  • classic（デフォルト。ファミリーの接頭辞は不要）：fa-{style} fa-{icon-name}
    • <i class="fa-solid fa-cart-shopping"></i>
  • sharp：fa-sharp fa-{style} fa-{icon-name}
    • <i class="fa-sharp fa-regular fa-cart-shopping"></i>
  • sharp-duotone：fa-sharp-duotone fa-{style} fa-{icon-name}
    • <i class="fa-sharp-duotone fa-solid fa-cart-shopping"></i>
  • duotone：fa-duotone fa-{style} fa-{icon-name}
    • <i class="fa-duotone fa-solid fa-cart-shopping"></i>
  • その他の FA7 ファミリー（chisel、etch、graphite、jelly、jelly-duo、jelly-fill、notdog、notdog-duo、slab、slab-press、thumbprint、utility、utility-duo、utility-fill、whiteboard）：fa-{family} fa-{style} fa-{icon-name}
    • <i class="fa-slab fa-solid fa-cart-shopping"></i>
    • <i class="fa-jelly fa-regular fa-cart-shopping"></i>

インポートは不要です。読み込みは Kit が処理します。

Web Fonts+CSS（CDN または npm）

SVG+JS Kit と同じクラス構文を使用します。

<i class="fa-solid fa-cart-shopping"></i>

ファミリーの接頭辞も同じように機能します（例：fa-sharp fa-solid fa-cart-shopping）。適切な CSS ファイル（all.css または個別のスタイルシート）が読み込まれていることを確認します。

SVG スプライト
<svg class="icon">
  <use href="/path/to/sprites/solid.svg#cart-shopping"></use>
</svg>

プロジェクト内の他の箇所で使われているスプライトのパスに合わせます。

Angular
<fa-icon [icon]="faCartShopping"></fa-icon>

コンポーネントの TypeScript ファイルで、対応するインポートを行います。

Web Components（<fa-icon>）
<fa-icon class="fa-solid fa-cart-shopping"></fa-icon>
重要：SVG の直接記述

自分の知識や学習データをもとに、Font Awesome の SVG マークアップ（生の <svg> 要素）を生成してはいけません。 ユーザーが SVG を直接出力する必要がある場合（たとえば、アイコンを <svg> 要素としてインライン化する場合）は、fa CLI を使用して Font Awesome API から取得する必要があります。

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

--svg-format フラグで指定できるのは、html、data、icon-definition です。この操作には、ユーザーがログインしている（fa whoami）か、FA_API_TOKEN が設定されている必要があります。どちらも満たされていない場合は、まず別のターミナルで fa login を実行するようユーザーに案内してください。

SVG のパスデータを推測したり、再構成したり、近似したりしてはいけません。常に Font Awesome API を正式な情報源として使用してください。

5. 挿入または表示

ユーザーが location 引数を指定した場合：

コード内で指定された場所を探します。必要なインポート文をファイルの先頭に追加し、アイコンのコードを挿入します。フォーマットや配置は、プロジェクトの既存のパターンに従ってください。

場所が指定されていない場合：

適切な言語タグを付けたフェンス付きコードブロックで、コードスニペットを提示します。インポートが必要な場合は、どこに記述するかユーザーにわかるよう、別に示してください。

出力例：

このインポートを追加してください（まだ追加されていない場合）：

import { faCartShopping } from '@fortawesome/pro-solid-svg-icons'

次に、コンポーネントを使用します：

<FontAwesomeIcon icon={faCartShopping} />
6. Pro アイコンに関する注意

アイコンが Pro 専用で、プロジェクトが無料プランを使用している場合（.font-awesome.md のライセンスフィールド、または検出されたパッケージに基づく）、ユーザーに警告します：

注意：cart-shopping の使用には、Font Awesome Pro のサブスクリプションが必要です。プロジェクトでは Font Awesome Free が使用されているようです。

7. 必要に応じて .font-awesome.md を更新

今回の実行で判明した情報に .font-awesome.md に記載されていないものがないか確認します。不足している可能性のある情報の例：

  • Import Pattern に記載されていない新しいインポートパターンが使われた
  • Families に記載されていないファミリーまたはスタイルが見つかった
  • Conventions に記載されていないラッパーコンポーネントまたはプロジェクトの規約が確認された
  • バージョン、ライセンス、または統合方法が変更された

情報が不足している、または古くなっている場合は、新しい情報を .font-awesome.md に反映します。同じ形式を維持し、不足している情報だけを補ってください。すでに正確なセクションは書き換えないでください。ユーザーが変更をコミットできるよう、更新した内容を知らせてください。

コメント

Markdown 対応