🧰 技術調査 - vercel-labs/skills

Vercel Labs が公開する OSS の AI エージェントスキル管理 CLI（npm パッケージ名: skills、リポジトリ: vercel-labs/skills）の構造・データモデル・運用パターンをまとめた技術調査ドキュメントです。2026-05 時点の v1.5.x 系列を対象とします。

読み方のガイド

• 急ぎでコマンドを知りたい → 「利用方法」の主要オプション一覧と add の典型例
• アーキテクチャを把握したい → 「構造」の C4 図と「データ」の概念モデル
• チーム導入を検討する → 「運用」と「ベストプラクティス」
• うまく動かないとき → 「トラブルシューティング」の症状別表

概要

skills は、Vercel Labs が公開するオープンソースの AI エージェントスキル管理 CLI です。リポジトリは vercel-labs/skills、公式レジストリは skills.sh です。

「一度書いたスキルを、対応するすべてのエージェントで再利用する」という設計思想で、断片化した AI エージェントエコシステムに統一された配布・管理レイヤーを提供します。

npx skills add <source> の 1 コマンドで、GitHub・GitLab・ローカル・well-known エンドポイント上のスキルパッケージを取得し、Claude Code・Cursor・GitHub Copilot など 50 を超えるエージェントの所定ディレクトリへ symlink または copy で配置します。

特徴

オープン標準（Agent Skills）

SKILL.md フォーマットは Anthropic が起点となって agentskills.io でオープン標準として整備されています。Vercel Labs、Microsoft、Google、OpenAI、JetBrains、Block など主要ベンダーが採用しています。

多数のエージェントに対応

src/types.ts の AgentType 定義では universal を含めて 54 種類（v1.5.x 系列）に対応します。主要カテゴリは次のとおりです。

symlink と copy の使い分け

インストール方式は symlink と copy の 2 種類です。複数エージェントが別々のディレクトリ（例: Claude Code の .claude/skills/ と Cursor の .agents/skills/）に解決する場合、対話プロンプトで方式を選びます。symlink を選ぶと正規コピー（.agents/skills/<name>/）への参照になり、npx skills update 一発で全エージェント分が最新版に追従します。

選択したエージェントが全部同じディレクトリに解決する場合（claude-code のみ、または universal 系のみ等）は、PR #582 以降プロンプトがスキップされ、自動的に copy で配置されます。--copy フラグで明示的に copy を指定することもできます。

プログレッシブディスクロージャ

SKILL.md の YAML frontmatter（name + description）のみが起動時に読まれ、エージェントが関連性を判断したときだけ本体・scripts/・references/ がロードされます。常時注入の AGENTS.md / CLAUDE.md と異なり、コンテキストウィンドウを節約します。

skills.sh によるエコシステム

skills.sh がスキル検索 API・blob ダウンロードキャッシュ・リーダーボードを提供します。npx skills find のインタラクティブ検索 UI もこのレジストリを参照します。

エージェント別コンテキスト設定形式の比較

配布・インストール方式の比較

アーキテクチャの技術的な違い

ChatGPT custom GPTs / OpenAI Assistants との比較

ユースケース別推奨

構造

システムコンテキスト図

コンテナ図

コンポーネント図

add コマンド 内部

インストーラー 内部

エージェントアダプタ群 内部

プロバイダレジストリ 内部

リモートフェッチ経路

データ

概念モデル

情報モデル

スコープと ParsedSource.type

スキルは 2 つのスコープで管理されます。

ParsedSource.type ごとの fetch 挙動は次のとおりです。

well-known エンドポイントが返す index.json の例を示します。

{
  "skills": [
    {
      "name": "company-conventions",
      "description": "Use this skill for all code in this repository to enforce team conventions.",
      "files": [
        "/skills/company-conventions/SKILL.md",
        "/skills/company-conventions/references/style-guide.md"
      ]
    }
  ]
}

構築方法

前提条件

• Node.js 18 以上が必要（package.json の engines で "node": ">=18"）
• npm / npx が使用できる環境であれば追加のセットアップは不要

node --version
# v18.x.x 以上であること

インストール方法

npx で都度実行（推奨）

常に最新バージョンを使用できます。ローカルへのインストールは不要です。

npx skills <command>

npm でグローバル永続インストール

npm install -g skills
skills --version

プロジェクトローカルインストール

npm install --save-dev skills

初期化（新規スキルの雛形生成）

npx skills init でカレントディレクトリまたは指定サブディレクトリに SKILL.md テンプレートを生成します。

npx skills init
npx skills init my-skill

