Справочник по плагинам

Для практических руководств и практического использования см. Плагины. Для управления плагинами в командах и сообществах см. Маркетплейсы плагинов.

Этот справочник предоставляет полные технические спецификации для системы плагинов Claude Code, включая схемы компонентов, команды CLI и инструменты разработки.

Справочник по компонентам плагинов

Этот раздел документирует четыре типа компонентов, которые могут предоставлять плагины.

Команды

Плагины добавляют пользовательские слэш-команды, которые бесшовно интегрируются с командной системой Claude Code. Расположение: директория commands/ в корне плагина Формат файла: файлы Markdown с frontmatter Для полных деталей о структуре команд плагинов, паттернах вызова и функциях см. Команды плагинов.

Агенты

Плагины могут предоставлять специализированных субагентов для конкретных задач, которых Claude может вызывать автоматически при необходимости. Расположение: директория agents/ в корне плагина Формат файла: файлы Markdown, описывающие возможности агента Структура агента:

---
description: В чем специализируется этот агент
capabilities: ["задача1", "задача2", "задача3"]
---

# Имя агента

Подробное описание роли агента, экспертизы и когда Claude должен его вызывать.

## Возможности
- Конкретная задача, в которой агент превосходит
- Другая специализированная возможность
- Когда использовать этого агента вместо других

## Контекст и примеры
Предоставьте примеры того, когда этот агент должен использоваться и какие проблемы он решает.

Точки интеграции:

Агенты появляются в интерфейсе /agents
Claude может вызывать агентов автоматически на основе контекста задачи
Агенты могут быть вызваны пользователями вручную
Агенты плагинов работают вместе со встроенными агентами Claude

Хуки

Плагины могут предоставлять обработчики событий, которые автоматически реагируют на события Claude Code. Расположение: hooks/hooks.json в корне плагина или встроенно в plugin.json Формат: конфигурация JSON с сопоставителями событий и действиями Конфигурация хука:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

Доступные события:

PreToolUse: Перед использованием Claude любого инструмента
PostToolUse: После использования Claude любого инструмента
UserPromptSubmit: Когда пользователь отправляет запрос
Notification: Когда Claude Code отправляет уведомления
Stop: Когда Claude пытается остановиться
SubagentStop: Когда субагент пытается остановиться
SessionStart: В начале сессий
SessionEnd: В конце сессий
PreCompact: Перед сжатием истории разговора

Типы хуков:

command: Выполнение команд оболочки или скриптов
validation: Проверка содержимого файлов или состояния проекта
notification: Отправка предупреждений или обновлений статуса

MCP серверы

Плагины могут объединять серверы Model Context Protocol (MCP) для подключения Claude Code к внешним инструментам и сервисам. Расположение: .mcp.json в корне плагина или встроенно в plugin.json Формат: стандартная конфигурация MCP сервера Конфигурация MCP сервера:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

Поведение интеграции:

MCP серверы плагинов запускаются автоматически при включении плагина
Серверы появляются как стандартные MCP инструменты в наборе инструментов Claude
Возможности сервера бесшовно интегрируются с существующими инструментами Claude
Серверы плагинов могут быть настроены независимо от пользовательских MCP серверов

Схема манифеста плагина

Файл plugin.json определяет метаданные и конфигурацию вашего плагина. Этот раздел документирует все поддерживаемые поля и опции.

