はじめに：なぜAgent Skillsが必要なのか
Claude Codeを日常的に使っていると、「毎回同じ指示をプロンプトに書いている」という場面に心当たりがある方は多いのではないでしょうか。社内特有のコーディング規約、決まったレビュー観点、繰り返し使うデータベーススキーマの説明など、本来は一度教えれば十分なはずの知識を、会話のたびに繰り返し伝えている状態です。
この課題を解決するのが、Anthropicが提供する「Agent Skills（エージェントスキル）」という仕組みです。Claude Codeだけでなく、Claude API、claude.aiなど、Claudeを使う複数の製品で共通して使える機能で、Claudeにドメイン固有の知識やワークフローを永続的に「教える」ことができます。本記事では、公式ドキュメントの内容をもとに、Agent Skillsの仕組みと、実際にClaude Codeで使う際の作り方、そして「思ったように発火しない」「意図と違う挙動をする」といった典型的なつまずきへの対処法を整理します。
Agent Skills（Claude Code Skills）とは何か
プロンプトとの違い
Agent Skillsは、Claudeの機能を拡張する再利用可能なモジュールです。1回限りの会話の中で指示を書く「プロンプト」とは異なり、Skillはファイルシステム上のディレクトリとして保存され、必要なタイミングでClaudeが自動的に読み込んで使用します。一度作成しておけば、以降の会話で同じ指示を繰り返す必要がなくなる点が最大のメリットです。Anthropicは、あらかじめ用意された「PowerPoint」「Excel」「Word」「PDF」向けの標準Skillに加えて、ユーザー自身が独自のカスタムSkillを作成できる仕組みを提供しています。
3段階のプログレッシブ・ディスクロージャー構造
Agent Skillsの技術的な特徴は「プログレッシブ・ディスクロージャー（段階的開示）」と呼ばれる設計にあります。Skillの中身は3つのレベルに分かれており、必要な情報だけを段階的にコンテキストへ読み込むことで、無駄なトークン消費を防ぎます。
レベル1はメタデータで、SKILL.mdのYAMLフロントマター（nameとdescription）を指します。これは起動時に常にシステムプロンプトへ読み込まれますが、1つのSkillあたり約100トークン程度と非常に軽量です。レベル2は本文の指示内容で、該当のSkillがユーザーの要求に一致したと判断された時点で初めて読み込まれます。レベル3は、SKILL.mdから参照される追加ファイルやスクリプトで、実際に参照・実行されるまではコンテキストを一切消費しません。この仕組みにより、数十から百以上のSkillをインストールしていても、使われていないSkillはほぼコストゼロで存在できます。
Claude CodeでのSkillsの使い方
保存場所とディレクトリ構成
Claude CodeにおけるカスタムSkillはファイルシステムベースで管理され、API経由でのアップロードは不要です。個人用のSkillは~/.claude/skills/に、プロジェクト単位で共有したいSkillは.claude/skills/（リポジトリ内）に配置します。プロジェクト単位のSkillはバージョン管理下に置けるため、チームメンバー間で同じSkillを共有できるほか、Claude Code Pluginsを通じて配布することも可能です。
なお、Claude Codeでは事前構築済みのドキュメント系Skill（PowerPoint・Excel・Word・PDF）は利用できませんが、オープンソースで公開されている「Claude API skill」（8言語分のAPIリファレンスやSDKドキュメントを提供するSkill）が標準でバンドルされています。
SKILL.mdの必須項目
すべてのSkillは、YAMLフロントマターを持つSKILL.mdファイルを必要とします。必須フィールドはnameとdescriptionの2つです。nameは64文字以内で、小文字の英数字とハイフンのみが使用可能、「anthropic」「claude」といった予約語は使えません。descriptionは1,024文字以内で、空欄にはできず、Skillが「何をするか」と「いつ使うべきか」の両方を含める必要があります。このdescriptionこそが、Claudeが数百個のSkillの中から適切な1つを選び出すための唯一の手がかりとなるため、記述の質がSkillの実用性を大きく左右します。
効果的なSkillの作り方（公式ベストプラクティス）
簡潔さを最優先する
公式のベストプラクティスガイドが繰り返し強調しているのが「簡潔さ」です。コンテキストウィンドウはSkill専用のものではなく、システムプロンプトや会話履歴など他の情報と共有される「公共財」であるという考え方に基づき、Claudeがすでに知っている一般的な説明は省略し、本当に必要な手順やコード例だけを記載することが推奨されています。SKILL.mdの本文は500行未満に収め、それを超える場合は別ファイルに分割するのが目安とされています。
自由度（degrees of freedom）を適切に設定する
もうひとつの重要な考え方が「自由度の設計」です。複数のアプローチが有効でコンテキストに応じた判断が求められるタスクには、文章ベースの大まかな指示（高自由度）が適しています。一方、データベースのマイグレーションのように、手順を誤ると重大な問題につながる操作には、実行すべきコマンドを一字一句指定する低自由度の指示が適しているとされています。公式ドキュメントでは、これを「両側が崖の細い橋」と「障害物のない広場」に例えており、タスクの性質に応じて指示の厳密さを調整することの重要性を説明しています。
descriptionの書き方
descriptionは必ず三人称で記述することが推奨されています。「私が処理します」ではなく「Excelファイルを処理し、レポートを生成する」という客観的な書き方にすることで、Skillの発見精度が安定するためです。また、「ドキュメントを処理する」のような曖昧な説明ではなく、「PDFファイルからテキストと表を抽出し、フォームに入力し、文書を結合する。PDFファイルを扱う際、またはユーザーがPDF・フォーム・文書抽出について言及した際に使用する」のように、具体的なトリガー条件まで含めることが推奨されています。
よくある失敗と「発火しない」問題のトラブルシューティング
Skillを作成しても期待通りに動かないケースは少なくありません。公式ドキュメントが指摘する典型的な原因と対処法を整理します。
まず多いのが、descriptionが曖昧すぎて選択されないケースです。「ドキュメントを手伝う」「データを処理する」といった漠然とした説明では、Claudeが数あるSkillの中から適切なものを選び出せません。何を・いつ使うのかを具体的なキーワードとともに明記することが対処法になります。
次に、参照ファイルの階層が深すぎる問題があります。SKILL.mdからさらに別のファイルを参照し、そのファイルがまた別のファイルを参照する、という「入れ子の参照」が発生すると、Claudeがhead -100のような部分読み込みしか行わず、情報が欠落したまま処理が進んでしまうことがあります。対処法として、すべての参照ファイルはSKILL.mdから直接一階層でリンクする構成にすることが推奨されています。
また、Windows形式のパス表記（バックスラッシュ区切り）を使うと、Unix系環境で動作するSkill実行環境ではエラーの原因になります。ファイルパスは常にスラッシュ区切り（例：scripts/helper.py）で記述する必要があります。
最後に、100行を超えるような長い参照ファイルに目次がない場合、Claudeが部分的にしかファイルを読み込まず、必要な情報を見落とすことがあります。長いリファレンスファイルの冒頭には目次を設けることで、Claudeが全体像を把握しやすくなります。
セキュリティ上の注意点
Agent Skillsは、指示とコードを通じてClaudeに新しい能力を与える仕組みであるため、信頼できる作成者（自分自身、またはAnthropic）のSkillのみを使用することが強く推奨されています。悪意のあるSkillは、本来の目的とは異なる形でツールやbashコマンドを実行させたり、外部URLからの不審な指示を読み込ませたりする可能性があります。特に外部サービスからデータを取得するタイプのSkillはリスクが高いとされ、SKILL.md本体だけでなく、同梱されたスクリプトや画像ファイルまで含めて、不審なネットワーク呼び出しや目的外の処理がないかを事前に確認することが推奨されています。
まとめ
Agent Skillsは、Claudeに繰り返し同じ指示を与える手間を省き、ドメイン固有の知識を「一度作れば使い回せる」形に変える仕組みです。Claude Codeでは~/.claude/skills/または.claude/skills/にディレクトリを置くだけで手軽に始められる一方、実際に安定して機能させるには、descriptionの書き方や参照ファイルの階層構造など、公式ドキュメントが示すいくつかの設計原則を押さえておく必要があります。特に「発火しない」「意図通りに動かない」といったトラブルの多くは、descriptionの曖昧さや参照構造の深さに起因するため、本記事で紹介したチェックポイントを踏まえてSkillを設計・見直しすることをおすすめします。