生成される SKILL.md の基本構造は次のとおりです。

---
name: my-skill
description: What this skill does and when to use it
---

# My Skill

Instructions for the agent to follow when this skill is activated.

利用方法

主要オプション一覧

npx skills add で使用できる主要オプションの早見表です。

npx skills add <source>

スキルをインストールするメインコマンドです。

ソース形式

npx skills add vercel-labs/agent-skills
npx skills add https://github.com/vercel-labs/agent-skills
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
npx skills add https://gitlab.com/org/repo
npx skills add git@github.com:vercel-labs/agent-skills.git
npx skills add ./my-local-skills

スキル名・エージェント名の指定

npx skills add vercel-labs/agent-skills --skill frontend-design
npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
npx skills add owner/repo --skill "Convex Best Practices"
npx skills add vercel-labs/agent-skills --skill '*'

npx skills add vercel-labs/agent-skills --agent claude-code
npx skills add vercel-labs/agent-skills -a claude-code -a opencode
npx skills add vercel-labs/agent-skills --agent '*'

スコープと非対話・全選択

npx skills add vercel-labs/agent-skills --global
npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y
npx skills add vercel-labs/agent-skills --all

スキル一覧表示と --copy

npx skills add vercel-labs/agent-skills --list
INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list

npx skills add vercel-labs/agent-skills --copy

インストール方式の違いは次のとおりです。

npx skills list / ls

npx skills list
npx skills ls -g
npx skills ls --agent claude-code --agent cursor
npx skills ls --json

JSON 出力スキーマは次のとおりです。

[
  {
    "name": "frontend-design",
    "path": "/Users/dev/.agents/skills/frontend-design",
    "scope": "global",
    "agents": ["Claude Code", "Cursor", "OpenCode"]
  }
]

npx skills remove / rm

npx skills remove
npx skills remove web-design-guidelines
npx skills remove frontend-design web-design-guidelines
npx skills remove --global web-design-guidelines
npx skills remove --agent claude-code cursor my-skill
npx skills remove --all
npx skills remove --skill '*' -a cursor
npx skills remove my-skill --agent '*'
npx skills rm my-skill

npx skills find

スキルをインタラクティブに検索・発見します（fzf スタイル UI）。

npx skills find
npx skills find typescript

npx skills check（注意）

cli.ts 上で check は update / upgrade と同じ runUpdate() ハンドラに振られているため、確認のつもりで叩くと更新が走ります（issue #954）。確認だけ行いたい場合は npx skills list --json などで現状を確認し、明示的に update を呼んでください。

npx skills experimental_sync

node_modules/ 配下を再帰的にクロールして SKILL.md を発見し、エージェント別ディレクトリへ同期する実験的コマンドです。スキルを npm パッケージとして配布する運用や、モノレポでスキルを開発する運用で使えます。ロックファイルからの同期ではない点に注意してください。

npx skills experimental_sync

experimental_install との違いは次のとおりです。

npx skills experimental_install

skills-lock.json から登録済みスキルを一括復元する実験的コマンドです。CI/CD や新メンバーオンボーディングで利用します。

npx skills experimental_install

引数・オプションの最新仕様は CLI ヘルプ（npx skills experimental_install --help）で確認してください。

npx skills update

npx skills update
npx skills update my-skill
npx skills update frontend-design web-design-guidelines
npx skills update -g
npx skills update -p
npx skills update -y

エージェント別インストール先パス早見表

主要エージェントのインストールパス（v1.5.x 系列、2026-05 時点）は次のとおりです。

注意点

• 上の表は agents.ts の globalSkillsDir 設定値です。installer.ts の getAgentBaseDir() は universal 系エージェント（.agents/skills を共有するもの）を先に判定し、global 指定時でも canonical な ~/.agents/skills/ に解決します。Cursor / Codex / OpenCode / GitHub Copilot / Gemini CLI / Cline / Amp などは表の global 値が使われる前に universal 経路に乗るケースがある点に注意してください
• ~/.config/... のパスは $XDG_CONFIG_HOME が設定されていれば $XDG_CONFIG_HOME/... になります（OpenCode / Goose / Amp / Devin など）
• v1.5.x 系列の AgentType 定義では universal を含めて 54 種類のエージェントに対応しています

環境変数

INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list

運用

スキルのバージョン更新

npx skills update でインストール済みスキルを最新バージョンに更新します。-g でグローバル、-p でプロジェクト、-y でスコープ自動検出ができます。

複数エージェントへの一括配布

