SDK のプラグイン

Agent SDK を通じてカスタムプラグインを読み込み、コマンド、エージェント、スキル、フックで Claude Code を拡張します

プラグインを使用すると、Claude Code をカスタム機能で拡張でき、プロジェクト全体で共有できます。Agent SDK を通じて、ローカルディレクトリからプログラムでプラグインを読み込み、カスタムスラッシュコマンド、エージェント、スキル、フック、MCP サーバーをエージェントセッションに追加できます。

プラグインとは何ですか？

プラグインは Claude Code 拡張機能のパッケージであり、以下を含めることができます：

Skills: Claude が自律的に使用するモデル呼び出し機能（/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: "./my-plugin" }]

// Check available commands from plugins
console.log("Commands:", message.slash_commands);
// Example: ["/help", "/compact", "my-plugin:custom-command"]
}
}

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": "./my-plugin"}]

# Check available commands from plugins
print("Commands:", message.data.get("slash_commands"))
# Example: ["/help", "/compact", "my-plugin:custom-command"]


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="/demo-plugin:greet",  # Use plugin skill with namespace
options=ClaudeAgentOptions(
plugins=[{"type": "local", "path": "./plugins/demo-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 * as path from "path";

async function runWithPlugin() {
const pluginPath = path.join(__dirname, "plugins", "my-plugin");

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

from pathlib import Path
import anyio
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" / "demo-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 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__":
anyio.run(run_with_plugin)

プラグイン構造リファレンス

プラグインディレクトリには .claude-plugin/plugin.json マニフェストファイルが含まれている必要があります。オプションで以下を含めることができます：

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── skills/                   # Agent Skills (invoked autonomously or via /skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Legacy: use skills/ instead
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

プラグイン作成の詳細については、以下を参照してください：

Plugins - プラグイン開発の完全ガイド
Plugins reference - 技術仕様とスキーマ

一般的なユースケース

開発とテスト

グローバルにインストールせずに開発中にプラグインを読み込みます：

plugins: [{ type: "local", path: "./dev-plugins/my-plugin" }];

プロジェクト固有の拡張機能

チーム全体の一貫性のためにプラグインをプロジェクトリポジトリに含めます：

plugins: [{ type: "local", path: "./project-plugins/team-workflows" }];

複数のプラグインソース

異なる場所からプラグインを組み合わせます：

plugins: [
  { type: "local", path: "./local-plugin" },
  { type: "local", path: "~/.claude/custom-plugins/shared-plugin" }
];

トラブルシューティング

プラグインが読み込まれない

プラグインが初期化メッセージに表示されない場合：

パスを確認する: パスがプラグインルートディレクトリ（.claude-plugin/ を含む）を指していることを確認してください
plugin.json を検証する: マニフェストファイルが有効な JSON 構文を持っていることを確認してください
ファイルパーミッションを確認する: プラグインディレクトリが読み取り可能であることを確認してください

スキルが表示されない

プラグインスキルが機能しない場合：

名前空間を使用する: プラグインスキルはスラッシュコマンドとして呼び出される場合、plugin-name:skill-name 形式が必要です
初期化メッセージを確認する: スキルが正しい名前空間で slash_commands に表示されることを確認してください
スキルファイルを検証する: 各スキルが skills/ の下の独自のサブディレクトリに SKILL.md ファイルを持っていることを確認してください（例：skills/my-skill/SKILL.md）

パス解決の問題

相対パスが機能しない場合：

作業ディレクトリを確認する: 相対パスは現在の作業ディレクトリから解決されます
絶対パスを使用する: 信頼性のために、絶対パスの使用を検討してください
パスを正規化する: パスユーティリティを使用してパスを正しく構築してください

agent-sdk/plugins.md +16 −10

46 46

47 ```python Python theme={null}47 ```python Python theme={null}

48 import asyncio48 import asyncio

~~49 from claude_agent_sdk import query~~49 from claude_agent_sdk import query, ClaudeAgentOptions

50 50

51 51

52 async def main():52 async def main():

53 async for message in query(53 async for message in query(

54 prompt="Hello",54 prompt="Hello",

~~55 options={~~55 options=ClaudeAgentOptions(

~~56 "plugins": [~~56 plugins=[

57 {"type": "local", "path": "./my-plugin"},57 {"type": "local", "path": "./my-plugin"},

58 {"type": "local", "path": "/absolute/path/to/another-plugin"},58 {"type": "local", "path": "/absolute/path/to/another-plugin"},

59 ]59 ]

~~60 },~~60 ),

61 ):61 ):

62 # Plugin commands, agents, and other features are now available62 # Plugin commands, agents, and other features are now available

63 pass63 pass

106 106

107 ```python Python theme={null}107 ```python Python theme={null}

108 import asyncio108 import asyncio

109 from claude_agent_sdk import query109 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage

110 110

111 111

112 async def main():112 async def main():

113 async for message in query(113 async for message in query(

114 prompt="Hello", options={"plugins": [{"type": "local", "path": "./my-plugin"}]}114 prompt="Hello",

115 options=ClaudeAgentOptions(

116 plugins=[{"type": "local", "path": "./my-plugin"}]

117 ),

115 ):118 ):

116 if message.type == "system" and message.subtype == "init":119 if isinstance(message, SystemMessage) and message.subtype == "init":

117 # Check loaded plugins120 # Check loaded plugins

118 print("Plugins:", message.data.get("plugins"))121 print("Plugins:", message.data.get("plugins"))

119 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]122 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]

151 154

152 ```python Python theme={null}155 ```python Python theme={null}

153 import asyncio156 import asyncio

154 from claude_agent_sdk import query, AssistantMessage, TextBlock157 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

155 158

156 159

157 async def main():160 async def main():

158 # Load a plugin with a custom /greet skill161 # Load a plugin with a custom /greet skill

159 async for message in query(162 async for message in query(

160 prompt="/demo-plugin:greet", # Use plugin skill with namespace163 prompt="/demo-plugin:greet", # Use plugin skill with namespace

161 options={"plugins": [{"type": "local", "path": "./plugins/demo-plugin"}]},164 options=ClaudeAgentOptions(

165 plugins=[{"type": "local", "path": "./plugins/demo-plugin"}]

166 ),

162 ):167 ):

163 # Claude executes the custom greeting skill from the plugin168 # Claude executes the custom greeting skill from the plugin

164 if isinstance(message, AssistantMessage):169 if isinstance(message, AssistantMessage):

219 from claude_agent_sdk import (224 from claude_agent_sdk import (

220 AssistantMessage,225 AssistantMessage,

221 ClaudeAgentOptions,226 ClaudeAgentOptions,

227 SystemMessage,

222 TextBlock,228 TextBlock,

223 query,229 query,

224 )230 )

238 async for message in query(244 async for message in query(

239 prompt="What custom commands do you have available?", options=options245 prompt="What custom commands do you have available?", options=options

240 ):246 ):

241 if message.type == "system" and message.subtype == "init":247 if isinstance(message, SystemMessage) and message.subtype == "init":

242 print(f"Loaded plugins: {message.data.get('plugins')}")248 print(f"Loaded plugins: {message.data.get('plugins')}")

243 print(f"Available commands: {message.data.get('slash_commands')}")249 print(f"Available commands: {message.data.get('slash_commands')}")

244 250

agent-sdk/plugins.md 2026-05-14 17:02 UTC to 2026-05-15 22:58 UTC

SDK のプラグイン

プラグインとは何ですか？

プラグインの読み込み

パス指定

プラグインインストールの確認

プラグインスキルの使用

完全な例

プラグイン構造リファレンス

一般的なユースケース

開発とテスト

プロジェクト固有の拡張機能

複数のプラグインソース

トラブルシューティング

プラグインが読み込まれない

スキルが表示されない

パス解決の問題

関連項目

agent-sdk/plugins.md +16 −10