Skip to main content
Agent Skills は、Claude が関連する場合に呼び出す特殊な機能で Claude を拡張します。Skills は、指示、説明、およびオプションのサポートリソースを含む SKILL.md ファイルとしてパッケージ化されます。このページでは、Agent SDK セッションのコマンドについても説明しています。 スキルの詳細(利点、アーキテクチャ、作成ガイドラインなど)については、Agent Skills の概要を参照してください。

Agent SDK での Skills の動作方法

Claude Agent SDK を使用する場合、Skills は以下のように機能します。
  • ファイルシステムアーティファクトとして定義される:各 Skill を SKILL.md ファイルとして独自のディレクトリ(.claude/skills/<name>/SKILL.md など)に作成します
  • ファイルシステムから読み込まれる:SDK は settingSources(TypeScript)または setting_sources(Python)によって管理されるファイルシステムの場所から Skills を読み込みます
  • 自動的に検出される:ファイルシステム設定が読み込まれると、SDK はスタートアップ時にユーザーおよびプロジェクトディレクトリから Skill メタデータを検出し、Claude が Skill を呼び出すときに完全なコンテンツを読み込みます
  • モデルによって呼び出される:Claude はコンテキストに基づいて自律的に使用するタイミングを選択します
  • ユーザーによって呼び出される:プロンプトで /<name> を送信して Skill を直接ディスパッチします。Agent SDK セッションのコマンドを参照してください
  • skills オプションでスコープされる:検出された Skills はデフォルトで有効になります。Skill 名のリスト、"all"、または [] を渡して、Claude が呼び出せる Skills を制御します
サブエージェント(agents オプションで定義できる)とは異なり、Skills はディスク上のファイルとして作成します。SDK は Skills を登録するためのプログラマティック API を提供しません。
Skills はファイルシステム設定ソースを通じて検出されます。デフォルトの query() オプションでは、SDK はユーザーおよびプロジェクトソースを読み込むため、~/.claude/skills/、<cwd>/.claude/skills/、および <cwd> の親ディレクトリからリポジトリルートまでの .claude/skills/ の Skills が利用可能です。プロジェクトソースは、additionalDirectories(TypeScript)または add_dirs(Python)を通じて渡す各ディレクトリの <dir>/.claude/skills/ もカバーしています。これは、SDK がそれらのディレクトリを Claude Code に --add-dir として渡すためです。settingSources を明示的に設定する場合は、プロジェクトおよび追加ディレクトリの Skills を保持するために 'project' を含め、個人用 Skills を保持するために 'user' を含めるか、plugins オプションを使用して特定のパスから Skills を読み込みます。

Agent SDK で Skills を使用する

query() の skills オプションを設定して、セッションで Claude が呼び出せる Skills を制御します。省略した場合、検出された Skills が有効になり、Skill ツールが利用可能になり、CLI の動作と一致します。"all" を渡してすべての検出された Skill を呼び出せるようにするか、Skill 名のリストを渡してそれらのみを許可するか、[] を渡して Claude が Skill を呼び出せないようにします。 たとえば、Claude が 2 つの名前付き Skills のみを呼び出せるようにするには:

セッションで Skills をセットアップする

skills を設定すると、SDK は Skill ツールを allowedTools に自動的に追加します。明示的な tools リストも渡す場合は、Claude が Skills を呼び出せるようにそのリストに "Skill" を含めてください。 設定されると、Claude はファイルシステムから Skills を自動的に検出し、ユーザーのリクエストに関連する場合に呼び出します。 次の例は、検出されたすべての Skill をセッションで有効にし、Skills が一般的に必要とするツールを事前承認します。この例は cwd をプロセスの現在の作業ディレクトリに設定するため、現在のディレクトリまたはリポジトリルートまでの親ディレクトリに .claude/skills/ ディレクトリを持つプロジェクト内から実行してください:

Skills が読み込まれたことを確認する

