Плагины в SDK

Плагины позволяют расширить Claude Code пользовательской функциональностью, которая может быть общей для нескольких проектов. Через Agent SDK вы можете программно загружать плагины из локальных директорий, чтобы добавить пользовательские слэш-команды, агентов, навыки, хуки и MCP серверы в сеансы вашего агента.

Что такое плагины?

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

• Команды: Пользовательские слэш-команды
• Агенты: Специализированные подагенты для конкретных задач
• Навыки: Возможности, вызываемые моделью, которые Claude использует автономно
• Хуки: Обработчики событий, которые реагируют на использование инструментов и другие события
• MCP серверы: Интеграции внешних инструментов через Model Context Protocol

Полную информацию о структуре плагина и способах создания плагинов см. в разделе Плагины.

Загрузка плагинов

Загружайте плагины, указав пути их локальной файловой системы в конфигурации параметров. 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

async def main():
    async for message in 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
        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"]
  }
}

Использование команд плагина

Команды из плагинов автоматически получают пространство имён с именем плагина, чтобы избежать конфликтов. Формат: plugin-name:command-name.

import { query } from "@anthropic-ai/claude-agent-sdk";

// Load a plugin with a custom /greet command
for await (const message of query({
  prompt: "/my-plugin:greet",  // Use plugin command with namespace
  options: {
    plugins: [{ type: "local", path: "./my-plugin" }]
  }
})) {
  // Claude executes the custom greeting command from the plugin
  if (message.type === "assistant") {
    console.log(message.content);
  }
}

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

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

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.content);
    }
  }
}

runWithPlugin().catch(console.error);

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

Директория плагина должна содержать файл манифеста .claude-plugin/plugin.json. Она может опционально включать:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── commands/                 # Custom slash commands
│   └── custom-cmd.md
├── agents/                   # Custom agents
│   └── specialist.md
├── skills/                   # Agent Skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # Event handlers
│   └── hooks.json
└── .mcp.json                # MCP server definitions

Для подробной информации о создании плагинов см.:

• Плагины - Полное руководство по разработке плагинов
• Справочник плагинов - Технические спецификации и схемы

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

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

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

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" }
]

Устранение неполадок

Плагин не загружается

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

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

Команды недоступны

Если команды плагина не работают:

1. Используйте пространство имён: Команды плагина требуют формат plugin-name:command-name
2. Проверьте сообщение инициализации: Убедитесь, что команда появляется в slash_commands с правильным пространством имён
3. Проверьте файлы команд: Убедитесь, что файлы markdown команд находятся в директории commands/

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

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

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

См. также

• Плагины - Полное руководство по разработке плагинов
• Справочник плагинов - Технические спецификации
• Слэш-команды - Использование слэш-команд в SDK
• Подагенты - Работа со специализированными агентами
• Навыки - Использование Agent Skills