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

​
Что такое plugins?

Plugins — это пакеты расширений Claude Code, которые могут включать:
  • Skills: Возможности, вызываемые моделью, которые Claude использует автономно (также могут быть вызваны с помощью /skill-name)
  • Agents: Специализированные подагенты для конкретных задач
  • Hooks: Обработчики событий, которые реагируют на использование инструментов и другие события
  • MCP серверы: Интеграции внешних инструментов через Model Context Protocol
Директория commands/ — это устаревший формат. Используйте skills/ для новых plugins. Claude Code продолжает поддерживать оба формата для обратной совместимости.
Для полной информации о структуре 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
}

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

Пути plugins могут быть:
  • Относительные пути: Разрешаются относительно вашей текущей рабочей директории (например, "./plugins/my-plugin")
  • Абсолютные пути: Полные пути файловой системы (например, "/home/user/plugins/my-plugin")
Путь должен указывать на корневую директорию plugin: родительскую директорию skills/, agents/, hooks/, commands/ (устаревший), или .claude-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") {
    // Проверка загруженных plugins
    console.log("Plugins:", message.plugins);
    // Пример: [{ name: "my-plugin", path: "./my-plugin" }]

    // Plugin skills появляются с именем plugin в качестве префикса
    console.log("Skills:", message.skills);
    // Пример: ["my-plugin:greet"]

    // Plugin команды используют тот же префикс, и skills также появляются здесь
    console.log("Commands:", message.slash_commands);
    // Пример: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]
  }
}

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

Skills из plugins автоматически получают пространство имен с именем plugin, чтобы избежать конфликтов. Для прямого вызова отправьте /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);
  }
}
Если вы установили plugin через CLI (например, /plugin install my-plugin@marketplace), вы все еще можете использовать его в SDK, предоставив путь его установки. Проверьте ~/.claude/plugins/ для plugins, установленных через CLI.

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

Вот полный пример, демонстрирующий загрузку и использование 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 skills:", message.skills);
      console.log("Available commands:", message.slash_commands);
    }

    if (message.type === "assistant") {
      console.log("Assistant:", message.message.content);
    }
  }
}

runWithPlugin().catch(console.error);

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

Директория plugin обычно содержит файл манифеста .claude-plugin/plugin.json. Манифест является опциональным. Когда он опущен, Claude Code автоматически обнаруживает компоненты из структуры директории. Директория может включать: 
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Манифест plugin (опциональный, компоненты автоматически обнаруживаются без него)
├── skills/                   # Agent Skills (вызываются автономно или через /skill-name)
│   └── my-skill/
│       └── SKILL.md
├── commands/                 # Legacy: используйте skills/ вместо этого
│   └── custom-cmd.md
├── agents/                   # Пользовательские агенты
│   └── specialist.md
├── hooks/                    # Обработчики событий
│   └── hooks.json
└── .mcp.json                # Определения MCP server
Для подробной информации о создании 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 не появляется в сообщении инициализации:
  1. Проверьте путь: убедитесь, что путь указывает на корневую директорию plugin, родительскую директорию для skills/, agents/, hooks/, commands/ (устаревшее), или .claude-plugin/
  2. Проверьте plugin.json: если ваш plugin включает манифест, убедитесь, что он имеет корректный синтаксис JSON
  3. Проверьте разрешения файлов: убедитесь, что директория plugin доступна для чтения

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

Если skills plugin не работают:
  1. Используйте пространство имен: вызывайте skills plugin как /plugin-name:skill-name
  2. Проверьте сообщение инициализации: убедитесь, что skill появляется в списке skills с правильным пространством имен
  3. Проверьте файлы skill: убедитесь, что каждый skill имеет файл SKILL.md в собственной поддиректории под skills/, например skills/my-skill/SKILL.md

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

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

​
См. также

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