ストリームの開始付近で、SDK はサブタイプ init のシステムメッセージを生成します。その skills 配列をチェックして、Claude が作業を開始する前に Skills が読み込まれたことを確認します。配列には、description または when_to_use frontmatter フィールドで定義したユーザー呼び出し可能な Skills と、Claude Code に含まれるバンドルされた Skills が含まれます。 配列はユーザー呼び出し可能な Skills のみをリストします。フロントマターで user-invocable: false を持つ Skill は読み込まれ、Claude で利用可能なままですが、配列には表示されません。配列は、skills リストに含まれているかどうかに関わらず、同じ Skills をリストします。

特定の Skills のみを許可する

Claude が特定の Skills のみを呼び出せるようにするには、それらの名前を skills リストで渡します。名前は SKILL.md の name フィールドまたは Skill のディレクトリ名と一致します。プラグイン提供の Skills には plugin:skill を使用します。 リストは正確な Skill 名のみを受け入れます。エントリが正確な名前として機能できない場合、query() はセッション開始前にリストを拒否します。無効な Skill 名エラーで名前ルールと各 SDK が発生させるエラーを参照してください。 モデルはリストされていない Skills を見ず、Skill ツールはそれらを拒否しますが、それらのファイルはディスク上に残り、Read および Bash を通じてアクセス可能です。リストを制限しても、名前でのディスパッチは制限されません。 検出されたすべての Skill を呼び出せるようにするには、ワイルドカードではなく skills: "all" を渡します。

Agent SDK セッションのコマンド

このセクションは SDK のコマンドドキュメントです。コマンドは、プロンプトで /<name> を送信して実行するものです。コマンドサーフェスのエントリは、それらをサポートするものが異なります:
  • 組み込みコマンド:SDK が実行する Claude Code プロセスにコード化されたロジックを実行します。たとえば /compact
  • バンドルされた Skills:Claude Code に含まれるプロンプトアーティファクト。たとえば /code-review
  • あなたの Skills:あなたが作成するプロンプトアーティファクト。各ディレクトリは SKILL.md ファイルを保持します。ユーザー呼び出し可能な Skill の名前はサーフェスに自動的に参加するため、独自の /security-check をディスパッチして組み込みを実行することは同じ方法で機能します
  • カスタムコマンドファイル:同じ動作を持つ古いアーティファクト形式。.claude/commands/ 内のフラットな Markdown ファイル。ファイル名がコマンド名になります。Skills はそれらの推奨される後継です
デフォルトでは、あなたと Claude の両方が任意の skill を呼び出せます。skill のフロントマターを通じてどちらかのパスを制限できます。2 つの用語の定義については、用語集のコマンドおよびSkillエントリを参照してください。すべての組み込みについてはClaude Code のコマンドを、両方のアーティファクト形式の完全なガイドについてはClaude を skills で拡張するを参照してください。

利用可能なコマンドを検出する

SDK を通じてインタラクティブターミナルなしで機能するコマンドをディスパッチできます。system/init メッセージは、セッションで利用可能なコマンドを slash_commands フィールドにリストします。/theme や /terminal-setup などのインタラクティブターミナルが必要なコマンドはリストに表示されません。セッション開始時にフィールドにアクセスします:
印刷されたリストは、組み込みコマンド、バンドルされた Skills、ユーザー呼び出し可能な Skills、および .claude/commands/ ファイルを混在させます:
フロントマターで user-invocable: false を持つ skill はこのリストやConfirm skills loadedからの skills 配列に表示されません。MCP サーバーを設定するセッションは、MCP プロンプトをコマンドとして使用することもできます。

名前でコマンドをディスパッチする

