setup-fa

プロジェクトに Font Awesome をゼロからセットアップします。このスキルでは、プロジェクトの種類の検出から、Kit のダウンロードまたはパッケージのインストール、初期統合コードの記述、.font-awesome.md の作成まで、すべてに対応します。これにより、その直後から /add-icon を使用できます。

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

重要：SVG マークアップを直接記述しないでください

自身の知識や学習データをもとに、Font Awesome の SVG マークアップ（生の <svg> 要素）を生成しないでください。 セットアップ中に SVG を直接記述する必要がある場合（検証など）、Font Awesome API から fa icons --version <version> --name <icon> --svg-format html を使用して取得してください。これには、ユーザーがログインしている（fa whoami）か、FA_API_TOKEN が設定されている必要があります。

事前確認

作業を始める前に、プロジェクトのルートに .font-awesome.md がすでに存在するか確認してください。存在する場合、Font Awesome はすでに設定されています。そのことをユーザーに伝え、設定をやり直したいのか、セットアップを更新したいのか、それとも別の目的があるのかを尋ねてください。現在のセットアップについて質問がある場合は /fa-help を、アイコンを使い始めたい場合は /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 kits と fa kit をそのまま使用できます。ログインしていなくても、FA_API_TOKEN が設定されていれば使用できます。どちらも該当しない場合は、ユーザーに次のように伝えてください：「Kit 操作には Font Awesome CLI へのログインが必要です。別のターミナルで fa login を実行してから、こちらに戻ってもう一度お試しください。」
• fa が見つからない場合： 該当する場合は、以下で説明する Python スクリプトに切り替えてください。
• 最新バージョンを取得するには latest-version.py を使用してください。

手順

1. プロジェクトの種類を判定する

サブエージェント（subagent_type: "Explore" を指定して Agent ツールを使用）を使い、次の項目を確認します。

• パッケージマネージャー — 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 引数を渡した場合は、自動判定の代わりにその値を使用します。

サブエージェントは、見つかった内容を構造化した要約として返します。すでに使用されているアイコンの一覧も、判別できる場合はファミリーとスタイルを含めます。

2. 導入方法を提案する

プロジェクトの種類とユーザーの希望（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 を作成する場合は、使用中のアイコンとファミリースタイルを含める必要があると説明します。Kit トークンを入手したら、ステップ 4 で実際の対応状況を確認します。

理由を簡潔に説明しながら、ユーザーに導入方法を提案します。先に進む前に、ユーザーの確認を待ってください。 セットアップでは、パッケージのインストールやプロジェクトファイルの変更が必要です。

3. 選択した方法のドキュメントを取得する

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. セットアップを実行する

選択した方法に合った手順に従います。それぞれの手順は、このスキルのディレクトリ内にある 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 を読みます。

Kit に現在使われているアイコンが含まれているか確認する

Kit のトークンを取得したら（Kit を使うすべてのパス A、B、C が対象です）、プロジェクトですでに Font Awesome アイコンが使われている場合は（手順 1 で収集）、Kit のサブセットにそれらが実際に含まれているか確認します。この確認には、fa CLI と認証済みセッション（fa whoami、または FA_API_TOKEN の設定）が必要です。

1. 現在使われている各アイコンについて、fa kit icon --kit-token <TOKEN> <icon> を実行します。Kit にそのアイコンが含まれているか、また対応するファミリーとスタイルが表示されます。アイコンの数が少ない場合は個別に確認し、多い場合は fa kit icons --kit-token <TOKEN>（ページネーションあり）で Kit の内容を一覧表示し、ローカルで照合できます。

2. プロジェクトで使っているファミリーとスタイルが含まれていることを、fa kit family-styles --kit-token <TOKEN>（ページネーションあり）で確認するか、単一のものを調べる場合は fa kit family-style --kit-token <TOKEN> ... を使って確認します。

3. 使用中のアイコン（またはそのファミリーとスタイル）が 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. セットアップを確認する

アイコンを 1 つ追加して、すべてが動作していることを確認します。

1. プロジェクト内で表示されるテンプレートまたはコンポーネントを探します。
2. 統合方法に合った構文を使い、シンプルなアイコン（例：fa-check または fa-font-awesome）を追加します。
3. アイコンが表示されることを確認するため、ページまたはアプリをプレビューするようユーザーに伝えます。
4. 問題が報告された場合は、llms.txt インデックスから関連するトラブルシューティングページを探し（troubleshoot を含む URL を確認）、取得した内容を参考に原因を調べます。

6. .font-awesome.md を作成する

プロジェクトのルートに .font-awesome.md を作成します。テンプレートと使用する形式については、add-icon スキルディレクトリ（plugins/icons/skills/add-icon/）にある font-awesome-md-format.md を読みます。セットアップ中に確認・設定した内容をすべて記入します。

ユーザーに次のように伝えます。「プロジェクトの Font Awesome 設定を記載した .font-awesome.md を作成しました。チームでも活用でき、/add-icon がすぐに使えるよう、このファイルをコミットしてください。」

7. 次のステップ

セットアップが完了したら、次にできることをユーザーに伝えます。

• アイコンを追加する: 「/add-icon <icon-name> を実行すると、任意の Font Awesome アイコンをコードに追加できます。」
• アイコンを探す: 「/suggest-icon <concept> を実行すると、用途に合ったアイコンを見つけられます。」
• ヘルプを得る: 「/fa-help <question> を実行すると、Font Awesome の公式ドキュメントに基づく回答を得られます。」