概要
Claude Agent SDK でスキルを設定・発見・実行するための仕様。スキルは SKILL.md ファイルとしてファイルシステムに置き、SDK が起動時に自動検出してセッションで利用できるようにする。
仕様
スキルの動作
- ファイルシステム成果物:
.claude/skills/<name>/SKILL.mdとして作成する - ロード元:
settingSources（Python:setting_sources）で指定したパスから SDK がロード - 自動検出: 起動時にメタデータを検出し、Claude が実際に呼び出すときに全文をロード
- モデル呼び出し: Claude がコンテキストに応じて自律的に選択・呼び出す
- ユーザー呼び出し: プロンプトで
/<name>を送信することで直接ディスパッチできる - スコープ制御:
skillsオプションで呼び出せるスキルを制限できる - SDK にスキルを登録するプログラム API はない。スキルはファイルシステム上に作成する
skills オプション
| 値 | 動作 |
|---|---|
| 省略 | 検出済みスキルがすべて有効。Skill ツールも利用可能（CLI と同じ動作） |
"all" | 検出済みスキルをすべて Claude が呼び出せる |
["pdf", "docx"] などの名前リスト | リストに含まれるスキルのみ Claude が呼び出せる |
[] | Claude が呼び出せるスキルはない |
skillsを設定すると SDK はallowedToolsに Skill ツールを自動追加する- 明示的な
toolsリストも渡す場合は"Skill"をそのリストに含める必要がある
スキルのロード確認
- ストリームの開始付近で SDK がサブタイプ
initのシステムメッセージを yield する message.skills配列（Python:message.data["slash_commands"]）でロードされたスキルを確認できるuser-invocable: falseのスキルはロードされるがskills配列に現れない- 配列は
skillsリストへの含有にかかわらず、セッションが検出したスキルを列挙する
特定スキルのみを許可する
skillsリストにスキル名を渡す。名前はSKILL.mdのnameフィールドまたはディレクトリ名と一致させる- プラグイン提供スキルには
plugin:skill形式を使う - 完全一致のみ。ワイルドカード不可
- リストにないスキルは Skill ツールが拒否するが、ファイルはディスク上に残る
/<name>でのユーザーディスパッチはリスト外でも機能する
コマンドの種類（Agent SDK セッション）
| 種別 | 説明 |
|---|---|
| 組み込みコマンド | Claude Code プロセスにコーディングされたロジック（例: /compact） |
| バンドルスキル | Claude Code に同梱のプロンプト成果物（例: /code-review、/verify） |
| ユーザースキル | ユーザーが作成した SKILL.md ファイル |
| カスタムコマンドファイル | .claude/commands/ 内のフラット Markdown ファイル（スキルの旧形式） |
system/initメッセージのslash_commandsフィールドで利用可能なコマンドを確認できる- インタラクティブなターミナルを必要とするコマンド（例:
/theme、/terminal-setup）はリストに現れない
コマンドのディスパッチ
/<name>をプロンプト文字列に含めて送信する- ディスパッチは
skillsオプションに依存しない。skillsリストに含まれていないスキルでも/<name>で実行できる maxTurns/max_turnsの上限に達する可能性がある場合は try/catch（TypeScript）または try/except（Python）で囲む
/compact
- 古いメッセージを要約してコンテキストウィンドウを縮小する
- 要約には既存の会話履歴が必要。ワンショット
query()の初回呼び出しには効果なし - コンパクションが実行された場合のみ
compact_boundaryシステムメッセージが届く - 要約対象がない場合: エラーを出さず
successで終了し、result テキストに理由が入る
/clear
- 会話を空のコンテキストにリセットする（以前の会話はディスク上に残る）
- ストリーミング入力モードで有用。ワンショット
query()では各呼び出しがすでに空のコンテキストで始まるため実用的な効果はない
スキルの作成
- ディレクトリと
SKILL.mdファイル（YAML フロントマター + Markdown）で構成する descriptionフィールドで Claude がスキルを呼び出すタイミングを制御する
発見レベル:
| レベル | パス | 有効範囲 |
|---|---|---|
| プロジェクトスキル | .claude/skills/ | 現在のプロジェクトのみ |
| 個人スキル | ~/.claude/skills/ | すべてのプロジェクト |
ツールの事前承認
allowedTools（Python:allowed_tools）でスキルが使うツールを事前承認できる- プロジェクト・個人スキルには SKILL.md の
allowed-toolsフロントマターフィールドも SDK セッション内で適用される
制約・注意点
スキルが見つからない場合
settingSources/setting_sourcesに"user"と"project"を含める必要がある。省略するとスキルはロードされないcwdは.claude/skills/を含むディレクトリかその下を指す必要がある（リポジトリルートまでの親ディレクトリも探索される）
スキルが使われない場合
skillsリストを渡した場合、スキル名がリストに含まれているか確認するdescriptionフィールドが具体的で関連キーワードを含んでいるか確認する
無効なスキル名エラー
query() がセッション開始前にリストを拒否する条件:
- 空の名前
- 括弧・カンマ・制御文字を含む名前
- 空白でパディングされた名前
- ワイルドカード形式（
*単独、または:*サフィックス）
| SDK | 動作 | バージョン制約 |
|---|---|---|
| TypeScript | Claude Code プロセス起動前に Error をスロー | TypeScript Agent SDK 0.3.221 より前はこのチェックを実行しない |
| Python | ValueError を raise | Python Agent SDK 0.2.129 より前はこのチェックを実行しない |