AI Skillを複数端末で再現可能に管理する

AIエージェントのSkillを試すだけなら、GitHubから1つをインストールして終わりです。端末やエージェントが増えた瞬間に、どのSkillを、どのコミットで、どこへ展開したかが問題になります。

そこで、Skill本体、インストーラー、プロジェクトのマニフェスト、解決結果のロックファイルを分けて考えた。この記事の結論は、試用と再現可能な依存管理を同じ運用にしないことです。

何を固定すべきか

対象	責務	端末が増えたときに確認すること
Skill	SKILL.mdと関連資産	原本の場所と公開範囲
インストーラー	エージェントの配置先へ展開	project / globalの範囲
マニフェスト	必要な依存関係の宣言	どのSkillを標準とするか
ロックファイル	コミット、ハッシュ、解決結果	同じ状態を再現できるか

インストール先の生成物を直接編集しても、別の端末へ意図は伝わらない。反対に、マニフェストだけでコミットや配置先が固定されていなければ、同じ見た目の構成を再現できません。

npx skillsは探して試す入口

Vercel LabsのSkills CLIは、Skillを探し、個人またはプロジェクトへ追加する入口として使えます。たとえば次のように導入します。

npx skills add vercel-labs/agent-skills \
  --skill frontend-design \
  --agent codex

まず挙動だけを確認するなら、skills useを使う方法もあります。

npx skills use vercel-labs/agent-skills \
  --skill frontend-design \
  --agent codex

--globalや対象エージェントの指定は、利用するCLIバージョンのヘルプを確認します。ここでの導入は候補を試す工程であり、チーム標準の依存管理と同じとは限りません。

gh skillはGitHub上の個別Skill向け

GitHub CLIのgh skill installは、GitHubリポジトリのSkillを対象エージェントへインストールする用途に向きます。

gh skill install github/awesome-copilot \
  documentation-writer \
  --agent codex \
  --scope project \
  --pin v1.2.0

--agent、--scope、--pinの意味と利用できる参照形式は、導入時のgh skill install --helpと公式マニュアルを正とします。1つのSkillを明示的に固定するには分かりやすいが、複数のSkill、MCP、エージェント設定を1つのプロジェクト依存関係として解決する仕組みではありません。

APMはプロジェクトの依存として扱う

APMは、Skillだけでなく、指示、prompt、agent、hook、plugin、MCPサーバーをパッケージとして管理するAgent Package Managerです。apm.ymlに依存関係を宣言し、apm.lock.yamlへ解決済みのコミットやハッシュを記録します。

project/
├── apm.yml
├── apm.lock.yaml
├── apm_modules/        # APMが生成する作業用ディレクトリ
└── .agents/            # エージェント向けの展開先

ロックファイルを使う端末やCIでは、まず記録済みの状態を展開します。

apm install --frozen --target codex

--frozenは、マニフェストとの不整合を検出し、更新を暗黙に解決しないための指定です。更新するときだけロックを再生成し、コミット、ハッシュ、展開先の差分をレビューします。

apm lock
git diff -- apm.lock.yaml

apm_modules/や展開された.agents/をGit管理するかは、APMと自作Skillの構成に依存します。自作Skillの原本を同じ場所へ置く場合は、生成物とソースを区別できるディレクトリ設計にします。

3つを導入段階で使い分ける

目的	まず使うもの	正本として残すもの
候補を一度試す	npx skills use	通常は何も固定しない
GitHubの1つのSkillを導入	gh skill install	pinした参照、またはプロジェクト設定
複数端末・CIで同じ構成を再現	APM	apm.ymlとapm.lock.yaml
Skill、MCP、promptを一緒に管理	APM	マニフェストとロックファイル
自作Skillをチーム共有	ソースリポジトリ、または選んだパッケージ管理	原本のGit履歴

同じSkillをnpx skillsとAPMの両方で管理すると、更新の入口が2つになります。チーム標準にするものは1つの原本と1つの更新経路へ寄せ、個人的な試用は別の場所に留めます。

CIで再現性を確認する

APMをプロジェクト依存として採用するなら、CIのクリーン環境でロックから展開できることを検証します。

apm install --frozen --target codex
apm audit --ci

auditのサブコマンドやオプションは、使用中のAPMで確認します。重要なのは生成先にファイルがあるかではなく、同じロックファイルから同じ入力を展開できることです。

更新の流れは、次のように固定するとレビューしやすいです。

1. apm.ymlへ依存関係を追加または変更します。
2. apm lockで解決結果を更新します。
3. apm.lock.yamlのコミットとハッシュを確認します。
4. apm install --frozenでクリーン環境へ展開します。
5. 監査とエージェントの最小動作確認を行います。
6. マニフェストとロックファイルを同じ変更としてレビューします。

結論の範囲

個人の短時間の試用ならnpx skills useで十分です。GitHub上のSkillを1つ固定するならgh skillが分かりやすいです。複数端末、CI、Skills以外のエージェント資産まで同じ状態にしたいなら、マニフェストとロックファイルを持つAPMが適しています。

ただし、APMがSkillの品質や安全性を保証するわけではありません。依存先の内容、更新差分、権限、生成されるファイルをレビューします。Skillをソフトウェア依存と同じように固定すると、導入、更新、監査、復元の責任範囲を見失いにくくなります。

参考資料

• Vercel Labs Skills CLI
• GitHub CLI: gh skill install
• microsoft/apm
• APM manifest and lockfile specification