ホーム / チュートリアル / Agent SDK のスキルとスラッシュコマンドの使い方

Agent SDK のスキルとスラッシュコマンドの使い方

Claude Agent SDK エンジニアリング 7分で読めます

Agent Skills は、指示・説明・補助ファイルを SKILL.md にまとめ、Claude が必要なときに呼び出せるようにする仕組みです。この記事では公式ドキュメント「Extend agents with skills」に沿って、Claude Agent SDK のセッションでスキルを読み込む条件、skills オプションで呼べるスキルを絞る方法、/compact や自作スキルを /名前 で送るコマンド実行を整理します。スキルそのものの考え方は「スキルとは何か？」、CLI での作り方は「はじめてのスキルを作る」を参照してください。

Agent SDK でスキルが読み込まれる仕組み

Agent SDK のスキルには、次の特徴があります。

query() の既定ではユーザーとプロジェクトのソースが読まれるので、~/.claude/skills/、<cwd>/.claude/skills/、さらに cwd からリポジトリのルートまでの親ディレクトリにある .claude/skills/ が対象になります。additionalDirectories（Python は add_dirs）で渡したディレクトリの .claude/skills/ もプロジェクトのソースとして読まれます。これは SDK がそれらを Claude Code に --add-dir として渡すためです。

settingSources を明示する場合は、プロジェクトと追加ディレクトリのスキルを残すなら 'project'、個人のスキルを残すなら 'user' を含めます。特定のパスからスキルを読みたいときは plugins オプションも使えます（「Agent SDK のプラグイン」参照）。なお Python SDK のリファレンスには、setting_sources を指定せず skills も設定しない場合は CLI と同じく user・project・local の3つを読み込み、skills を設定して setting_sources を省いた場合は user と project だけが読まれる、と書かれています。

skills オプションで呼べるスキルを絞る

query() の skills オプションで、そのセッションで Claude が呼び出せるスキルを決めます。指定しなければ見つかったスキルがすべて有効で Skill ツールも使え、CLI と同じ挙動になります。指定できる値は次の3種類です。

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

skills を設定すると、SDK は Skill ツールを allowedTools に自動で加えます。ただし tools で使えるツールを明示している場合は、その配列に "Skill" を含めないとスキルを呼び出せません。次は見つかったスキルをすべて有効にし、スキルがよく使うツールを事前承認する例です。

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Help me process this PDF document",
  options: {
    cwd: process.cwd(), // ここか親ディレクトリに .claude/skills/ がある
    settingSources: ["user", "project"], // ファイルシステムからスキルを読む
    skills: "all",
    allowedTools: ["Read", "Write", "Bash"]
  }
})) {
  console.log(message);
}

配列に書く名前の決まりは次のとおりです。

配列は正確な名前しか受け付けません。空文字、括弧・カンマ・制御文字を含む名前、前後に空白がある名前、* や docs:* のようなワイルドカードは、セッション開始前に拒否されます。TypeScript では Error、Python では ValueError になり、たとえば docs:* には「wildcard-suffix names are not allowed」という趣旨のメッセージが返ります。この検査は TypeScript SDK 0.3.221 以降、Python SDK 0.2.129 以降で行われます。すべて許可したいときはワイルドカードではなく "all" を使います。

配列に入れなかったスキルはモデルから見えず、Skill ツールも拒否します。ただしファイル自体はディスクに残っているので、Read や Bash からは読めます。また、この制限は次節の「名前を指定した直接実行」には効きません。

スキルが読み込まれたかは、ストリームの最初のほうで届く subtype が init のシステムメッセージの skills 配列で確かめられます。ここに並ぶのは、フロントマターに description か when_to_use を書いた利用者が呼べるスキルと、Claude Code に同梱されたスキルです。user-invocable: false を書いたスキルは読み込まれて Claude からは使えますが、この配列には出ません。配列の中身は skills オプションで絞っても変わりません。

コマンドを一覧して /名前 で送る

SDK でいう「コマンド」は、プロンプトに /<name> と書いて実行するもの全般を指します。中身によって次の4種類があります。

種類中身例
組み込みコマンドSDK が動かす Claude Code プロセスに組み込まれた処理/compact
同梱スキルClaude Code に含まれるプロンプト/code-review
自作のスキルSKILL.md を持つディレクトリ。利用者が呼べるものは自動でコマンドになる/security-check
カスタムコマンドファイル.claude/commands/ の Markdown。ファイル名がコマンド名になる旧来の形式で、後継はスキル.claude/commands/deploy.md → /deploy

SDK から実行できるのは、対話型ターミナルが無くても動くコマンドです。使えるものは init メッセージの slash_commands に並びます。/theme や /terminal-setup のようにターミナルが必要なものは出てきません。

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Hello Claude",
  options: { maxTurns: 1 }
})) {
  if (message.type === "system" && message.subtype === "init") {
    console.log("Available commands:", message.slash_commands);
  }
}
async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):
    if isinstance(message, SystemMessage) and message.subtype == "init":
        print("Available commands:", message.data["slash_commands"])

出力には clear・compact・context・usage などの組み込み、code-review・verify などの同梱スキル、自作スキル、.claude/commands/ のファイルが混ざって並びます。MCP サーバーを設定したセッションでは、MCP のプロンプトもコマンドとして現れることがあります。