Полная схема

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Краткое описание плагина",
  "author": {
    "name": "Имя автора",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["ключевое_слово1", "ключевое_слово2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json"
}

Обязательные поля

Поле	Тип	Описание	Пример
`name`	string	Уникальный идентификатор (kebab-case, без пробелов)	`"deployment-tools"`

Поля метаданных

Поле	Тип	Описание	Пример
`version`	string	Семантическая версия	`"2.1.0"`
`description`	string	Краткое объяснение назначения плагина	`"Инструменты автоматизации развертывания"`
`author`	object	Информация об авторе	`{"name": "Команда разработчиков", "email": "[email protected]"}`
`homepage`	string	URL документации	`"https://docs.example.com"`
`repository`	string	URL исходного кода	`"https://github.com/user/plugin"`
`license`	string	Идентификатор лицензии	`"MIT"`, `"Apache-2.0"`
`keywords`	array	Теги для поиска	`["развертывание", "ci-cd"]`

Поля путей компонентов

Поле	Тип	Описание	Пример
`commands`	string\|array	Дополнительные файлы/директории команд	`"./custom/cmd.md"` или `["./cmd1.md"]`
`agents`	string\|array	Дополнительные файлы агентов	`"./custom/agents/"`
`hooks`	string\|object	Путь к конфигурации хуков или встроенная конфигурация	`"./hooks.json"`
`mcpServers`	string\|object	Путь к конфигурации MCP или встроенная конфигурация	`"./mcp.json"`

Правила поведения путей

Важно: Пользовательские пути дополняют директории по умолчанию - они их не заменяют.

Если существует commands/, она загружается в дополнение к пользовательским путям команд
Все пути должны быть относительными к корню плагина и начинаться с ./
Команды из пользовательских путей используют те же правила именования и пространства имен
Несколько путей могут быть указаны как массивы для гибкости

Примеры путей:

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

Переменные окружения

${CLAUDE_PLUGIN_ROOT}: Содержит абсолютный путь к директории вашего плагина. Используйте это в хуках, MCP серверах и скриптах для обеспечения правильных путей независимо от места установки.

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

Структура директории плагина

Стандартная структура плагина

Полный плагин следует этой структуре:

enterprise-plugin/
├── .claude-plugin/           # Директория метаданных
│   └── plugin.json          # Обязательно: манифест плагина
├── commands/                 # Расположение команд по умолчанию
│   ├── status.md
│   └──  logs.md
├── agents/                   # Расположение агентов по умолчанию
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── hooks/                    # Конфигурации хуков
│   ├── hooks.json           # Основная конфигурация хуков
│   └── security-hooks.json  # Дополнительные хуки
├── .mcp.json                # Определения MCP серверов
├── scripts/                 # Скрипты хуков и утилит
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Файл лицензии
└── CHANGELOG.md             # История версий

Директория .claude-plugin/ содержит файл plugin.json. Все остальные директории (commands/, agents/, hooks/) должны быть в корне плагина, а не внутри .claude-plugin/.

Справочник по расположению файлов

Компонент	Расположение по умолчанию	Назначение
Манифест	`.claude-plugin/plugin.json`	Обязательный файл метаданных
Команды	`commands/`	Файлы markdown слэш-команд
Агенты	`agents/`	Файлы markdown субагентов
Хуки	`hooks/hooks.json`	Конфигурация хуков
MCP серверы	`.mcp.json`	Определения MCP серверов

Инструменты отладки и разработки

Команды отладки

Используйте claude --debug для просмотра деталей загрузки плагинов:

claude --debug

Это показывает:

Какие плагины загружаются
Любые ошибки в манифестах плагинов
Регистрацию команд, агентов и хуков
Инициализацию MCP серверов

Распространенные проблемы

Проблема	Причина	Решение
Плагин не загружается	Недействительный `plugin.json`	Проверьте синтаксис JSON
Команды не появляются	Неправильная структура директорий	Убедитесь, что `commands/` в корне, а не в `.claude-plugin/`
Хуки не срабатывают	Скрипт не исполняемый	Выполните `chmod +x script.sh`
MCP сервер не работает	Отсутствует `${CLAUDE_PLUGIN_ROOT}`	Используйте переменную для всех путей плагина
Ошибки путей	Используются абсолютные пути	Все пути должны быть относительными и начинаться с `./`

Справочник по распространению и версионированию

Управление версиями

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


## См. также

- [Плагины](/ru/docs/claude-code/plugins) - Руководства и практическое использование
- [Маркетплейсы плагинов](/ru/docs/claude-code/plugin-marketplaces) - Создание и управление маркетплейсами
- [Слэш-команды](/ru/docs/claude-code/slash-commands) - Детали разработки команд
- [Субагенты](/ru/docs/claude-code/sub-agents) - Конфигурация и возможности агентов
- [Хуки](/ru/docs/claude-code/hooks) - Обработка событий и автоматизация
- [MCP](/ru/docs/claude-code/mcp) - Интеграция внешних инструментов
- [Настройки](/ru/docs/claude-code/settings) - Опции конфигурации для плагинов

Начало работы

Создавайте с Claude Code

Claude Code SDK

Развертывание

Администрирование

Конфигурация

Справочник

Ресурсы

Справочник по плагинам

Справочник по компонентам плагинов

Команды

Агенты

Хуки

MCP серверы

Схема манифеста плагина

Полная схема

Обязательные поля

Поля метаданных

Поля путей компонентов

Правила поведения путей

Переменные окружения

Структура директории плагина

Стандартная структура плагина

Справочник по расположению файлов

Инструменты отладки и разработки

Команды отладки

Распространенные проблемы

Справочник по распространению и версионированию

Управление версиями

Начало работы

Создавайте с Claude Code

Claude Code SDK

Развертывание

Администрирование

Конфигурация

Справочник

Ресурсы

​Справочник по компонентам плагинов

​Команды

​Агенты

​Хуки

​MCP серверы

​Схема манифеста плагина

​Полная схема

​Обязательные поля

​Поля метаданных

​Поля путей компонентов

​Правила поведения путей

​Переменные окружения

​Структура директории плагина

​Стандартная структура плагина

​Справочник по расположению файлов

​Инструменты отладки и разработки

​Команды отладки

​Распространенные проблемы

​Справочник по распространению и версионированию

​Управление версиями

Справочник по компонентам плагинов

Команды

Агенты

Хуки

MCP серверы

Схема манифеста плагина

Полная схема

Обязательные поля

Поля метаданных

Поля путей компонентов

Правила поведения путей

Переменные окружения

Структура директории плагина

Стандартная структура плагина

Справочник по расположению файлов

Инструменты отладки и разработки

Команды отладки

Распространенные проблемы

Справочник по распространению и версионированию

Управление версиями