npx skills add vercel-labs/agent-skills -a claude-code -a cursor -a codex
npx skills add vercel-labs/agent-skills --agent '*' --skill frontend-design
npx skills add vercel-labs/agent-skills --all

symlink vs copy 運用

注意点として、-a claude-code のように単一エージェントだけを指定した場合や、universal 系エージェント（.agents/skills/ 共有）だけを選んだ場合は、ターゲットディレクトリが 1 つに収束するため symlink/copy プロンプトはスキップされ、自動的に copy で配置されます（Issue #519 / PR #582）。symlink で運用したい場合は、複数ディレクトリに解決するエージェントを -a で組み合わせるか、-a を省略して universal 経由で配置します。

ディレクトリ構造は次のとおりです。

• 正規コピー: ~/.agents/skills/<skill-name>/ または .agents/skills/<skill-name>/
• エージェント用 symlink: ~/.claude/skills/<skill-name> → 正規コピー

global と project の使い分け

判断基準は次のとおりです。

• プロジェクト固有（チームの PR 規約・特定外部ツール連携）はプロジェクトスコープでリポジトリに含める
• 汎用（コードレビュー、ドキュメント生成）はグローバルスコープで個人環境に導入

CI/CD への組み込み

npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y
npx skills experimental_install

ポイントは次のとおりです。

• skills-lock.json をリポジトリにコミットしてバージョンを固定（package.json と package-lock.json の関係に相当）
• npx skills@latest で npx キャッシュ問題を回避
• テレメトリは CI 環境で自動的に無効化（手動で DISABLE_TELEMETRY=1 も設定可）
• 開発依存に追加して CI とローカルでバージョンを揃える: npm install --save-dev skills

新メンバーオンボーディング時の一括 install

npx skills experimental_install
npx skills add vercel-labs/agent-skills --all -y
npx skills add vercel-labs/agent-skills -y

エージェントが検出できない場合は対話プロンプトで選択を促します。

ベストプラクティス

チーム共有のスコープ選択

プロジェクトスコープでリポジトリ内に含める運用を推奨します。

• チーム全員が同一スキルセットを使用できる
• .claude/skills/ などをリポジトリに含めてバージョン管理する
• CI/CD での再現性が確保される
• skills-lock.json でバージョン固定できる

npx skills add vercel-labs/agent-skills --skill team-conventions

グローバルスコープは個人の好みや汎用ツール、横断的に使うスキルに向きます。

npx skills add vercel-labs/agent-skills --skill code-review -g

プログレッシブディスクロージャ思想

スキルは段階的開示の原則で設計します。

1. メタデータ（YAML frontmatter）はルーティング判断のために最初に読まれる。短い description で発火条件を示す
2. 本体の指示はスキル起動後に詳細手順を提供する
3. リソース（scripts/, references/）は必要な場合のみロードする

「ほぼすべてのタスクに適用するルールは AGENTS.md、特定のワークフローはスキル」が分離の指針です。

SKILL.md の命名規約と完全記述例

• name: 小文字のケバブケース
• description: 「いつ使うか」を具体的に記述。発火する具体シナリオを書く
• tools: スキルが利用するツール（参照値）
• allowed-tools: 実行を許可するツール（権限制御。対応エージェントのみ）

---
name: generate-release-notes
description: Use this skill when the user asks to generate release notes, create a changelog, or summarize git history for a release.
tools:
  - bash
  - read_file
allowed-tools:
  - bash
  - read_file
---

# Generate Release Notes

## Steps

1. `git log --oneline <prev-tag>..HEAD` でコミットを収集する
2. `references/release-template.md` を出力テンプレートとして読み込む
3. `scripts/categorize.sh` でコミットを自動分類する

スキルパッケージのディレクトリ構造例

複数スキルをまとめたチーム共有リポジトリのレイアウトです。

my-team-skills/
├── README.md
├── skills/
│   ├── release-notes/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   │   └── categorize.sh
│   │   └── references/
│   │       └── release-template.md
│   └── code-review/
│       └── SKILL.md
└── .claude-plugin/
    └── plugin.json

• scripts/: スキル実行時にエージェントが起動するスクリプト（シェル / Python など）
• references/: 詳細指示・テンプレート・ナレッジを置く Markdown 等。プログレッシブディスクロージャで必要時のみロード
• .claude-plugin/plugin.json または marketplace.json: 複数スキルを 1 プラグインとしてまとめる場合のマニフェスト

ローカル開発から公開までの導線

# 1. 雛形生成
npx skills init my-skill

# 2. ローカルテスト（手元のディレクトリから直接インストール）
npx skills add ./my-skill -a claude-code

