SDK内のエージェントスキル

概要

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

スキルの利点、アーキテクチャ、および作成ガイドラインを含む包括的な情報については、エージェントスキルの概要を参照してください。

SDKでのスキルの動作方法

Claude Agent SDKを使用する場合、スキルは以下のようになります：

ファイルシステムアーティファクトとして定義される：特定のディレクトリ（.claude/skills/）にSKILL.mdファイルとして作成されます
ファイルシステムから読み込まれる：スキルは設定されたファイルシステムの場所から読み込まれます。ファイルシステムからスキルを読み込むには、settingSources（TypeScript）またはsetting_sources（Python）を指定する必要があります
自動的に検出される：ファイルシステム設定が読み込まれると、スキルメタデータはスタートアップ時にユーザーおよびプロジェクトディレクトリから検出されます。完全なコンテンツはトリガーされたときに読み込まれます
モデルによって呼び出される：Claudeはコンテキストに基づいて自律的に使用するかどうかを選択します
allowed_toolsで有効化される：allowed_toolsに"Skill"を追加してスキルを有効にします

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

デフォルトの動作：デフォルトでは、SDKはファイルシステム設定を読み込みません。スキルを使用するには、オプションでsettingSources: ['user', 'project']（TypeScript）またはsetting_sources=["user", "project"]（Python）を明示的に設定する必要があります。

SDKでのスキルの使用

SDKでスキルを使用するには、以下を行う必要があります：

allowed_tools設定に"Skill"を含める
settingSources/setting_sourcesを設定してファイルシステムからスキルを読み込む

設定されると、Claudeは指定されたディレクトリからスキルを自動的に検出し、ユーザーのリクエストに関連する場合に呼び出します。

スキルの場所

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

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

スキルの作成

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

ディレクトリ構造の例：

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

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

Claude Codeのエージェントスキル：例を含む完全なガイド
エージェントスキルのベストプラクティス：作成ガイドラインと命名規則

ツール制限

SKILL.mdのフロントマターallowed-toolsフィールドは、Claude Code CLIを直接使用する場合にのみサポートされます。SDKを通じてスキルを使用する場合には適用されません。

SDKを使用する場合は、クエリ設定のメインallowedToolsオプションを通じてツールアクセスを制御します。

SDK アプリケーションでスキルのツールを制限するには、allowedToolsオプションを使用します：

最初の例のインポートステートメントは、以下のコードスニペットで想定されています。

利用可能なスキルの検出

SDKアプリケーションで利用可能なスキルを確認するには、単にClaudeに尋ねます：

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

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

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

スキルのテスト

説明に一致する質問をすることでスキルをテストします：

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

トラブルシューティング

スキルが見つからない

settingSources設定を確認する：スキルはsettingSources/setting_sourcesを明示的に設定した場合にのみ読み込まれます。これが最も一般的な問題です：

# 間違い - スキルは読み込まれません
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# 正しい - スキルが読み込まれます
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

settingSources/setting_sourcesの詳細については、TypeScript SDKリファレンスまたはPython SDKリファレンスを参照してください。

作業ディレクトリを確認する：SDKはcwdオプションに相対的にスキルを読み込みます。.claude/skills/を含むディレクトリを指していることを確認してください：

# cwdが.claude/skills/を含むディレクトリを指していることを確認します
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # Must contain .claude/skills/
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["Skill"]
)

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

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

# プロジェクトスキルを確認
ls .claude/skills/*/SKILL.md

# 個人スキルを確認
ls ~/.claude/skills/*/SKILL.md

スキルが使用されていない

スキルツールが有効になっていることを確認する：allowedToolsに"Skill"が含まれていることを確認します。

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

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

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

関連ドキュメント

スキルガイド

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

SDKリソース

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

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
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # Enable Skill tool
    )

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

asyncio.run(main())

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

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

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

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