Agent Skills完全ガイド：AI Agentに専門知識を教える方法

「同じ手順を毎回プロンプトへ貼り付けている」「Skillを追加したのに意図しない場面で発動する」という症状が出ている場合、知識をシステムプロンプトへ増やすのではなく、用途ごとにAgent Skillsへ分割するのが最短の改善策です。

今週の推奨アクションは、1つの頻出作業を選び、SKILL.mdに発動条件と実行手順だけを定義し、動的な情報は知識ソース、外部操作は権限管理されたツールへ分離することです。 Agent Skillは、発動条件、操作指示、必要に応じたスクリプトや参考資料をまとめた再利用可能な能力パッケージです。

主な対象は、初めてSKILL.mdを作る開発者、チーム標準の手順をClaude Codeで再利用したい開発者、社内Skillリポジトリの安全管理を担当する技術責任者です。単発の質問に回答させたいだけなら、通常のPromptのほうが適しています。

最終更新：2026年8月17日。仕様フィールド、公式テンプレート、Claude Codeの検出方法は、Agent Skillsの公式仕様、Claude Code公式ドキュメント、Anthropic公式Skillsリポジトリを基準に確認しています。

まず「知識を置く場所」を分けます

専門知識をシステムプロンプトへ長期間追加し続ける方法には、少なくとも3つの問題があります。

1つ目は、すべての作業で同じ説明が読み込まれ、関係のないタスクにもコンテキストを消費することです。2つ目は、手順の更新箇所がシステムプロンプト、プロジェクト設定、個人メモへ分散し、どれが最新版か分からなくなることです。3つ目は、似た作業向けの指示が増えるほど、AI Agentがどの手順を選ぶべきか判断しにくくなることです。

Agent Skillsは、この問題を「用途単位の独立した能力」に分解します。Claude CodeではSkillの概要が利用可能な道具として扱われ、必要な作業で本体を読み込む仕組みが採用されています。公式ドキュメントでも、繰り返し貼り付けている指示や複数段階の手順をSkillへ移す用途が案内されています。詳しくはClaude CodeにおけるSkillの読み込みと配置を確認できます。

ただし、Skillは知識ベースそのものではありません。社内の最新料金、現在のAPI仕様、在庫、障害状況のように更新頻度が高い事実は、更新可能な知識ソースや外部検索へ置くべきです。Skillには「どの情報を確認し、どの条件で判断するか」を書き、最新値そのものを固定しない設計が安全です。

最小構成からSkillを組み立てます

Agent Skillsの基本単位は、フォルダーとその中のSKILL.mdです。公式仕様では、scripts/、references/、assets/は任意の補助ディレクトリとして定義されています。Agent Skills仕様のディレクトリ定義では、それぞれの役割とフロントマターの扱いが整理されています。

要素	役割	初期段階で入れる内容
`name`	Skillの識別名	小文字、数字、ハイフンによる短い名前
`description`	何をするか、いつ使うか	対象作業と具体的な発動条件
`SKILL.md`本文	AI Agentが従う手順	前提、実行順、確認項目、失敗時の処理
`references/`	必要時に読む資料	詳細仕様、社内規約、判断表
`scripts/`	実行可能な処理	検証、変換、生成、定型コマンド
`assets/`	固定素材	テンプレート、画像、スキーマ、サンプル

仕様上、nameは64文字以内、descriptionは1024文字以内で、descriptionには処理内容と使用タイミングの両方を記述します。compatibilityは環境要件がある場合に使える任意フィールドで、最大500文字です。これらは一般的な推奨値ではなく、公式仕様に記載された制約です。

最初から大量の参考資料を入れる必要はありません。最小Skillでは、次のような構成から始めます。

code-review/
├── SKILL.md
├── references/
│   └── review-policy.md
└── scripts/
    └── collect-diff.sh

SKILL.mdには、対象作業、開始条件、実行手順、出力形式、例外処理を記載します。詳細な規約を本文へ詰め込むと、Skillが発動しただけで長い情報を読み込むため、個別資料はreferences/へ分けます。公式仕様でも、本文は500行未満を目安とし、詳細資料を別ファイルへ移すプログレッシブ・ディスクロージャーが推奨されています。

`SKILL.md`は何を書けばよいか