# 3. GitHub リポジトリへ push（SKILL.md をルートまたは skills/ 配下に配置）
git push origin main

# 4. 他者からのインストール
npx skills add owner/my-skill

skills.sh への掲載条件（自動クロール / 申請の要否）は公式ドキュメントに明記がないため、登録手順は skills.sh 側の最新情報を確認してください。

セキュリティ

不特定の GitHub リポジトリからスキルを追加する際の注意点を示します。

• スキルをコードと同様に扱い、インストール前に内容をレビューする
• scripts/ ディレクトリが含まれる場合は特に注意する
• 既知のリポジトリにピン留めし、更新時は差分をレビューする

npx skills add vercel-labs/agent-skills
npx skills add owner/repo --list

CLI 自体の安全機能は次のとおりです。

• パストラバーサル防止: sanitizeName がパス安全性を確認
• ロックファイル整合性: skillFolderHash（GitHub tree SHA）でインテグリティを検証
• 認証: GITHUB_TOKEN または GH_TOKEN でレート制限緩和とプライベートリポジトリ対応

allowed-tools / 権限設定

SKILL.md の allowed-tools で使用ツールを最小化できます（対応エージェントのみ）。これらの frontmatter キーは skills CLI 自体は内容を検証せず、各エージェントの仕様に従って解釈されます。

---
name: read-only-analysis
description: Use this skill to analyze code without making changes
allowed-tools:
  - read_file
  - list_files
  - search_files
---

非対応エージェント（Kiro CLI、Zencoder 等）にも配布する場合は、本体の指示文でツール制約を明記します。

トラブルシューティング

エージェントがスキルを認識しない場合の確認手順

1. インストール済みスキルとパスを確認する

npx skills list
npx skills ls -g
npx skills ls --json

2. エージェントごとの正しいインストールパスを確認する（前述「エージェント別インストール先パス早見表」）

3. SKILL.md のフロントマターが有効な YAML であることを確認する。name と description は必須。インデントは 2 スペース。特殊文字はクォートで囲む

4. 正しいエージェントを明示して再インストールする

npx skills add <repo> -a claude-code

まとめ

npx skills は、SKILL.md フォーマットを共通言語にして 50+ の AI エージェントへスキルを横断配布する CLI で、複数ディレクトリ向けの symlink 配置とプログレッシブディスクロージャによりコンテキスト効率を高めます（単一ディレクトリ時は PR #582 以降 copy が既定）。本記事では C4 model 3 段階の構造図、ロックファイルや SkillLockFile を含む情報モデル、エージェント別パス早見表、運用・セキュリティ・既知の不具合まで網羅しています。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNS でのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント
  • skills.sh（公式レジストリ）
  • Vercel docs: Agent Skills
  • Vercel KB: Creating, Installing and Sharing Agent Skills
  • Vercel changelog: Introducing skills
  • Vercel changelog: skills v1.1.1
  • agentskills.io（仕様）
  • Anthropic Agent Skills 公式仕様
• GitHub
  • vercel-labs/skills
  • GitHub releases: vercel-labs/skills
  • vercel-labs/agent-skills（公式スキル群）
  • skills（npm）
  • src/cli.ts
  • src/add.ts
  • src/installer.ts
  • src/agents.ts
  • src/git.ts
  • src/blob.ts
  • src/providers/index.ts
  • src/providers/wellknown.ts
  • src/constants.ts
  • src/types.ts
  • src/skill-lock.ts
  • src/local-lock.ts
  • src/skills.ts
  • src/plugin-manifest.ts
  • src/source-parser.ts
  • src/frontmatter.ts
  • skills/find-skills/SKILL.md（実例）
  • #1045: Claude Code needs skills installed to .claude
  • #1049: Stuck on Cloning repository
  • #999: well-known source truncated in skills-lock.json
  • #985: /.well-known/agent-skills/index.json not fetched
  • #974: -g combined with -a override symlinking
  • #954: skills check reinstalls instead of reporting
  • #916: Update command creates skills folder at project root
  • #886: Local install from .agent/skills/ deletes source SKILL.md
  • #1028: The API requires authentication
  • #1025: Add a repair/relink command
  • #519: Skip symlink/copy prompt when only universal path is selected
  • PR #582: Skip symlink/copy prompt when all agents share one directory
• 記事
  • dev.to: Managing AI Agent Skills with npx skills
  • The Unwind AI: Vercel Releases the npm of Agent Skills
  • Builder.io: Agent Skills, Rules, Commands
  • deepwiki.com/vercel-labs/skills