Agent SDK Skillsの使い方 — スラッシュコマンドでの呼び出し方

Agent SDKでSkillsが動く仕組み

Agent SDKのSkillsは、ファイルシステム上のSKILL.mdをClaudeが自律的に呼び出す仕組みです。.claude/skills/<name>/SKILL.mdとしてディレクトリに置くだけで、セッション起動時にメタデータが読み込まれ、必要になった瞬間に本文が展開されます。Claude Code CLIのSkillsと中身は同じ仕組みですが、Agent SDKでは登録の入口がプログラムに無い点が異なります。Subagentsのようにagentsオプションへ直接定義する方法は無く、必ずディスク上のファイルとして用意します。

呼び出し方は2種類あります。Claudeが会話の文脈から判断して自律的に使う「モデル起動」と、プロンプト文字列に/<name>を書いて直接指定する「ユーザー起動」です。どちらの経路も同じSkillファイルを指しますが、skillsオプションでの許可リストが効くのはモデル起動側だけで、ユーザー起動側には及びません。

SKILL.mdのfrontmatterや本文構成の書き方はClaude Code Skills完全ガイドにまとまっています。Agent SDKの導入自体がまだの場合はClaude Agent SDK入門から始めると、query()の基本設計が先に頭に入ります。

skillsオプションでSkillsの利用範囲を絞る

query()のskillsオプションで、Claudeが呼び出せるSkillsの範囲を制御します。値は次の3パターンです。

TypeScriptとPythonの指定は次の通りです。

const options = { skills: ["pdf", "docx"] };

options = ClaudeAgentOptions(skills=["pdf", "docx"])

skillsオプションを設定すると、SDKはSkillツールをallowedToolsへ自動的に追加します。ツールリストを自分で明示している場合は、"Skill"を含めておかないとClaudeがSkillsを呼び出せません。

配列に渡す名前は完全一致だけを受け付けます。空文字・括弧やカンマを含む名前・前後に空白がある名前・*や:*のようなワイルドカードは、セッションが始まる前にquery()がエラーで弾きます。TypeScriptはError、PythonはValueErrorで、違反したルールを含むメッセージが返ります。このチェック自体はTypeScript Agent SDK 0.3.221、Python Agent SDK 0.2.129で追加されました。それより古いバージョンでは無効な名前を渡してもチェックが走りません。

settingSourcesがSkillsの発見条件を決める

skillsオプションで許可を絞っても、そもそもSkillsがディスクから読み込まれていなければ意味を持ちません。SDKはユーザー(~/.claude/skills/)とプロジェクト(<cwd>/.claude/skills/、リポジトリルートまでの親ディレクトリを含む)のファイルシステム設定からSkillsを発見します。この発見元を制御するのがsettingSources(Pythonはsetting_sources)です。

settingSourcesを明示して"user"と"project"を両方外すと、Skillsは1つも読み込まれません。query()のオプションを省略すればデフォルトでuser / project / localのすべてが読み込まれるため、通常は意識せずにSkillsが動きます。additionalDirectories(Pythonはadd_dirs)で渡したディレクトリの.claude/skills/も、プロジェクトソースの一部として扱われます。

# Skillsが読み込まれない: settingSourcesがuser/projectを含まない
options = ClaudeAgentOptions(setting_sources=[], skills="all")
 
# Skillsが読み込まれる
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],
    skills="all",
)

settingSourcesはSkills専用のオプションではなく、CLAUDE.mdやfilesystem hooksの読み込みにも影響する共通のスイッチです。値を触るときは、Skills以外への影響も一緒に確認します。

initメッセージでロード結果を確認する

セッション開始直後に流れるsystem初期化メッセージ(subtype: "init")のskills配列を見ると、ユーザー起動可能なSkillsが実際に読み込まれたか確認できます。この配列には、自分で書いたSkillsに加えてClaude Codeに同梱されているbundled skillsも並びます。

frontmatterでuser-invocable: falseを指定したSkillは、ディスクからは読み込まれてClaudeは使えますが、skills配列には出てきません。skillsオプションで許可したかどうかに関わらず、そのセッションが発見した内容がそのまま並びます。

同じinitメッセージのslash_commandsフィールドには、ビルトインコマンド・bundled skills・自分のユーザー起動Skills・.claude/commands/ファイルがまとめて並びます。インタラクティブな端末を必要とする/themeや/terminal-setupはこのリストに出ません。

if (message.type === "system" && message.subtype === "init") {
  console.log("Available commands:", message.slash_commands);
}

スラッシュコマンドで名前指定して呼び出す

プロンプト文字列に/<name>を書けば、Claudeの判断を待たずにそのSkillを直接実行できます。ディスパッチはskillsオプションの許可リストに依存しません。skillsのリストから名前を外していても、/<name>と送れば実行されます。制限できるのはモデル起動側の経路だけで、ユーザー起動の経路は別の枠だと考えます。

プラグイン経由のSkillsは/plugin-name:skill-nameという名前空間付きの形式で呼び出します。

