マルチエージェントAgent SDK でスキルを使う｜読み込みと絞り込み
この記事の要点
- Agent SDK のスキルは、フォルダに置いた SKILL.md のファイル。コードから登録する方法は無く、決まった場所から自動で読み込まれる
- skills オプションで、AI が自分から使ってよいスキルを名前で絞れる。ただし /名前 で直接呼ぶのは絞り込みに関係なく動く
- 読み込まれない時は、設定の読み込み元・作業フォルダ・説明文の3つを確かめる
活用例：社内の決まった確認作業（チェックリストに沿った点検）を AI に任せる
- 部署
- 情報システム・品質管理
- 使うもの
- Claude Agent SDK
- AIに任せる
- チェックリストに沿った点検と結果のまとめ
- 人が決める
- チェックリストの中身・どのスキルを使わせるか
AI エージェントに社内の仕事を任せると、「毎回同じ手順を説明している」「この作業はいつも同じ順番で確かめてほしい」 という場面が増えてきます。その手順を1つのファイルにまとめて、必要な時だけ AI に読ませる仕組みが スキル（Skills） です。
この記事では、公式ドキュメント「Extend agents with skills」（2026年11月11日確認）にもとづいて、Claude Agent SDK でスキルを使う方法を整理します。SDK の全体像は Claude Agent SDK とは、スキルそのものの書き方は Claude Codeのスキルとは で解説しています。
結論：スキルは「決まった場所に置くファイル」で、SDK が自動で見つける
Agent SDK のスキルは、フォルダに置いた SKILL.md というファイルです。 コードの中で登録する方法はありません。SDK は起動した時に決まった場所を探し、スキルの名前と説明だけを先に読みます。中身の全文を読むのは、AI がそのスキルを使うと決めた時だけです。
サブエージェントはコードの中で定義できますが、スキルはファイルとして置く という点が大きな違いです。
スキルが読み込まれる場所
既定の設定では、次の場所にあるスキルが見つかります。
| 置き場所 | 使える範囲 |
|---|---|
| 作業フォルダの .claude/skills/ | そのプロジェクトだけ |
| 作業フォルダより上（リポジトリの一番上まで）の .claude/skills/ | そのリポジトリの中 |
| 自分のホームの .claude/skills/ | 自分のすべてのプロジェクト |
1つのスキルは、1つのフォルダに SKILL.md を1つ 置く形です。ファイルの先頭に名前と説明（description）を書き、その下に手順を書きます。AI がいつ使うかは、説明文で決まります。 説明が具体的で、仕事の言葉が入っているほど、正しい場面で使われやすくなります。
以前からある .claude/commands/ の中のファイルも、そのまま動きます。公式ドキュメントでは、スキルがその後継とされています。
AI に使わせるスキルを絞る
skills オプションで、AI が自分の判断で使ってよいスキルを決められます。
| 指定 | 動き |
|---|---|
| 指定しない | 見つかったスキルはすべて使える（ふだんの Claude Code と同じ） |
| "all" | 見つかったスキルをすべて使える |
| 名前の一覧 | 一覧にあるスキルだけ使える |
| 空の一覧 | どのスキルも使わない |
名前の一覧には、正確な名前だけ を書きます。「全部」の意味で記号のワイルドカードを書くとエラーになり、作業が始まる前に止まります。全部を許すときは "all" を使います。
一覧に無いスキルは AI からは見えなくなり、使おうとしても断られます。ただし、ファイル自体はディスクに残っているので、ファイルを読む道具からは読めてしまいます。 中身を見せたくない手順は、そもそもその作業フォルダに置かないのが確実です。
/名前 で直接呼ぶこともできる
AI に判断させず、頼む文に「/スキルの名前」と書けば、そのスキルを直接動かせます。 これは skills の絞り込みとは関係なく動きます。
- 名前がどのコマンドにも当たらない時は、エラーにならず、ふつうの依頼として AI に届く
- 会話の要約（/compact）や、会話のリセット（/clear）も同じ書き方で送れる
- 画面の色の設定など、対話の画面が要るコマンドは使えない
使えるコマンドの一覧は、会話の始まりに届く最初のメッセージ（init）に入っています。作業を始める前に、ここに自分のスキルの名前があるかを確かめる と、読み込み漏れにすぐ気づけます。
スキルに必要な道具を先に許可しておく
スキルは、その会話で使える道具を使って動きます。ファイルを読む・探すといった道具を、あらかじめ許可の一覧（allowedTools）に入れておくと、スキルの途中で確認待ちになって止まることが減ります。 スキルのファイルの先頭に、許可する道具を書いておく方法もあります。許可の考え方は Agent SDK の権限設定 で解説しています。
読み込まれない時の確かめ方
- 設定の読み込み元：設定の読み込み元（settingSources）を自分で指定していて、ユーザーとプロジェクトを外していると、スキルは読み込まれない
- 作業フォルダ：作業フォルダ（cwd）が、.claude/skills/ のあるフォルダかその下を指しているか
- ファイルの場所：.claude/skills/ の下に、フォルダごとに SKILL.md があるか
- 絞り込みの一覧：skills の一覧に、そのスキルの名前が入っているか
- 説明文：AI が使いどころを判断できるくらい、具体的に書かれているか
仕事での使いどころ
- 決まった点検：チェックリストに沿った確認を、毎回同じ順番で進めてほしい時
- 文書の型：報告書や議事録など、書き方が決まっている文書を作る時
- 担当ごとの切り替え：同じエージェントでも、部署ごとに使わせるスキルを skills で分ける
よくある質問
スキルとサブエージェントは、どう使い分けますか？
手順を覚えさせたいならスキル、作業を別の担当に分けたいならサブエージェント が目安です。スキルはファイルとして置き、必要な時に中身が読まれます。サブエージェントはコードの中でも定義でき、別の会話として作業します。サブエージェントは Agent SDK のサブエージェント で解説しています。
skills を絞れば、ほかのスキルの中身は守られますか？
守られません。 絞り込みは「AI が自分から使うかどうか」を決めるもので、ファイルを読む道具からは読めます。また、頼む文に /名前 と書けば一覧に無いスキルも動きます。見せたくない手順は、作業フォルダに置かないようにします。
まとめ
- Agent SDK のスキルは 決まった場所に置く SKILL.md。コードから登録はしない
- skills オプション で AI が使うスキルを絞れるが、/名前 での直接の呼び出しは別
- 読み込まれない時は 設定の読み込み元・作業フォルダ・説明文 を確かめる
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