プロンプト文字列にコマンドを含めて、通常のテキストを送信するのと同じ方法でコマンドを送信します。ディスパッチは skills オプションに依存しません。/<name> を送信すると、skills リストがそれを省略している場合でも、ユーザー呼び出し可能な Skill が実行されます。会話履歴に作用するコマンド(/compact など)は、作業する前のメッセージが必要です。 /<name> がセッション内のコマンドにも組み込み Claude Code コマンドにも一致しない場合、クエリは失敗しません。Claude Code はプロンプトを Claude に通常のメッセージとして送信し、コマンドが実行されなかったことを示すメモを付けるため、クエリはモデルターンを費やし、Claude の返信を返します。v2.1.274 より前では、何にも一致しない /<name> はモデルターンなしで Unknown command: /<name> を結果として返しました。 セッションで利用できない /theme などの組み込み Claude Code コマンドに一致する /<name> は、モデルターンなしで /theme isn't available in this environment. を結果として返します。
コマンドは、他のプロンプトと同様に maxTurns / max_turns 制限に達する可能性があり、success ではなくエラー結果でクエリを終了します。エラー結果契約については、結果を処理するを参照してください。コマンドが制限に達する可能性がある場合は、単一メッセージ入力に示されているように、TypeScript で try/catch またはPython で try/except でループをラップするか、作業が完了するのに十分な高さに maxTurns を設定します。

/compact で履歴をコンパクト化する

/compact コマンドは、古いメッセージを要約しながら重要なコンテキストを保持することで、会話履歴のサイズを削減します。コンパクト化には、要約する十分な前のメッセージを持つ既存の会話が必要です。この例は、最初に会話を行い、次にそれをコンパクト化し、結果を報告する compact_boundary システムメッセージを読みます:
compact_boundary メッセージは、コンパクト化が実行された場合にのみ到着します。継続されたセッションにメッセージがあるが、/compact が要約できるものがない場合、実行は依然として success 結果で終了し、compact_boundary メッセージは到着しません。結果テキストは理由を含みます。たとえば、セッションがプロンプトを保持しているが Claude からの返信がまだない場合は Not enough messages to compact. です。新しいワンショット query() 呼び出しは空のコンテキストで開始するため、このパターンを前のターンを持つセッション(たとえばストリーミング入力モードまたはセッションを再開するとき)で使用します。

/clear でコンテキストをリセットする

/clear コマンドは、会話を空のコンテキストにリセットするため、後続のプロンプトは前の会話履歴なしで開始します。前の会話はディスク上に残ります。resume オプションにセッション ID を渡すことで、その会話に戻ることができます。 /clear はストリーミング入力モードで有用です。単一の接続を通じて複数のプロンプトを送信します。ワンショット query() 呼び出しの場合、各呼び出しは既に空のコンテキストで開始するため、/clear を送信しても実際の効果はありません。代わりに新しい query() を開始します。

Skills を作成する

各 Skill を、YAML フロントマターと Markdown コンテンツを含む SKILL.md ファイルを含むディレクトリとして作成します。description フィールドは、Claude が Skill を呼び出すタイミングを決定します。 ディレクトリ構造の例:

検出レベルを選択する

2 つの最も一般的な検出レベルのいずれかで Skills を保存します:
  • プロジェクト Skills:.claude/skills/。現在のプロジェクトでのみ利用可能
  • 個人用 Skills:~/.claude/skills/。すべてのプロジェクト全体で利用可能
.claude/commands/ に既存のカスタムコマンドファイルがある場合、それらは機能し続けます。.claude/commands/deploy.md のコマンドファイルは /deploy を作成し、.claude/skills/deploy/SKILL.md の Skill と同じ方法で機能します。コマンドファイルと Skill が名前を共有する場合、名前を共有する Skills を解決するを参照して、どちらが実行されるかを確認します。SDK は .claude/commands/ および ~/.claude/commands/ ファイルを Skills と同じ 2 つのスコープから読み込みます。両方のアーティファクト形式の完全なガイドについては、Claude を Skills で拡張するを参照してください。

最初の Skill を作成してディスパッチする

