SDK のプラグイン
Agent SDK を通じてカスタムプラグインを読み込み、スキル、エージェント、フック、MCP サーバーで Claude Code を拡張します
プラグインを使用すると、Claude Code をカスタム機能で拡張でき、プロジェクト全体で共有できます。Agent SDK を通じて、ローカルディレクトリからプログラムでプラグインを読み込み、エージェントセッションに機能を追加できます。プラグインには以下を含めることができます：
- Skills: Claude が関連する場合に自律的に呼び出す機能。
/plugin-name:skill-nameでプラグインスキルを直接呼び出すこともできます。 - Agents: 特定のタスク用の専門的なサブエージェント
- Hooks: ツール使用およびその他のイベントに応答するイベントハンドラー
- MCP servers: Model Context Protocol 経由の外部ツール統合
プラグイン構造とプラグインの作成方法に関する完全な情報については、Plugins を参照してください。
プラグインの読み込み
オプション設定でローカルファイルシステムパスを指定してプラグインを読み込みます。type フィールドは "local" である必要があります。これは SDK が受け入れる唯一の値です。SDK は複数の場所から複数のプラグインを読み込むことをサポートしています。
マーケットプレイスまたはリモートリポジトリを通じて配布されているプラグインを使用するには、まずダウンロードしてローカルディレクトリパスを指定してください。プラグインが必要とするディレクトリレイアウトについては、以下のプラグイン構造リファレンスを参照してください。
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Hello",
options: {
plugins: [
{ type: "local", path: "./my-plugin" },
{ type: "local", path: "/absolute/path/to/another-plugin" }
]
}
})) {
// Plugin commands, agents, and other features are now available
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
plugins=[
{"type": "local", "path": "./my-plugin"},
{"type": "local", "path": "/absolute/path/to/another-plugin"},
]
),
):
# Plugin commands, agents, and other features are now available
pass
asyncio.run(main())
パス指定
プラグインパスは以下のいずれかです：
- 相対パス: 現在の作業ディレクトリを基準に解決されます（例：
"./plugins/my-plugin"） - 絶対パス: 完全なファイルシステムパス（例：
"/home/user/plugins/my-plugin"）
プラグインインストールの確認
プラグインが正常に読み込まれると、システム初期化メッセージに表示されます。プラグインが利用可能であることを確認できます：
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Hello",
options: {
plugins: [{ type: "local", path: "./my-plugin" }]
}
})) {
if (message.type === "system" && message.subtype === "init") {
// Check loaded plugins
console.log("Plugins:", message.plugins);
// Example: [{ name: "my-plugin", path: "/absolute/path/to/my-plugin" }]
// Plugin skills appear with the plugin name as a prefix
console.log("Skills:", message.skills);
// Example: ["my-plugin:greet"]
// Plugin commands use the same prefix, and skills appear here too
console.log("Commands:", message.slash_commands);
// Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage
async def main():
async for message in query(
prompt="Hello",
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./my-plugin"}]
),
):
if isinstance(message, SystemMessage) and message.subtype == "init":
# Check loaded plugins
print("Plugins:", message.data.get("plugins"))
# Example: [{"name": "my-plugin", "path": "/absolute/path/to/my-plugin"}]
# Plugin skills appear with the plugin name as a prefix
print("Skills:", message.data.get("skills"))
# Example: ["my-plugin:greet"]
# Plugin commands use the same prefix, and skills appear here too
print("Commands:", message.data.get("slash_commands"))
# Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
asyncio.run(main())
プラグインスキルの使用
プラグインのスキルは競合を避けるためにプラグイン名で自動的に名前空間化されます。直接呼び出すには、プロンプトとして /plugin-name:skill-name を送信してください。
import { query } from "@anthropic-ai/claude-agent-sdk";
// Load a plugin with a custom /greet skill
for await (const message of query({
prompt: "/my-plugin:greet", // Use plugin skill with namespace
options: {
plugins: [{ type: "local", path: "./my-plugin" }]
}
})) {
// Claude executes the custom greeting skill from the plugin
if (message.type === "assistant") {
console.log(message.message.content);
}
}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock
async def main():
# Load a plugin with a custom /greet skill
async for message in query(
prompt="/my-plugin:greet", # Use plugin skill with namespace
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./my-plugin"}]
),
):
# Claude executes the custom greeting skill from the plugin
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"Claude: {block.text}")
asyncio.run(main())
完全な例
プラグインの読み込みと使用を示す完全な例を以下に示します：
import { query } from "@anthropic-ai/claude-agent-sdk";
import { fileURLToPath } from "node:url";
async function runWithPlugin() {
const pluginPath = fileURLToPath(new URL("./plugins/my-plugin", import.meta.url));
console.log("Loading plugin from:", pluginPath);
for await (const message of query({
prompt: "What custom commands do you have available?",
options: {
plugins: [{ type: "local", path: pluginPath }],
maxTurns: 3
}
})) {
if (message.type === "system" && message.subtype === "init") {
console.log("Loaded plugins:", message.plugins);
console.log("Available skills:", message.skills);
console.log("Available commands:", message.slash_commands);
}
if (message.type === "assistant") {
console.log("Assistant:", message.message.content);
}
}
}
runWithPlugin().catch(console.error);
#!/usr/bin/env python3
"""Example demonstrating how to use plugins with the Agent SDK."""
import asyncio
from pathlib import Path
from claude_agent_sdk import (
AssistantMessage,
ClaudeAgentOptions,
SystemMessage,
TextBlock,
query,
)
async def run_with_plugin():
"""Example using a custom plugin."""
plugin_path = Path(__file__).parent / "plugins" / "my-plugin"
print(f"Loading plugin from: {plugin_path}")
options = ClaudeAgentOptions(
plugins=[{"type": "local", "path": str(plugin_path)}],
max_turns=3,
)
async for message in query(
prompt="What custom commands do you have available?", options=options
):
if isinstance(message, SystemMessage) and message.subtype == "init":
print(f"Loaded plugins: {message.data.get('plugins')}")
print(f"Available skills: {message.data.get('skills')}")
print(f"Available commands: {message.data.get('slash_commands')}")
if isinstance(message, AssistantMessage):
for block in message.content:
if isinstance(block, TextBlock):
print(f"Assistant: {block.text}")
if __name__ == "__main__":
asyncio.run(run_with_plugin())
プラグイン構造リファレンス
プラグインディレクトリには通常、.claude-plugin/plugin.json マニフェストファイルが含まれています。マニフェストはオプションです。省略した場合、Claude Code はディレクトリレイアウトからコンポーネントを自動検出します。ディレクトリには以下を含めることができます：
my-plugin/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (optional, components auto-discovered without it)
├── skills/ # Agent Skills (invoked autonomously or via /plugin-name:skill-name)
│ └── my-skill/
│ └── SKILL.md
├── commands/ # Skills as flat .md files
│ └── custom-cmd.md
├── agents/ # Custom agents
│ └── specialist.md
├── hooks/ # Event handlers
│ └── hooks.json
└── .mcp.json # MCP server definitions
複数のプラグインソース
異なる場所からプラグインを組み合わせます：
import * as os from "node:os";
import * as path from "node:path";
plugins: [
{ type: "local", path: "./local-plugin" },
{
type: "local",
path: path.join(os.homedir(), ".claude", "custom-plugins", "shared-plugin")
}
];
トラブルシューティング
プラグインが読み込まれない
プラグインが初期化メッセージに表示されない場合：
- パスを確認する: パスがプラグインルートディレクトリ（
skills/、agents/、hooks/、commands/、または.claude-plugin/の親）を指していることを確認してください - plugin.json を検証する: プラグインにマニフェストが含まれている場合、有効な JSON 構文を持っていることを確認してください
- ファイルパーミッションを確認する: プラグインディレクトリが読み取り可能であることを確認してください
- ディレクトリが存在することを確認する: SDK は存在しないパスをスキップし、プラグインは初期化メッセージの
pluginsリストに表示されません
スキルが表示されない
プラグインスキルが機能しない場合：
- 名前空間を使用する:
/plugin-name:skill-nameとしてプラグインスキルを呼び出してください - 初期化メッセージを確認する: スキルが正しい名前空間で
skillsリストに表示されることを確認してください - スキルファイルを検証する: 各スキルが
skills/の下の独自のサブディレクトリにSKILL.mdファイルを持っていることを確認してください（例：skills/my-skill/SKILL.md）
関連項目
- Plugins - プラグイン開発の完全ガイド
- Plugins reference - 技術仕様
- Commands - SDK でのコマンドのディスパッチ
- Subagents - 専門的なエージェントの操作
- Skills - Agent Skills の使用