SDK の Agent Skills

Claude Agent SDK を使用して、Agent Skills で Claude を特殊な機能で拡張します

概要

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

Skills に関する包括的な情報（利点、アーキテクチャ、作成ガイドラインを含む）については、Agent Skills の概要を参照してください。

SDK での Skills の動作方法

Claude Agent SDK を使用する場合、Skills は以下のように機能します。

1. ファイルシステムアーティファクトとして定義される：特定のディレクトリ（.claude/skills/）に SKILL.md ファイルとして作成されます
2. ファイルシステムから読み込まれる：Skills は settingSources（TypeScript）または setting_sources（Python）によって管理されるファイルシステムの場所から読み込まれます
3. 自動的に検出される：ファイルシステム設定が読み込まれると、Skill メタデータはスタートアップ時にユーザーおよびプロジェクトディレクトリから検出されます。完全なコンテンツはトリガーされたときに読み込まれます
4. モデルによって呼び出される：Claude はコンテキストに基づいて自律的に使用するタイミングを選択します
5. skills オプションでフィルタリングされる：検出された Skills はデフォルトで有効になります。スキル名のリスト、"all"、または [] を渡して、セッションで利用可能なものを制御します

サブエージェント（プログラムで定義できる）とは異なり、Skills はファイルシステムアーティファクトとして作成する必要があります。SDK は Skills を登録するためのプログラマティック API を提供しません。

SDK での Skills の使用

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

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
options = ClaudeAgentOptions(
cwd="/path/to/project",  # Project with .claude/skills/
setting_sources=["user", "project"],  # Load Skills from filesystem
skills="all",  # Enable 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())

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

for await (const message of query({
prompt: "Help me process this PDF document",
options: {
cwd: "/path/to/project", // Project with .claude/skills/
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all", // Enable every discovered Skill
allowedTools: ["Read", "Write", "Bash"]
}
})) {
console.log(message);
}

特定の Skills のみを有効にするには、それらの名前を渡します。名前は SKILL.md の name フィールドまたは Skill のディレクトリ名と一致します。プラグイン提供の Skills には plugin:skill を使用します。

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

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

skills オプションはコンテキストフィルタであり、サンドボックスではありません。リストされていない Skills はモデルから非表示になり、Skill ツールによって拒否されますが、それらのファイルはディスク上に残り、Read および Bash を通じてアクセス可能です。

Skill の場所

Skills は settingSources/setting_sources 設定に基づいてファイルシステムディレクトリから読み込まれます。

• プロジェクト Skills（.claude/skills/）：git を通じてチームと共有されます。setting_sources に "project" が含まれている場合に読み込まれます
• ユーザー Skills（~/.claude/skills/）：すべてのプロジェクト全体の個人用 Skills。setting_sources に "user" が含まれている場合に読み込まれます
• プラグイン Skills：インストールされた Claude Code プラグインにバンドルされています

Skills の作成

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

ディレクトリ構造の例：

.claude/skills/processing-pdfs/
└── SKILL.md

Skills の作成に関する完全なガイダンス（SKILL.md 構造、複数ファイルの Skills、例を含む）については、以下を参照してください。

• Claude Code の Agent Skills：例を含む完全なガイド
• Agent Skills のベストプラクティス：作成ガイドラインと命名規則

ツール制限

SDK アプリケーションで Skills のツールアクセスを制御するには、allowedTools を使用して特定のツールを事前承認します。canUseTool コールバックがない場合、リストにないものはすべて拒否されます。

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

async for message in query(prompt="Analyze the codebase structure", options=options):
print(message)

for await (const message of query({
prompt: "Analyze the codebase structure",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "dontAsk" // Deny anything not in allowedTools
}
})) {
console.log(message);
}

利用可能な Skills の検出

SDK アプリケーションで利用可能な Skills を確認するには、Claude に尋ねるだけです。

options = ClaudeAgentOptions(
setting_sources=["user", "project"],  # Load Skills from filesystem
skills="all",
)

async for message in query(prompt="What Skills are available?", options=options):
print(message)

for await (const message of query({
prompt: "What Skills are available?",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all"
}
})) {
console.log(message);
}

Claude は、現在の作業ディレクトリとインストールされたプラグインに基づいて、利用可能な Skills をリストします。

Skills のテスト

説明と一致する質問をすることで Skills をテストします。

options = ClaudeAgentOptions(
cwd="/path/to/project",
setting_sources=["user", "project"],  # Load Skills from filesystem
skills="all",
allowed_tools=["Read", "Bash"],
)

async for message in query(prompt="Extract text from invoice.pdf", options=options):
print(message)

for await (const message of query({
prompt: "Extract text from invoice.pdf",
options: {
cwd: "/path/to/project",
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Bash"]
}
})) {
console.log(message);
}

説明がリクエストと一致する場合、Claude は自動的に関連する Skill を呼び出します。

トラブルシューティング

Skills が見つからない

settingSources 設定を確認する：Skills は user および project 設定ソースを通じて検出されます。settingSources/setting_sources を明示的に設定し、それらのソースを省略した場合、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",
)

// Skills not loaded: settingSources excludes user and project
const options = {
settingSources: [],
skills: "all"
};

// Skills loaded: user and project sources included
const options = {
settingSources: ["user", "project"],
skills: "all"
};

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",
)

// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};

上記の「SDK での Skills の使用」セクションで完全なパターンを参照してください。

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

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

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

Skill が使用されていない

skills オプションを確認する：skills リストを渡した場合、skill の名前が含まれていることを確認します。[] を渡すとすべての skills が無効になります。

説明を確認する：具体的で関連するキーワードが含まれていることを確認します。効果的な説明の書き方に関するガイダンスについては、Agent Skills のベストプラクティスを参照してください。

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

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

関連ドキュメント

Skills ガイド

• Claude Code の Agent Skills：作成、例、トラブルシューティングを含む完全な Skills ガイド
• Agent Skills の概要：概念的な概要、利点、アーキテクチャ
• Agent Skills のベストプラクティス：効果的な Skills のための作成ガイドライン
• Agent Skills クックブック：例の Skills とテンプレート

SDK リソース

• SDK のサブエージェント：プログラマティックオプションを備えた同様のファイルシステムベースのエージェント
• SDK のスラッシュコマンド：ユーザーが呼び出すコマンド
• SDK の概要：一般的な SDK の概念
• TypeScript SDK リファレンス：完全な API ドキュメント
• Python SDK リファレンス：完全な API ドキュメント