完全なフローを確認するには、.claude/skills/security-check/SKILL.md を作成します:
ファイルが存在すると、Skill は SDK を通じて利用可能になります。Claude はリクエストが説明と一致するときに呼び出し、直接ディスパッチできます:
成功した実行は、テキストがスキャン結果を含む success 結果で終了します。シードされた問題を持つ小さな Express アプリに対して、結果テキストは以下で始まります:
Skill の名前は、init メッセージの slash_commands 配列にも表示されます。
Claude Code には、バンドルされた code-review および verify Skills が含まれています。.claude/commands/ ファイルにそれらの 1 つの後に名前を付ける場合(たとえば .claude/commands/code-review.md)、ファイルのコマンドはバンドルされた Skill をシャドウし、slash_commands は名前を 1 回リストします。

Skills のツールを事前承認する

SDK セッションでは、プロジェクトまたは個人用のスキルのツールを、スキルの allowed-tools フロントマター、またはクエリ設定の allowedTools オプション(Python では allowed_tools)で事前承認できます。組織が管理設定で allowManagedPermissionRulesOnly を設定している場合、Claude Code はその両方を無視します。claude.ai から同期された Skills は、独自のフロントマタールールに従います。
Skills はセッションのツールで実行されます。以下の例は、allowedTools(Python では allowed_tools)で Read、Grep、および Glob を事前承認するため、Claude はsecurity-check Skillを実行しながらファイルを検査でき、承認を停止する必要がありません:
ストリームでは、Skill 呼び出しは Skill ツール使用として表示され、その後にプロジェクトファイルの Read 呼び出しが続きます。実行は、テキストが結果を含む success 結果で終了します。 リストは、他を制限するのではなく、名前付きツールを事前承認します。権限モードおよび canUseTool コールバックを含む完全な権限フローについては、権限を参照してください。

トラブルシューティング

Skills が見つからない

settingSources 設定を確認する:SDK は user および project 設定ソースを通じて Skills を検出します。settingSources/setting_sources を明示的に設定し、それらのソースを省略した場合、SDK は Skills を読み込みません:
各ソースが読み込む Skill ディレクトリについては、ファイルシステムソーステーブルを参照してください。settingSources/setting_sources の詳細については、TypeScript SDK リファレンスまたは Python SDK リファレンスを参照してください。 作業ディレクトリを確認する:SDK は cwd オプションの .claude/skills/ およびリポジトリルートまでのすべての親ディレクトリから Skills を読み込みます。cwd が .claude/skills/ を含むディレクトリ以下を指していることを確認してください。同じリポジトリ内である必要があります:
完全なパターンについては、Agent SDK で Skills を使用するを参照してください。 ファイルシステムの場所を確認する:

Skill が使用されていない

skills オプションを確認する:skills リストを渡した場合、Skill の名前が含まれていることを確認します。Claude がリストされていない Skill を呼び出そうとすると、Skill ツールは Skill <name> is not in this session's skills allowlist を返します。名前をリストに追加するか、プロンプトで /<name> を送信して Skill を直接ディスパッチします。これはリストなしで機能します。 説明を確認する:具体的で関連するキーワードが含まれていることを確認します。効果的な説明の書き方に関するガイダンスについては、Agent Skills のベストプラクティスを参照してください。

無効な Skill 名エラー

skills リストの名前が正確な Skill 名として機能できない場合、query() は Claude Code プロセスを開始する前にリストを拒否します。拒否をトリガーする名前には以下が含まれます:
  • 空の名前
  • 括弧、コンマ、または制御文字を含む名前
  • 空白でパディングされた名前
  • * の裸の形式または:* サフィックスなどのワイルドカード形式
各 SDK は拒否を異なる方法でサーフェスします:
TypeScript SDK は、エントリが破ったルールを述べる Error をスローします。たとえば、skills: ["docs:*"] はスローします:
空の名前は Skill names must be non-empty strings. を報告しますTypeScript Agent SDK 0.3.221 より前では、SDK はこのチェックを実行しませんでした。

追加のトラブルシューティング

YAML 構文エラーおよびデバッグなどの一般的な Skills トラブルシューティングについては、Claude Code Skills トラブルシューティングセクションを参照してください。

次のステップ

Claude Code Skills ガイドは、作成を詳細にカバーしています。そのガイダンスは SDK セッションに適用されます。これらのセクションから始めてください: