SDKにおけるAgent Skills

概要

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

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

SkillsがSDKでどのように機能するか

Claude Agent SDKを使用する場合、Skillsは：

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

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

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

SDKでのSkillsの使用

SDKでSkillsを使用するには、以下が必要です：

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

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

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

SKILL.mdの構造、マルチファイルSkills、および例を含むSkills作成の完全なガイダンスについては、以下を参照してください：

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

ツールの制限

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

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

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

最初の例のimport文は、以下のコードスニペットでも使用されていることを前提としています。

利用可能なSkillsの確認

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

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # ファイルシステムからSkillsを読み込み
    allowed_tools=["Skill"]
)

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

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

Skillsのテスト

Skillsの説明に一致する質問をしてSkillsをテストします：

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

トラブルシューティング

Skillsが見つからない

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

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

# 正しい - Skillsが読み込まれます
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Skillsの読み込みに必要
    allowed_tools=["Skill"]
)

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

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

# cwdが.claude/skills/を含むディレクトリを指していることを確認
options = ClaudeAgentOptions(
    cwd="/path/to/project",  # .claude/skills/を含む必要があります
    setting_sources=["user", "project"],  # Skillsの読み込みに必要
    allowed_tools=["Skill"]
)

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

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

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

# 個人Skillsを確認
ls ~/.claude/skills/*/SKILL.md

Skillが使用されない

Skillツールが有効になっていることを確認: allowedToolsに"Skill"が含まれていることを確認してください。

説明を確認: 説明が具体的で関連するキーワードが含まれていることを確認してください。効果的な説明の書き方については、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ドキュメント

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        cwd="/path/to/project",  # .claude/skills/を含むプロジェクト
        setting_sources=["user", "project"],  # ファイルシステムからSkillsを読み込み
        allowed_tools=["Skill", "Read", "Write", "Bash"]  # Skillツールを有効化
    )

    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"],  # ファイルシステムからSkillsを読み込み
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # 制限されたツールセット
)

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

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # ファイルシステムからSkillsを読み込み
    allowed_tools=["Skill", "Read", "Bash"]
)

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