SKILL.mdの中心は、AI Agentが迷わず再現できる作業フローです。次の順番で記述すると、単なる知識メモではなく実行可能な手順になります。

対象範囲：何を処理し、何を処理しないかを明記します。
発動条件：ユーザーの依頼、対象ファイル、作業目的を具体化します。
事前確認：入力ファイル、ブランチ、権限、依存コマンドを確認させます。
実行手順：順番を固定し、分岐条件を明示します。
検証方法：成功と判断する基準を、出力ファイルやテスト結果で定義します。
失敗時の処理：停止、確認依頼、ロールバックの条件を書きます。

Agent SkillsとPromptの違いは、保存場所や文字数だけではありません。Promptはその会話のための一時的な指示になりやすい一方、Skillはファイルとしてバージョン管理し、必要な作業で再利用し、スクリプトや参考資料まで同じ単位で管理できます。したがって、単発の文体指定はPrompt、何度も使うレビュー手順やリリース手順はSkillという分け方が実務的です。

発動説明は「能力」ではなく「条件」で書きます

「開発を支援する」「専門的な分析を行う」といった説明は、対象範囲が広すぎます。似たSkillが複数ある環境では、発動の重複や誤選択を招きます。

例えば、次のように書き換えます。

---
name: api-review
description: REST APIの変更差分を確認し、互換性、認証、エラー形式、テスト不足を報告します。OpenAPI定義やAPIルートの変更をレビューするときに使用します。
---

この説明には「何をするか」と「いつ使うか」が含まれています。Anthropic公式のSkill作成ガイドでも、descriptionはSkillを呼び出すかどうかを決める主要な仕組みと説明され、発動する依頼と発動しない依頼を用意した評価が推奨されています。公式Skill作成ガイドも参照できます。

実装後は、少なくとも正例と反例を用意します。

正例：OpenAPIの変更差分をレビューする
正例：認証方式を変更したAPIの互換性を確認する
反例：一般的なPythonコードの整形を行う
反例：UIの色や文言だけを修正する
隣接Skillとの境界：データベースmigrationとAPI契約変更をどちらが担当するか決める

Claude Codeでは、Skillを自動発動させるだけでなく、/skill-nameの形式で明示的に呼び出すこともできます。自動判定の精度が重要な作業では、説明文の評価と手動呼び出しの両方を用意すると、誤発動と見逃しを切り分けやすくなります。

スクリプト、権限、MCPを分担させます

Agent Skillはスクリプトを含められます。公式仕様では、scripts/に実行可能なコードを置き、依存関係、エラー表示、境界条件を明確にすることが求められています。したがって「Agent Skillはスクリプトを呼び出せるか」という疑問への答えは、仕様上は可能ですが、実際に実行できる範囲はクライアントの実装、ツール設定、承認ポリシーに依存するです。

ここでSkillとMCPを混同してはいけません。Skillは、どのような手順で判断・作業するかを定義する指示パッケージです。MCPは、外部サービスやデータソースへ接続するためのツールやリソースを提供する仕組みです。MCPの公式仕様でも、Toolはサーバーが公開し、クライアント側が呼び出しを制御する構成になっています。MCPのTool概念に関する公式説明で、接続と呼び出しの境界を確認できます。

役割分担は次のように整理できます。

Skill：レビュー基準、作業順、出力形式、確認条件
知識ソース：最新の仕様、社内規約、顧客情報、更新される事実
MCP：Issue管理、データベース、監視、クラウドサービスとの接続
スクリプト：決められた変換、検証、集計、ファイル生成
通常のPrompt：今回だけの条件や一時的な依頼

Skillを書いたからといって、独立した実行権限が発生するわけではありません。削除、外部送信、認証情報の利用、クラウド環境の変更などは、専用ツール、承認、監査ログ、最小権限の仕組みで制御する必要があります。特に汎用的なシェル実行だけへ依存すると、操作の意図や対象範囲を検査しにくくなります。

第三者Skillを導入する前に確認します

第三者Skillは、SKILL.mdだけを読んで安全と判断できません。実行ファイル、依存パッケージ、ネットワークアクセス、ファイル書き込み、ライセンスが別のリスクになります。

導入前には、次のチェックを実行します。

