「毎回同じ指示をClaude Codeに伝えるのが面倒」「プロジェクト固有のルールを自動で反映させたい」――こうした課題を解決する仕組みが Agent Skills（エージェントスキル） です。
Anthropicが2025年10月16日に発表し、同年12月18日にオープンスタンダードとして仕様を公開したこの機能は、Claude Codeだけでなく OpenAI Codex CLI・Cursor・VS Code・GitHub Copilot・Gemini CLI をはじめ27以上のAIコーディングツールで採用が広がっています（出典: agentskills.io）。GitHubリポジトリ anthropics/skills は65,000を超えるスターを獲得しており、開発者コミュニティの関心の高さがうかがえます。
Agent Skillsの定義と基本構造
Agent Skillsは、指示・スクリプト・リソースをフォルダ単位でまとめた「再利用可能な専門知識パッケージ」です。Claudeは会話の文脈に応じて必要なSkillだけを動的に読み込み、タスクに適した振る舞いに切り替わります。
1つのSkillは以下のようなディレクトリ構成を取ります。
my-skill/
├── SKILL.md # エントリポイント（必須）
├── template.md # Claudeが埋めるテンプレート
├── examples/
│ └── sample.md # 期待される出力例
└── scripts/
└── validate.sh # Claudeが実行するスクリプト
SKILL.md がエントリポイントです。このファイルにYAMLフロントマターとMarkdown形式の指示を記述します。その他のファイルはオプションで、テンプレート・出力例・実行スクリプト・リファレンスドキュメントなどを必要に応じて配置します。
プログレッシブディスクロージャーによるコンテキスト管理
Agent Skillsは3段階のローディングシステムを採用しており、コンテキストウィンドウを効率的に利用します。
| 読み込み段階 | 対象データ | タイミング |
|---|---|---|
| レベル1: メタデータ | name + description（約100語） | 常時コンテキストに存在 |
| レベル2: SKILL.md本文 | 指示・手順（約5,000語目安） | Skillが発動した時点で読み込み |
| レベル3: 付属リソース | スクリプト・リファレンス等 | Claudeが必要と判断した時のみ |
この段階的読み込みにより、多数のSkillを登録していても、使われないSkillの本文がコンテキストを圧迫する心配がありません。descriptionのみが常時読み込まれ、Claudeはそこから「今のタスクにどのSkillが関連するか」を判断します。
Skillの配置場所とスコープ
Skillの配置場所によって有効範囲が異なります。優先度は Enterprise > Personal > Project の順です。
| スコープ | パス | 適用範囲 |
|---|---|---|
| Enterprise（組織全体） | Managed Settingsで配布 | 組織の全プロジェクト |
| Personal（個人用） | ~/.claude/skills/<skill-name>/SKILL.md | 自分の全プロジェクト |
| Project（プロジェクト固有） | .claude/skills/<skill-name>/SKILL.md | そのプロジェクトのみ |
| Plugin（プラグイン経由） | <plugin>/skills/<skill-name>/SKILL.md | プラグインを有効にした場所 |
モノレポ対応: サブディレクトリに .claude/skills/ を配置すると、そのディレクトリ内のファイル編集時に自動検出されます。たとえば packages/frontend/.claude/skills/ に配置したSkillは、packages/frontend/ 内の作業中のみ有効です。
Plugin Skills: plugin-name:skill-name という名前空間を使うため、他のスコープのSkillとの名前衝突が起こりません。
SKILL.md フロントマター全フィールド一覧
SKILL.md のYAMLフロントマターで設定できるフィールドの一覧です。すべてオプションですが、description の記述が推奨されています。なお、オープンスタンダード仕様（agentskills.io）で定義されているフィールドは name・description・license・compatibility・metadata・allowed-tools の6つです。以下の表にはClaude Code固有の拡張フィールドも含まれています。
| フィールド | 推奨度 | 説明 |
|---|---|---|
name | 任意 | 表示名。省略時はディレクトリ名を使用。小文字英数字とハイフンのみ（最大64文字） |
description | 推奨 | Skillの用途と発動条件。Claudeがいつ使うか判断するための最重要フィールド |
argument-hint | 任意 | 補完時に表示される引数のヒント（例: [issue-number]） |
disable-model-invocation | 任意 | true にするとClaudeの自動呼び出しを抑止。手動の /name のみ |
user-invocable | 任意 | false にすると / メニューから非表示。背景知識用Skillに使用 |
allowed-tools | 任意 | Skill実行中にClaude が許可なく使えるツールを指定 |
model | 任意 | Skill実行中に使用するモデルを指定 |
context | 任意 | fork を指定するとサブエージェントとして独立実行 |
agent | 任意 | context: fork 時に使うサブエージェント種別（Explore, Plan, general-purpose等） |
hooks | 任意 | Skillライフサイクルに紐づくHooksを設定 |
動的な値の埋め込み（文字列置換）
Skillの本文中で以下のプレースホルダを使えます。
| 変数 | 用途 |
|---|---|
$ARGUMENTS | /skill-name に続けて入力された引数の全体 |
$ARGUMENTS[N] / $N | N番目の引数（0始まり）。$0 は最初の引数 |
${CLAUDE_SESSION_ID} | セッションID。ログ出力やファイル名に利用可能 |
CLAUDE.md・MCP・Subagentsとの機能比較
Claude Code にはSkills以外にもカスタマイズ手段が存在します。それぞれの役割が異なるため、目的に応じた使い分けが重要です。
| 比較項目 | CLAUDE.md | Agent Skills | MCP Server | Subagents |
|---|---|---|---|---|
| 主な目的 | プロジェクト全体の指針 | 特定タスクの専門知識 | 外部ツール・API連携 | タスクの並列委任 |
| 読み込みタイミング | 常時 | 必要に応じて動的 | 常時接続 | 親エージェントが起動 |
| コンテキスト消費 | 大きい（全文常時読み込み） | 小さい（段階的読み込み） | API定義分のみ | 独立コンテキスト |
| 再利用性 | プロジェクト単位 | 跨プロジェクト共有可能 | サーバー単位 | 定義単位 |
| 使い分けの指針 | コーディング規約・ビルド手順 | デプロイ手順・レビュー基準 | DB操作・Slack通知 | 大規模調査・検証 |
使い分けのポイント: 常に参照すべきルール（命名規則やコーディングスタイル等）は CLAUDE.md に、特定の作業フロー（デプロイ・コードレビュー・ドキュメント生成等）はSkillsに配置します。Skillsのメリットは「使うときだけコンテキストを消費する」ことにあり、大量のルールをCLAUDE.mdに詰め込むとコンテキストが逼迫する問題を回避できます。
実用Skillテンプレート3選
テンプレート1: コードレビューSkill
---
name: code-review
description: コードレビューを実施する。PRの差分を読み、品質・セキュリティ・可読性の観点でフィードバックを出力する。
allowed-tools: Read, Grep, Glob, Bash(gh pr diff *)
disable-model-invocation: true
---
# コードレビュー
指定されたPR（$ARGUMENTS）をレビューしてください。
## 観点
1. **ロジックの正しさ**: エッジケースの考慮漏れがないか
2. **セキュリティ**: SQLインジェクション・XSS・機密情報の露出がないか
3. **可読性**: 変数名・関数名が意図を表しているか
4. **テストカバレッジ**: 変更箇所に対応するテストが存在するか
## 出力フォーマット
- 問題の深刻度を `[Critical]` `[Warning]` `[Info]` で分類
- 各指摘にファイルパスと行番号を記載
- 改善案を具体的なコード例で提示
テンプレート2: デプロイSkill（サブエージェント実行）
---
name: deploy-staging
description: ステージング環境へのデプロイを実行する。テスト → ビルド → プッシュの3段階で進行。
context: fork
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *), Bash(docker *)
---
# ステージングデプロイ
$ARGUMENTS をステージング環境にデプロイしてください。
## 手順
1. `npm run test` でテストスイートを実行
2. テスト通過を確認後、`npm run build` でビルド
3. `docker build -t app:staging .` でコンテナイメージを作成
4. `docker push registry.example.com/app:staging`
5. デプロイ完了のサマリを出力
## 中断条件
- テスト失敗時は即座に中断し、失敗内容を報告
- ビルドエラー時も中断し、エラーログを表示
テンプレート3: PRサマリ生成Skill（動的コンテキスト注入）
---
name: pr-summary
description: PRの変更内容を要約する。差分・コメント・変更ファイル一覧を取得して分析。
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
## PR情報
- 差分: !`gh pr diff`
- コメント: !`gh pr view --comments`
- 変更ファイル: !`gh pr diff --name-only`
## タスク
上記の情報をもとに、以下の構成でPRを要約してください。
1. **変更の概要**（1〜2文）
2. **主な変更点**（箇条書き）
3. **影響範囲**
4. **レビュー時の注目ポイント**
!command`` 構文により、Skill実行時にシェルコマンドの出力結果が自動で差し込まれます。Claudeはコマンドの実行結果だけを受け取り、それを元に分析を行います。
Skill の呼び出し制御と権限設定
Skillの呼び出し元と発動タイミングを制御する方法は複数あります。
| フロントマター設定 | ユーザーが呼び出し可能 | Claudeが自動呼び出し可能 | コンテキスト上の扱い |
|---|---|---|---|
| デフォルト（設定なし） | はい | はい | descriptionが常時読み込み、本文は発動時 |
disable-model-invocation: true | はい | いいえ | descriptionもコンテキスト外 |
user-invocable: false | いいえ | はい | descriptionが常時読み込み、本文は発動時 |
副作用のある操作（デプロイ・メッセージ送信・データ削除等）には disable-model-invocation: true を設定し、手動の /skill-name でのみ実行する運用が安全です。
Skill単位でのツール制限も可能です。allowed-tools に Read, Grep, Glob のみを指定すれば、そのSkill実行中はファイルの読み取りだけが許可される読み取り専用モードになります。
skill-creator を使った作成手順
Anthropicが公式に提供している skill-creator を使うと、対話形式でSkillを構築できます。
手順1: 公式プラグインをインストール
# Anthropic公式マーケットプレイスを追加
/plugin marketplace add anthropics/claude-code
# マーケットプレイスからskill-creatorを含むプラグインをインストール
/plugin install skills@anthropics-claude-code
インストール後、Claude Codeを再起動して skill-creator が / メニューに表示されれば準備完了です。
手順2: Skillを作成
/skill-creator 新しいスキルを作りたい。APIレスポンスのフォーマットを標準化するSkillが欲しい。
skill-creatorがヒアリングを行い、要件に合った SKILL.md とディレクトリ構造を自動生成します。Opusモデル（/model opus）に切り替えてから実行すると、生成精度が向上します。
手順3: 既存の会話からSkill化
Claude Codeとの作業中に「このやり取りをSkillにしたい」と感じた場合、skill-creatorに依頼できます。
/skill-creator 今の会話の手順をSkill化して
直前の会話コンテキストから手順を抽出し、再利用可能なSkillとして定義してくれます。
descriptionの書き方が成否を分ける
Skillが適切に発動するかどうかは、description の記述に大きく依存します。Claudeは description を読んで「今のタスクに関連するか」を判断するため、曖昧な記述だとSkillが発動しない、あるいは意図しないタイミングで発動する問題が起きます。
効果的な description の条件:
- 何をするか と いつ使うか の両方を含める
- ユーザーが自然に使う言葉をキーワードとして含める
- 30〜80語程度で簡潔にまとめる
改善の具体例:
# 発動しにくい例
description: コードのフォーマット
# 発動しやすい例
description: Pythonファイルのコードフォーマットを実行する。black と isort を使い、PEP 8準拠のスタイルに整形。新しいPythonファイルを作成した後や、フォーマットの乱れを指摘された場合に使用。
トラブルシューティング早見表
| 現象 | 原因 | 対処法 |
|---|---|---|
| Skillが発動しない | descriptionにタスクと関連するキーワードが不足 | descriptionを見直し、ユーザーが使いそうな語句を追加 |
| Skillが発動しない | Skill自体が認識されていない | What skills are available? と質問して一覧を確認 |
| Skillが頻繁に誤発動する | descriptionが広すぎる | より限定的な表現に変更、または disable-model-invocation: true を設定 |
| 一部のSkillが読み込まれない | Skill数がコンテキスト予算を超過 | /context コマンドで警告を確認。環境変数 SLASH_COMMAND_TOOL_CHAR_BUDGET で上限を調整 |
| Skillの変更が反映されない | --add-dir 以外の方法で追加したSkillはホットリロード対象外 | Claude Codeを再起動 |
セキュリティ上の留意点
- allowed-tools の最小権限: Skillに必要最低限のツールだけを許可する。特にBashコマンドは
Bash(npm test)のようにパターンを絞る - サードパーティSkillの確認: マーケットプレイスからインストールする前に、SKILL.md の内容とスクリプトの処理を確認する
- 機密情報の除外: SKILL.md やスクリプトにAPIキー・パスワードなどの機密情報を直接記載しない。環境変数を経由する設計にする
- 副作用の制御: データの変更や外部通信を伴うSkillには
disable-model-invocation: trueを設定し、意図しない自動実行を防ぐ
Skillの共有・配布方法
作成したSkillは複数の方法で配布できます。
| 配布方法 | 手順 | 適したケース |
|---|---|---|
| Gitリポジトリに含める | .claude/skills/ をバージョン管理に追加 | チーム内の標準化 |
| Plugin として公開 | プラグインの skills/ ディレクトリに配置 | オープンソースでの共有 |
| Managed Settings | 組織のManaged Settings経由で配布 | エンタープライズ全体への展開 |
| サードパーティディレクトリ | skills.sh（Vercel運営）や skillsmp.com（コミュニティ運営）に掲載 | 広いコミュニティへの公開 |
SKILL.md 作成時のベストプラクティス
- 1つのSkillに1つの責務: 複数の機能を詰め込まず、焦点を絞る。複雑な処理は複数のSkillに分割する
- SKILL.md は500行以内に収める: 長い参照ドキュメントは
reference.mdなどの別ファイルに分離し、SKILL.md からリンクする - 具体例を含める: 期待される入出力の例を記載すると、Claudeの動作精度が向上する
- 制限事項を明記する: Skillが対応しないケースや前提条件を書いておくと、誤用を防げる
- 反復的に改善する: 実際に使いながら description やフロントマターを調整する。一度で完璧なSkillは作れない
まとめ
Agent Skillsは、Claude Codeでの繰り返し作業をパッケージ化し、チームや個人の開発効率を引き上げる仕組みです。SKILL.md の description を適切に書くことが発動精度に直結し、プログレッシブディスクロージャーによりコンテキストの無駄遣いも防止されます。
オープンスタンダードとして公開されたことで、Claude Code以外のツール（Codex CLI・Cursor・VS Code GitHub Copilot等）でも同じSKILL.md形式が利用可能です。一度作成したSkillを複数のツールで横断的に活用できる点が、従来のツール固有の設定ファイルとの大きな違いです。
公式リポジトリ anthropics/skills には実用的なサンプルSkillが多数収録されています。まずはskill-creatorで自分のワークフローに合ったSkillを1つ作るところから始めると、Skillsの効果を実感しやすいです。