Plugins в SDK

Загружайте пользовательские plugins для расширения Claude Code с помощью команд, agents, skills и hooks через Agent SDK

Plugins позволяют расширить Claude Code пользовательской функциональностью, которая может быть общей для нескольких проектов. Через Agent SDK вы можете программно загружать plugins из локальных директорий, чтобы добавить пользовательские slash commands, agents, skills, hooks и MCP серверы к сеансам вашего agent.

Что такое plugins?

Plugins — это пакеты расширений Claude Code, которые могут включать:

Skills: Возможности, вызываемые моделью, которые Claude использует автономно (также могут быть вызваны с помощью /skill-name)
Agents: Специализированные подагенты для конкретных задач
Hooks: Обработчики событий, которые реагируют на использование инструментов и другие события
MCP серверы: Интеграции внешних инструментов через Model Context Protocol

Для полной информации о структуре plugin и способах создания plugins см. Plugins.

Загрузка plugins

Загружайте plugins, предоставляя пути их локальной файловой системы в конфигурации параметров. Поле type должно быть "local", это единственное значение, которое принимает SDK. Чтобы использовать plugin, распространяемый через marketplace или удаленный репозиторий, сначала загрузите его и предоставьте путь локальной директории. SDK поддерживает загрузку нескольких plugins из разных мест.

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 могут быть:

Относительные пути: Разрешаются относительно вашей текущей рабочей директории (например, "./plugins/my-plugin")
Абсолютные пути: Полные пути файловой системы (например, "/home/user/plugins/my-plugin")

Проверка установки plugin

Когда plugins загружаются успешно, они появляются в системном сообщении инициализации. Вы можете проверить, что ваши plugins доступны:

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 skills

Skills из plugins автоматически получают пространство имен с именем plugin, чтобы избежать конфликтов. При вызове как slash commands формат — 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())

Полный пример

Вот полный пример, демонстрирующий загрузку и использование plugin:

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)

Справочник структуры plugin

Директория 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 — Полное руководство по разработке plugin
Plugins reference — Технические спецификации и схемы

Распространенные варианты использования

Разработка и тестирование

Загружайте plugins во время разработки без их глобальной установки:

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

Расширения, специфичные для проекта

Включайте plugins в репозиторий вашего проекта для согласованности в команде:

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

Несколько источников plugins

Объединяйте plugins из разных мест:

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

Troubleshooting

Plugin не загружается

Если ваш plugin не появляется в сообщении инициализации:

Проверьте путь: Убедитесь, что путь указывает на корневую директорию plugin (содержащую .claude-plugin/)
Проверьте plugin.json: Убедитесь, что ваш файл манифеста имеет корректный синтаксис JSON
Проверьте разрешения файлов: Убедитесь, что директория plugin доступна для чтения

Skills не появляются

Если plugin skills не работают:

Используйте пространство имен: Plugin skills требуют формат plugin-name:skill-name при вызове как slash commands
Проверьте сообщение инициализации: Убедитесь, что skill появляется в slash_commands с правильным пространством имен
Проверьте файлы skill: Убедитесь, что каждый skill имеет файл SKILL.md в собственной поддиректории под skills/ (например, skills/my-skill/SKILL.md)

Проблемы с разрешением пути

Если относительные пути не работают:

Проверьте рабочую директорию: Относительные пути разрешаются из вашей текущей рабочей директории
Используйте абсолютные пути: Для надежности рассмотрите использование абсолютных путей
Нормализуйте пути: Используйте утилиты пути для правильного построения путей

См. также

Plugins — Полное руководство по разработке plugin
Plugins reference — Технические спецификации
Slash Commands — Использование slash commands в SDK
Subagents — Работа со специализированными agents
Skills — Использование Agent Skills

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

Plugins в SDK

Что такое plugins?

Загрузка plugins

Спецификации путей

Проверка установки plugin

Использование plugin skills

Полный пример

Справочник структуры plugin

Распространенные варианты использования

Разработка и тестирование

Расширения, специфичные для проекта

Несколько источников plugins

Troubleshooting

Plugin не загружается

Skills не появляются

Проблемы с разрешением пути

См. также