エージェントと Skills

Vantage に同梱された Claude Code の Agent Skills。vantage add skill でアプリに配置し（既定はルート直下、--dir で .claude/skills などに変更）、エージェントに手順を伴うワークフローを教える。

Vantage は Claude Code の Agent Skills を同梱しています。Skill は「手順を伴うワークフロー」を、 エージェントが必要なときだけ呼び出せる形にしたものです。UI キットや CLI の使い方といった 静的な参照(このドキュメント)とは別に、再現可能な段取りをエージェントに渡すのが目的です。

何が同梱されているか

いずれも「Vantage アプリを作るエージェント」向けの手順です。

配置する

Skill のソースは @squadbase/vantage パッケージに同梱されています。vantage add skill で 対象アプリにコピーします。配置先は既定でプロジェクトルート直下で、--dir で変えられます。

vantage add skill                             # 一覧と配置場所を表示するだけ(何も書かない)
vantage add skill --all                       # 未配置のものを、ルート直下に配置
vantage add skill vantage-app                 # 名前を指定して1つだけ配置
vantage add skill --all --dir .claude/skills  # Claude Code が読む場所に配置
vantage add skill --all --force               # 配置済みのコピーをその場で最新に更新

配置先は決め打ちではなく、走査して見つけます。 add skill はまずプロジェクト内 (node_modules などを除く)を走査し、既に配置されている skill はスキップして場所を報告 します。ルート直下でも .claude/skills/ でも .squadbase/skills/ でも同じで、再実行しても 二重に配置されません。名前を省いて実行すると、一覧と配置場所だけが出ます:

$ vantage add skill
Bundled skills:
  project-storage      .claude/skills/project-storage/
  vantage-add-feature  .claude/skills/vantage-add-feature/
  vantage-app          .claude/skills/vantage-app/
  vantage-pitfalls     not placed

--force を付けると、見つかった場所をそのまま新しい内容で書き換えます(--dir を明示した ときは、そちらが配置先として優先されます)。

--dir のパスはプロジェクトルートからの相対で解決されます（絶対パスも可）。Claude Code に 自動認識させるなら .claude/skills/ に置きます:

your-app/
├── index.tsx
├── package.json
└── .claude/
    └── skills/
        ├── vantage-app/SKILL.md
        ├── vantage-add-feature/SKILL.md
        ├── vantage-pitfalls/SKILL.md
        └── project-storage/SKILL.md

.claude/skills/ は Claude Code が自動で認識します。エージェントはタスクに応じて、対応する Skill の手順を読み込んで実行します。他のエージェントに読ませる場合は、そのツールが期待する ディレクトリを --dir に渡してください。

配布と更新の方針

• source-of-truth はパッケージ内にあります。Skill はフレームワークのバージョンと一緒に 配布・更新されるため、@squadbase/vantage を上げれば最新の手順が手に入ります。配置済みの コピーを更新したいときは vantage add skill --all --force を実行します(置き場所は走査して 見つけるので、--dir を覚えておく必要はありません)。
• Squadbase テンプレートには配置済みです。テンプレートから作ったアプリには、最初から .claude/skills/ が入っています。手で作ったアプリには vantage add skill で足してください。

AGENTS.md(アプリの地図)

Skill が「手順書」なら、AGENTS.md は**エージェントが最初に読む「地図」**です。Vantage の 不変条件・import サブパスの地図・ルーティング規約・データ取得/API/env の最小レシピを 1 ページに まとめてあり、それだけ読んで最小アプリを組めることを狙っています。手順の深掘りは上の Skill へ 名前で誘導し、内容は重複させません。

Skill と同じく source-of-truth はパッケージ内にあり、vantage add agents でアプリルートへ 配置します。

vantage add agents           # AGENTS.md をアプリルートに配置
vantage add agents --force    # 既存を上書き

配置済みの AGENTS.md は vantage upgrade で正本と同期されます(差分があるときだけ書き換え、 まだ配置していないアプリには作りません)。フレームワークの規約が変わっても、正本 1 箇所の更新が upgrade でアプリへ反映されます。Squadbase テンプレートには最初から配置済みです。

責務の切り分け

Skill は「手順を伴うワークフロー」だけを担います。次のものとは役割を分け、内容を重複させません。

• このドキュメント(仕様・リファレンス)― 何がどう動くかの静的な説明。ブラウザを開けない エージェントには、同じ内容が vantage docs でそのまま読めます (vantage docs button で props の表、vantage docs --json で機械可読。名前が 分からなければ vantage search <やりたいこと>)。
• AGENTS.md(静的な地図)― 構成やファイルの居場所。vantage add agents で配置します。
• Skill 同士 ― 落とし穴などの共通内容は各 Skill に写経せず、名前で相互参照します (例: vantage-app の手順中から vantage-pitfalls を指す)。