/compactのように会話履歴を操作するコマンドは、要約する対象の履歴が無いと成立しません。単発のquery()は毎回空のコンテキストから始まるため、履歴操作系コマンドはストリーミング入力モードか、resumeでセッションを再開した状態で使います。

コマンドの実行も通常のプロンプトと同じくmaxTurns(Pythonはmax_turns)の上限にかかることがあります。上限に達するとsuccessではなくエラー付きの結果でクエリが終わるため、コマンドが長引く可能性があるならtry/catch(Pythonはtry/except)で囲むか、上限に余裕を持たせます。

Skillに引数を渡したいときは、/security-check src/のように名前の後ろへそのままテキストを続けます。SKILL.md側で$ARGUMENTSや$0・$1といった置換変数を定義しておけば、渡した文字列がその変数に展開された状態でSkill本文が実行されます。

Skillsが使うツールを事前承認する

Skillsはセッションのツールをそのまま使って動きます。ファイル読み取りが必要なSkillを承認なしで走らせたいなら、allowedTools(Pythonはallowed_tools)にツール名を渡しておきます。

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],
    skills="all",
    allowed_tools=["Read", "Grep", "Glob"],
)

プロジェクト / ユーザーSkillsについては、SKILL.mdのfrontmatterにあるallowed-toolsフィールドもSDKセッションで適用されます。allowedToolsオプションと合わせて二重に事前承認できる形です。claude.aiから同期されたSkillsだけは扱いが異なり、同期時点のfrontmatterルールに従います。

このリストは指定したツールを承認するだけで、それ以外のツールを禁止するものではありません。権限モードやcanUseToolコールバックを含めた全体の権限フローは別途設計します。

よくあるつまずき

Skillsが見つからない: settingSourcesを明示していてuser / projectを含めていないケースが最多です。次に多いのがcwdのずれです。SDKはcwdと、そこからリポジトリルートまでの各親ディレクトリの.claude/skills/を探すので、cwdが対象ディレクトリの外を指していると見つかりません。ls .claude/skills/*/SKILL.mdで実際にファイルがあるか先に確認します。

Skillが呼ばれない: skillsに配列を渡しているなら、まずその配列に名前が入っているか見ます。許可リストに無いSkillをClaudeが呼ぼうとすると、Skill toolはSkill <name> is not in this session's skills allowlistを返すだけで止まります。許可リストに追加するか、/<name>で直接呼び出せば許可リストを経由せずに動きます。それでも呼ばれなければSKILL.mdのdescriptionフィールドを見ます。具体的なキーワードを含んだ説明でないと、Claudeが「関連する」と判断してくれません。効果的な書き方はClaude Code Skillsの書き方にパターン集があります。許可リストから外したSkillのファイル自体は消えるわけではなく、ReadやBashのような通常ツールからは引き続き読み取れる点も覚えておきます。

名前を渡したのにエラーで弾かれる: 空文字・括弧やカンマ入り・前後の空白・ワイルドカードのいずれかが原因です。エラーメッセージに違反したルールがそのまま書かれているので、読んで名前を直します。

Agent SDK Skillsをどう使い分けるか

セッションの性質でskillsオプションの選び方は変わります。開発中でCLIと同じ挙動が欲しいなら省略でよく、本番で使わせるSkillsを固定したいなら配列で明示し、Skill機能そのものを止めたいマルチテナント用途なら[]にします。どの設定でも、settingSourcesがuser / projectを含んでいることが前提です。ここが抜けていると、skills側をどう設定してもSkillsは1つも発見されません。

よくある質問

.claude/commands/のファイルはskillsオプションの対象になりますか

対象になりません。skillsオプションが制御するのはSkill tool経由の呼び出しだけです。.claude/commands/のコマンドファイルはslash_commandsには現れますがskills配列には現れず、ディスパッチもskillsの許可リストとは無関係に動きます。

Claude Codeに同梱されているbundled skillsはskillsオプションで無効化できますか

skillsオプションはユーザー起動可能なSkillsを絞る仕組みで、bundled skillsを個別に無効化する機能ではありません。bundled skills全体を止めたい場合はdisableBundledSkills設定を使います。/doctorだけはこの設定でも無効になりません。

CLIのSkillsとAgent SDKのSkillsは同じファイルを共有しますか

同じファイルです。.claude/skills/以下のディレクトリ構成もSKILL.mdの書式もCLIと共通で、Agent SDK固有なのはskillsとsettingSourcesという2つのオプションによる制御だけです。

Skillと同名の.claude/commands/ファイルがあるとどちらが動きますか

コマンドファイルの側がSkillを覆い隠します。たとえば.claude/commands/code-review.mdを作ると、Claude Code同梱のcode-review skillより先にそのファイルの内容が使われ、slash_commandsには名前が1つだけ並びます。

まとめ

Agent SDKでSkillsを使うには、settingSourcesでファイルシステムからの発見を有効にし、skillsオプションで呼び出せる範囲を絞り、必要ならallowedToolsでツールを事前承認します。この3つを別のレイヤーとして扱うと、設定のどこが原因で動かないのかを切り分けやすくなります。