Anthropic がついに公式の Agent Skills チュートリアル動画を公開しました。全 6 レッスン、合計 22 分の内容で、Skills とは何か、作成方法、マルチファイル設定、他の機能との違い、共有方法、トラブルシューティングまで、Skills のライフサイクル全体をカバーしています。
このチュートリアルの最大の価値は、単に Skill の書き方を教えるだけでなく、Skills の設計思想とその背後にあるメカニズムを解説している点にあります。多くの人が Skills を使う際に直面する問題は、これらのメカニズムへの理解不足に起因しています。
Skills はどのような問題を解決するのか？
チームのコーディング規約を Claude に説明するたびに、あなたは同じことを繰り返しています。PR レビューのたびに、フィードバックをどのように整理してほしいかを再説明しなければなりません。コミットメッセージのたびに、好みのフォーマットを Claude に思い出させる必要があります。
Skills は、このような繰り返しを排除するために設計されました。Skill とは、Claude に何かを一度教えるための Markdown ファイルであり、Claude は関連する状況でその知識を自動的に適用します。
より正確には、Agent Skill とは、指示、スクリプト、リソースを含むフォルダです。Claude はこれらを自動的に発見し、活用することで、より正確かつ効率的に作業を完了できます。
中核となるメカニズムは description フィールドです。Claude が起動すると、すべての Skill の名前と説明を読み込みます。あなたがリクエストを行うと、Claude はリクエストと利用可能なすべての Skill の説明を意味的にマッチングし、該当する Skill を見つけて有効化します。有効化された時点で初めて、Skill の全内容がコンテキストウィンドウに読み込まれます。
これは claude.md とは根本的に異なります。claude.md の内容は、何をしているかに関わらず、すべての会話に読み込まれます。Skill は必要な時だけ読み込まれます。つまり、デバッグ中に PR レビューのチェックリストがコンテキストにある必要はなく、実際にレビューを依頼した時だけ表示されます。
では、いつ Skill を使うべきでしょうか？もし Claude に同じことを繰り返し説明している自分に気づいたなら、それは Skill を開発すべき時です。
最初の Skill をゼロから作成する
Skill の作成に必要なのは、ディレクトリを作成し、ファイルを書くことだけです。
ステップ 1: ~/.claude/skills/ の下に、Skill の名前を付けたディレクトリを作成します。ここに配置すると、個人レベルの Skill となり、すべてのプロジェクトで利用可能になります。
ステップ 2: そのディレクトリ内に SKILL.md ファイルを作成します。ファイルは 3 つのダッシュで区切られた 2 つの部分に分かれています。上部は name と description を含む YAML メタデータです。下部には、Claude が従うべき具体的な指示が含まれます。
Claude Code が起動すると、エンタープライズパス、個人の Skills ディレクトリ、プロジェクトの Skills ディレクトリ、インストールされたプラグインの 4 つの場所をスキャンします。各 Skill の名前と説明のみを読み込み、全内容は読み込みません。
リクエストを送信すると、Claude はリクエストとすべての Skill の説明を比較します。意図が一致した場合、まず Skill を読み込むかどうかの確認を求めます。確認後、初めてファイル全体を読み込み、指示を実行します。この確認ステップにより、Claude がどのようなコンテキストを使用しているかを常に把握できます。
同じ名前の Skill が存在する場合、優先順位は高い順に、エンタープライズレベル (managed-settings.json)、個人レベル (~/.claude/skills)、プロジェクトレベル (project/.claude/skills)、プラグインレベル (project/.claude-plugins/skills) となります。
つまり、企業はエンタープライズレベルの Skill を通じて標準を強制しつつ、個人は異なる名前の Skill を使用してカスタマイズできます。会社にエンタープライズコードレビュー用の Skill がある場合、個人で front-end-pr-review という名前の Skill を作成して上書きではなく補完することができます。
高度な設定: メタデータフィールドとプログレッシブディスクロージャー
基本的な Skill には name と description のみ必要ですが、いくつかの高度な設定により、Skill をより強力にすることができます。
allowed-tools フィールドは、Skill がアクティブなときに Claude が使用できるツールを制限できます。例えば、読み取り専用の分析 Skill がある場合、編集、書き込み、Bash コマンドを禁止できます。このフィールドを省略すると、Skill は制限を課さず、Claude は通常の権限モデルを使用します。
model フィールドは、使用する Claude モデルのバージョンを指定できます。
description の書き方は、Skill が正しくトリガーされるかどうかを直接決定します。優れた説明は、次の 2 つの質問に答える必要があります。この Skill は何をするのか？Claude はいつこれを使うべきか？Skill がトリガーされない場合は、リクエストの表現と一致するキーワードを追加してください。
最も重要な高度な概念は、プログレッシブディスクロージャー（段階的開示）です。Skills は会話とコンテキストウィンドウを共有します。すべてを 20,000 行の SKILL.md に詰め込むと、膨大なコンテキストスペースを消費します。
正しいアプローチは、必須の指示を SKILL.md に置き、詳細な参考資料は別のファイルに分け、Claude が必要な時だけそれらを読み込むようにすることです。推奨されるディレクトリ構造は、実行可能コード用の scripts フォルダ、参考文書用の references フォルダ、画像やテンプレートなどのデータファイル用の resources フォルダです。SKILL.md 内のリンクを使用してこれらのファイルを参照します。
重要なルール: SKILL.md は 500 行を超えてはいけません。超える場合は分割する必要があります。スクリプトは、その内容をコンテキストに読み込まずに直接実行できます。トークンを消費するのは出力のみです。そのため、Claude にはスクリプトを読ませるのではなく、実行するように指示してください。これは、環境検証やデータ変換に特に有用であり、テスト済みのスクリプトコードはその場で生成するコードよりも信頼性が高くなります。
Skills と他の Claude Code 機能の違い
Skills vs. claude.md: claude.md は常にすべての会話に読み込まれ、常に適用されるプロジェクトの標準やルール（例：「このプロジェクトは TypeScript の strict モードを使用します」）に使用されます。Skills はオンデマンドで読み込まれ、Claude がリクエストにマッチした場合にのみ有効化されます。
Skills vs. Sub Agents: Skills は現在の会話に知識を追加します。有効化されると、指示が既存のコンテキストに追加されます。Sub Agents は独立したコンテキストで実行され、タスクを完了して結果を個別に提出し、メインの会話から完全に分離されます。
Skills vs. Hooks: Hooks はイベント駆動型で、特定のイベント（例：ファイルが保存されるたびに Claude が Linter を実行するなど）が発生したときにトリガーされます。Skills はリクエスト駆動型で、あなたが尋ねる質問に基づいて有効化されます。
Skills vs. MCP: MCP は外部ツール接続を提供し、Claude が Gmail や Notion などのサービスを呼び出せるようにします。Skills は知識とワークフローを提供し、Claude にそれらのツールを使って特定のタスクを完了する方法を指示します。
一文でまとめると、claude.md は常時オンの指示、Skills は自動マッチングされる専門知識、Sub Agents は分離されたコンテキストで委任されたタスクを実行、Hooks はイベントに応答、MCP は外部ツールに接続します。これらは組み合わせて使用できます。
Skills の共有: 個人からチーム、組織へ
Skills の価値は共有にあります。自分だけが使う PR レビュー用 Skill も役立ちますが、チームで共有する Skill はコードレビューを標準化し、一貫したエクスペリエンスを提供できます。
共有方法は 3 つあります。
1 つ目はプロジェクトディレクトリです。コードリポジトリの .claude/skills ディレクトリに Skill をコミットします。リポジトリをクローンした人は誰でも、追加のインストールなしでこれらの Skill を自動的に取得できます。更新は次のプルで受け取れます。これは、チームのコーディング標準やプロジェクト固有のワークフローに適しています。
2 つ目はプラグインです。プラグインは、プロジェクト間で Skills を配布する方法と考えてください。アプリストアにアップロードすると、他のユーザーがダウンロードしてインストールできます。あなたの Skill が汎用的でプロジェクト固有でない場合、これはコミュニティメンバーにとって最良の選択肢です。
3 つ目はエンタープライズデプロイメントです。管理者は管理設定を通じて、組織全体に Skills をプッシュします。エンタープライズレベルの Skill は最も高い優先順位を持ち、同じ名前の個人用やプロジェクト用の Skill を上書きします。これは、必須の標準、セキュリティ要件、コンプライアンスワークフローに使用されます。
重要な注意点: Sub Agents は自動的にあなたの Skills を継承しません。タスクをサブエージェントに委任すると、新しいコンテキストで開始されます。組み込みエージェント（Explorer、Plan、Verify）は Skills にまったくアクセスできません。あなたが定義したカスタム Sub Agents のみが使用でき、それらは agent.md に明示的にリストする必要があります。
Skills を使用するカスタム Sub Agent を作成するには、.claude/agents ディレクトリに agent.md ファイルを作成し、必要な Skill 名をリストした skills フィールドを追加します。サブエージェントの目標に常に関連する Skill のみをリストしてください。これらの Skill はサブエージェントの起動時に読み込まれます。
トラブルシューティングガイド: Skills が失敗する 6 つの理由とその解決策
Skill の問題は通常、6 つのカテゴリに分類されます。
- Skill がトリガーされない: 理由はほとんどの場合、
descriptionの書き方が不適切であることです。Claude は意味的マッチングを使用します。あなたのリクエストが説明の意味と一致する必要があります。十分な重なりがないと、マッチしません。解決策: 説明とリクエストの表現を比較し、ユーザーが実際に言うトリガーフレーズ（「分析を手伝って」「なぜこれが遅いのか」「高速化して」など）を追加します。
- Skill の読み込みに失敗する: パスとファイル名を確認してください。
SKILL.mdは、名前付きディレクトリ内に配置する必要があり、skills ルートに直接置くことはできません。ファイル名は大文字で正確にSKILL.mdでなければなりません。claude --debugを実行して読み込みエラーを確認します。
- Claude が間違った Skill を使用する: これは、説明が似すぎている複数の Skill があり、Claude がそれらを区別できないことを意味します。解決策: 各説明を可能な限り具体的にして、Claude がいつどれを使用すべきかを判断できるようにします。
- 個人用 Skill が無視される: 同じ名前の優先順位の高い Skill（エンタープライズ用など）が上書きしている可能性があります。4 つの優先順位レベルを確認してください。解決策: Skill の名前をよりユニークなものに変更します。
- プラグインはインストールされているが Skill が表示されない:
rm ~/.claude/plugins/cacheでキャッシュをクリアし、Claude Code を再起動して再インストールします。それでも動作しない場合、プラグインのディレクトリ構造が間違っている可能性があります。検証ツールskills-ref validateを使用して確認してください。
- Skill は読み込まれたが実行中に失敗する: Skill が外部パッケージを使用している場合、それらがインストールされていることを確認してください。依存関係情報を Skill の説明に追加します。
Anthropic は、Skill のファイル構造と YAML 構文が正しいかどうかを確認するための skills-ref という検証ツールも提供しています。最も高速な方法として、uv を使用してインストールすることをお勧めします。