実行は、プロンプトの文字列にそのまま書くだけです。名前による実行は skills オプションとは無関係で、配列に入れていないスキルでも /<name> で送れば動きます。どれにも当てはまらない /<name> はエラーにならず、「コマンドは実行されなかった」という注記付きの普通のメッセージとして Claude に送られ、1ターン分を使って返答が返ります（v2.1.274 より前は Unknown command: /<name> を返していました）。一方、/theme のようにこの環境では使えない組み込みコマンドは、モデルを呼ばずに「この環境では使えない」という結果を返します。

コマンドもほかのプロンプトと同じく maxTurns（Python は max_turns）の上限に達することがあり、その場合は success ではなくエラーの結果で終わります。長くかかりそうなコマンドは try/catch（Python は try/except）で囲むか、上限を十分に取っておきます。結果の扱いは「Agent SDK のエージェントループ」で解説しています。

/compact と /clear で会話を整理する

/compact は、古いメッセージを要約して大事な文脈を残しつつ、会話履歴を小さくする組み込みコマンドです。要約する履歴が必要なので、先に会話をしてから同じ会話を続ける形で送ります。結果は compact_boundary のシステムメッセージで届きます。

// まず会話をして履歴を作る（maxTurns に達すると throw するので囲む）
try {
  for await (const message of query({
    prompt: "Explain what this project does",
    options: { maxTurns: 2 }
  })) { /* ... */ }
} catch (error) {
  console.error(`Session ended with an error: ${error}`);
}

// 同じ会話を compact する
for await (const message of query({
  prompt: "/compact",
  options: { continue: true, maxTurns: 1 }
})) {
  if (message.type === "system" && message.subtype === "compact_boundary") {
    console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
    console.log("Trigger:", message.compact_metadata.trigger); // 例: manual
  }
}

Python では ClaudeAgentOptions(continue_conversation=True, max_turns=1) を渡し、message.data["compact_metadata"]["pre_tokens"] のように読みます。compact_boundary が届くのは実際に要約が行われたときだけです。要約できるものが無い場合もエラーにはならず success で終わり、結果の文面に理由（たとえば Claude の返答がまだ無いときの Not enough messages to compact.）が入ります。新しい単発の query() は空の文脈から始まるので、ストリーミング入力モードや再開したセッションのように、すでにやり取りがある会話で使います。

/clear は会話を空の文脈に戻すコマンドです。以前の会話はディスクに残っているので、そのセッション ID を resume オプションに渡せば戻れます（「Agent SDK のセッション管理」参照）。1つの接続で複数のプロンプトを送るストリーミング入力モードで役立ちます。単発の query() は毎回空の文脈で始まるため、/clear を送っても実質的な効果はなく、新しい query() を始めれば十分です。

スキルを作って事前承認し、つまずきを直す

スキルは、YAML フロントマターと Markdown の本文を持つ SKILL.md をディレクトリに置いて作ります。Claude がいつ呼び出すかを決めるのは description です。置き場所は、そのプロジェクトだけで使うなら .claude/skills/、すべてのプロジェクトで使うなら ~/.claude/skills/ です。既存の .claude/commands/ のファイルもそのまま動き、.claude/commands/deploy.md は .claude/skills/deploy/SKILL.md と同じく /deploy になります。

---
name: security-check
description: Run a security vulnerability scan
---

Analyze the codebase for security vulnerabilities including:
- SQL injection risks
- XSS vulnerabilities
- Exposed credentials
- Insecure configurations

これを .claude/skills/security-check/SKILL.md に置けば、説明に合う依頼で Claude が呼び出すほか、prompt: "/security-check" として直接実行できます。名前は init メッセージの slash_commands にも現れます。なお .claude/commands/code-review.md のように同梱スキルと同じ名前のファイルを作ると、ファイルのコマンドが同梱スキルを上書きし、slash_commands には1回だけ載ります。

スキルはセッションのツールで動きます。承認待ちで止まらないようにするには、スキルのフロントマターの allowed-tools か、query() の allowedTools（Python は allowed_tools）でツールを事前承認します。次は Read・Grep・Glob を事前承認する例です。この配列は名前を挙げたツールを承認するだけで、ほかのツールを禁止するものではありません。組織が管理設定で allowManagedPermissionRulesOnly を有効にしている場合は、どちらの事前承認も無視されます。

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

権限の流れ全体は「Agent SDK の権限設定」を参照してください。うまく動かないときは、公式のトラブルシューティングに沿って次を確認します。

フロントマターの全項目や $ARGUMENTS による引数の渡し方、!`command` で実行結果を差し込む方法など、スキルの書き方そのものは CLI と共通です。「スキルの設定と複数ファイル構成」もあわせて参照してください。

本ページは Extend agents with skills を中心に、Agent SDK reference - Python の skills・setting_sources の記述を踏まえた非公式の日本語解説です（確認日 2026-10-28）。コード例は一部を簡略化しています。最新の仕様は公式ドキュメントを確認してください。

関連チュートリアル / 次に読む

スキルとは何か？ はじめてのスキルを作る Agent SkillsをClaude APIから使う Agent SDK でプラグインを読み込む設定と確認方法 Agent SDK の権限設定：permissionMode と allowedTools の使い方
← チュートリアル一覧へ戻る カテゴリで探す