[ ] 配布元のリポジトリ、更新履歴、責任者を確認した
[ ] SKILL.mdのnameとdescriptionが実際の用途に一致している
[ ] scripts/内のコマンドを1行ずつ確認した
[ ] 外部通信先、APIキー、環境変数の読み取りを確認した
[ ] 作成・変更・削除するファイルの範囲を限定した
[ ] ライセンスと再配布条件を確認した
[ ] 隔離した開発環境で正例と反例を試した
[ ] 失敗時に処理を停止し、確認を求める設計になっている
[ ] 本番の認証情報を持たない状態で最初の検証を行った
[ ] 導入版と検証結果を記録した

allowed-toolsは事前承認するツールを記述できる任意フィールドですが、公式仕様では実験的な扱いで、対応状況はAgent実装によって異なります。これを記述しただけで、すべての環境で安全なサンドボックスになるとは考えないほうがよいでしょう。

Claude Codeの公式ドキュメントでは、Skillの配置場所によって個人用、プロジェクト用、プラグイン用などの適用範囲が変わり、同名Skillの優先順位も定義されています。チームで共有する場合は、個人フォルダーへ直接置くのではなく、レビュー可能なリポジトリと導入手順を用意するほうが管理しやすくなります。Claude CodeのSkill配置と優先順位も導入前に確認してください。

1つのSkillをチームの能力庫へ育てます

Skillの数を増やすこと自体は成果ではありません。優先すべきなのは、頻繁に発生し、手順が安定しており、結果を検証できる作業です。例えば、リリース前チェック、APIレビュー、ログ調査、ドキュメント生成のように、入力と合格条件を定義しやすい処理から始めます。

チーム運用では、各Skillに次の管理情報を持たせます。

所有者とレビュー担当者
対応するAgentとバージョン
正例、反例、境界ケース
変更理由と変更日
依存するスクリプトやMCP
廃止条件と移行先

Skillを更新したときは、説明文だけで発動するか、本文手順まで読み込んで期待した出力になるか、スクリプトが許可された環境でのみ動くかを分けて確認します。公式のskills-ref validateは、フロントマターや命名規則の検証に使えますが、実務上の品質、発動精度、権限の妥当性まで自動保証するものではありません。公式仕様の検証方法を基準にしつつ、実際のタスクでも受け入れ試験を行う必要があります。

Claude Code用のSkillをクラウド開発環境へ導入する場合は、プロジェクトごとのファイル配置、シェル権限、依存コマンドの有無も確認してください。ローカル環境とリモート環境の差分が残っていると、同じSkillでも結果が変わるためです。導入後の環境確認や運用上の問い合わせ先を整理する場合は、ヘルプセンターの案内も参照できます。

最初の1週間で行う実装手順

頻出する作業を1つ選び、成功条件を文章化します。
skill-name/SKILL.mdを作り、nameとdescriptionを先に確定します。
本文へ前提条件、作業順、出力形式、停止条件を記載します。
変換や検証が必要になった段階で、依存関係を明記したスクリプトを追加します。
長い規約や資料をreferences/へ移し、本文から相対パスで参照します。
正例、反例、隣接Skillとの境界を使って発動テストを行います。
隔離環境でファイル書き込みと外部通信を確認します。
所有者、版、変更履歴、廃止条件をリポジトリへ記録します。

この順番なら、最初から大規模なSkill基盤を作らず、実際の失敗から必要な参考資料やスクリプトだけを追加できます。

現在の方法が長いシステムプロンプトや個人PCへ依存している場合、知識が重複し、環境差分が見えにくく、スクリプトの実行権限も管理しづらいという欠点があります。短期間の検証や一時的な開発環境が必要なら、Macを手元で購入して固定化するより、VuncloudのMacレンタルで隔離した開発環境を用意するほうが、導入前のSkill検証と破棄を分けやすい場面があります。長期の常時稼働や物理機器への接続が必要なケースでは自前環境が適しますが、Claude Codeの遠隔開発や一時的なAgent Skills検証なら、Macレンタルの利用環境を候補に入れる価値があります。

Skillの導入後に権限とファイル操作をさらに分離したい場合は、第三者Skillを本番データへ接続する前に隔離環境で受け入れ試験を行うのが安全です。最初に作るべきなのは大量のSkillではなく、発動条件、実行範囲、検証結果を説明できる1つのSkillです。