SpyBara
Go Premium

agent-sdk/skills.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

This page contains 5 additions and 1 deletion.

2026
Wed 9 22:58 Mon 14 22:58 Fri 18 23:58

Agent Skills でエージェントを拡張する

Claude Agent SDK セッションで Claude が呼び出せる Skills を制御し、名前でコマンドをディスパッチし、セッションが検出する Skills を作成します

Agent Skills は、Claude が関連する場合に呼び出す特殊な機能で Claude を拡張します。Skills は、指示、説明、およびオプションのサポートリソースを含む SKILL.md ファイルとしてパッケージ化されます。このページでは、Agent SDK セッションのコマンドについても説明しています。

Skills に関する包括的な情報（利点、アーキテクチャ、作成ガイドラインを含む）については、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 を提供しません。

Agent SDK で Skills を使用する

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

たとえば、Claude が 2 つの名前付き Skills のみを呼び出せるようにするには：

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

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

skills を設定すると、SDK は Skill ツールを allowedTools に自動的に追加します。明示的な tools リストも渡す場合は、Claude が Skills を呼び出せるようにそのリストに "Skill" を含めてください。

設定されると、Claude はファイルシステムから Skills を自動的に検出し、ユーザーのリクエストに関連する場合に呼び出します。

次の例は、検出されたすべての Skill をセッションで有効にし、Skills が一般的に必要とするツールを事前承認します。この例は cwd をプロセスの現在の作業ディレクトリに設定するため、現在のディレクトリまたはリポジトリルートまでの親ディレクトリに .claude/skills/ ディレクトリを持つプロジェクト内から実行してください：

import asyncio
import os

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
options = ClaudeAgentOptions(
cwd=os.getcwd(),  # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"],  # Load skills from filesystem
skills="all",  # Let Claude invoke every discovered skill
allowed_tools=["Read", "Write", "Bash"],
)

async for message in query(
prompt="Help me process this PDF document", options=options
):
print(message)


asyncio.run(main())

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 などのインタラクティブターミナルが必要なコマンドはリストに表示されません。セッション開始時にフィールドにアクセスします：

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);
}
}

印刷されたリストは、組み込みコマンド、バンドルされた Skills、ユーザー呼び出し可能な Skills、および .claude/commands/ ファイルを混在させます：

Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]

フロントマターで 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. を結果として返します。

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

/compact コマンドは、古いメッセージを要約しながら重要なコンテキストを保持することで、会話履歴のサイズを削減します。コンパクト化には、要約する十分な前のメッセージを持つ既存の会話が必要です。この例は、最初に会話を行い、次にそれをコンパクト化し、結果を報告する compact_boundary システムメッセージを読みます：

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

// Compaction needs existing history, so have a conversation first
try {
for await (const message of query({
prompt: "Explain what this project does",
options: { maxTurns: 2 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result,
// so the follow-up query below still runs.
console.error(`Session ended with an error: ${error}`);
}

// Compact the same conversation
for await (const message of query({
prompt: "/compact",
options: { continue: true, maxTurns: 1 }
})) {
if (message.type === "system" && message.subtype === "compact_boundary") {
console.log("Compaction completed");
console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
console.log("Trigger:", message.compact_metadata.trigger);
// Example output:
// Compaction completed
// Pre-compaction tokens: 1842
// Trigger: manual
}
}

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

/clear コマンドは、会話を空のコンテキストにリセットするため、後続のプロンプトは前の会話履歴なしで開始します。前の会話はディスク上に残ります。resume オプションにセッション ID を渡すことで、その会話に戻ることができます。

/clear はストリーミング入力モードで有用です。単一の接続を通じて複数のプロンプトを送信します。ワンショット query() 呼び出しの場合、各呼び出しは既に空のコンテキストで開始するため、/clear を送信しても実際の効果はありません。代わりに新しい query() を開始します。

Skills を作成する

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

ディレクトリ構造の例：

.claude/skills/security-check/
└── SKILL.md

検出レベルを選択する

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 を作成します：

---
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

ファイルが存在すると、Skill は SDK を通じて利用可能になります。Claude はリクエストが説明と一致するときに呼び出し、直接ディスパッチできます：

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

for await (const message of query({
prompt: "/security-check",
options: { maxTurns: 10 }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

成功した実行は、テキストがスキャン結果を含む success 結果で終了します。シードされた問題を持つ小さな Express アプリに対して、結果テキストは以下で始まります：

**Security scan of `app.js` — 4 findings (most severe first):**

1. **SQL Injection** (line 8) — `req.query.name` is concatenated directly into the SQL string. Trivially exploitable (`' OR '1'='1`, `'; DROP TABLE users;--`). **Fix:** use parameterized queries, e.g. `db.query("SELECT * FROM users WHERE name = ?", [req.query.name], cb)`.
...

Skill の名前は、init メッセージの slash_commands 配列にも表示されます。

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

Skills はセッションのツールで実行されます。以下の例は、allowedTools（Python では allowed_tools）で Read、Grep、および Glob を事前承認するため、Claude はsecurity-check Skillを実行しながらファイルを検査でき、承認を停止する必要がありません：

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

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


async def main():
async for message in query(prompt="Check this project for security issues", options=options):
print(message)


asyncio.run(main())

ストリームでは、Skill 呼び出しは Skill ツール使用として表示され、その後にプロジェクトファイルの Read 呼び出しが続きます。実行は、テキストが結果を含む success 結果で終了します。

リストは、他を制限するのではなく、名前付きツールを事前承認します。権限モードおよび canUseTool コールバックを含む完全な権限フローについては、権限を参照してください。

トラブルシューティング

Skills が見つからない

settingSources 設定を確認する：SDK は user および project 設定ソースを通じて Skills を検出します。settingSources/setting_sources を明示的に設定し、それらのソースを省略した場合、SDK は Skills を読み込みません：

# Skills not loaded: setting_sources excludes user and project
options = ClaudeAgentOptions(setting_sources=[], skills="all")

# Skills loaded: user and project sources included
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
)

各ソースが読み込む Skill ディレクトリについては、ファイルシステムソーステーブルを参照してください。settingSources/setting_sources の詳細については、TypeScript SDK リファレンスまたは Python SDK リファレンスを参照してください。

作業ディレクトリを確認する：SDK は cwd オプションの .claude/skills/ およびリポジトリルートまでのすべての親ディレクトリから Skills を読み込みます。cwd が .claude/skills/ を含むディレクトリ以下を指していることを確認してください。同じリポジトリ内である必要があります：

# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
cwd="/path/to/project",  # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"],  # Loads skills from these sources
skills="all",
)

完全なパターンについては、Agent SDK で Skills を使用するを参照してください。

ファイルシステムの場所を確認する：

# Check project skills
ls .claude/skills/*/SKILL.md

# Check personal skills
ls ~/.claude/skills/*/SKILL.md

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:*"] はスローします：

Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.

空の名前は Skill names must be non-empty strings. を報告します

TypeScript Agent SDK 0.3.221 より前では、SDK はこのチェックを実行しませんでした。

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

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

次のステップ

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