npx skills — AIエージェント用パッケージマネージャーの使い方と落とし穴
背景
Claude Code、Cursor、GitHub Copilotといった AI エージェントは、プロジェクト固有のツール（Playwright、独自CLIなど）を最初から知っているわけではない。それを教え込む仕組みが npx skills だ。Vercel Labs が提供するAIエージェント向けスキル管理CLIで、npmのような感覚でエージェントの「能力」を管理できる。
npx skills add microsoft/playwright-cli
このコマンドを実行すると、GitHubから SKILL.md を取得してエージェント設定ディレクトリ（.agents/skills/ や .claude/skills/）に配置する。これ以降、対象エージェントは Playwright の使い方を「知っている」状態になる。
仕組み
レジストリは GitHub
npm が npmjs.com を使うのに対し、skills は GitHub がレジストリ。microsoft/playwright-cli という指定は https://github.com/microsoft/playwright-cli に対応する。
公開リポジトリのルートに SKILL.md さえあれば、それが有効なスキルになる。
SKILL.md の役割
npm における index.js に相当するのが SKILL.md。以下を含む：
- メタデータ — スキルの名前・説明
-
ツール定義 — AIが実行できるコマンド（例：
playwright test） - プロンプト指示 — そのツールをいつ・どう使うかのAIへの指示書
npm との対応関係
| 概念 | npm | skills CLI |
|---|---|---|
| 依存関係の定義 | package.json |
.skills.json |
| ロックファイル | package-lock.json |
skills-lock.json |
| 実体の保存先 | node_modules/ |
.agents/skills/ |
| レジストリ | npmjs.com | GitHub |
| 復元コマンド | npm ci |
npx skills experimental_install |
npx skills add 実行後、.skills.json はこうなる：
{
"skills": [
{
"name": "playwright-cli",
"remote": "microsoft/playwright-cli",
"version": "latest"
}
]
}
主なコマンド
# スキルを追加
npx skills add vercel-labs/agent-skills
# グローバル（ユーザーレベル）に追加
npx skills add vercel-labs/agent-skills -g
# 特定エージェント向けにインストール
npx skills add vercel-labs/agent-skills --agent claude-code cursor
# インストール済みスキルの一覧
npx skills list
npx skills ls -g # グローバルスキル
npx skills ls -a cursor # エージェントで絞り込み
# スキルを検索
npx skills find typescript
# 全スキルを最新版に更新
npx skills update
# ロックファイルから復元（npm ci 相当）
npx skills experimental_install
# node_modules からエージェントディレクトリへ同期
npx skills experimental_sync
# 新規スキルの雛形を作成
npx skills init my-skill
注意点
remove してもロックファイルは更新されない
最大の落とし穴がこれ：
npx skills rm microsoft/playwright-cli --all
エージェントディレクトリからはファイルが消えるが、skills-lock.json にエントリが残る。次に experimental_install を実行すると復活する。
完全削除の手順：
-
npx skills removeでエージェントディレクトリから削除 -
.skills.jsonを手動で編集して該当エントリを削除 -
skills-lock.jsonを削除 -
npx skills updateなどを実行してクリーンなロックファイルを再生成
npm 初期の頃のような「手動管理の泥臭さ」が残っている部分だ。
experimental_ は本当に試験的
現状のバージョンでは：
-
npx skills sync→ 存在しない - ロックファイルからの復元 →
npx skills experimental_install - node_modules からの同期 →
npx skills experimental_sync
ヘルプを見ると "Restore skills from skills-lock.json" と明記されているが、コマンド名が直感的でないので注意。
npx のキャッシュ問題
npx skills は古いキャッシュを使う場合がある。常に最新版を使うには：
npx skills@latest add <repo>
プロジェクト全員が同じバージョンを使うなら devDependencies に追加する方が確実：
npm install --save-dev skills
CI/CD での運用
GitHub Actions 等でスキルを復元するステップを追加する：
- name: Restore AI agent skills
run: npx skills experimental_install
skills-lock.json をコミットしておけば、全開発者・CI環境で同一バージョンのスキルを使える。
自作スキルの公開
SKILL.md を置いた GitHub リポジトリは、そのままスキルとして配布できる。
npx skills init my-skill # 雛形生成
# → SKILL.md を編集してGitHubにpush
公開後は誰でも：
npx skills add yourusername/my-skill
でインストール可能。スキルの探し方は skills.sh を参照。
まとめ
npx skills は「AIエージェント向けのnpm」だ。メンタルモデルはほぼ同じ：
-
SKILL.md=index.js -
.skills.json=package.json -
skills-lock.json=package-lock.json -
experimental_install=npm ci
ロックファイル管理（特に remove との不整合）はまだ荒削りだが、チーム開発でAIの挙動を揃えるユースケースには十分使える。