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

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

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

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

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

Команды

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

Агенты

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

---
description: Что специализирует этот агент
capabilities: ["task1", "task2", "task3"]
---

# Имя агента

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

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

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

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

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

Навыки

Плагины могут предоставлять Agent Skills, которые расширяют возможности Claude. Навыки вызываются моделью — Claude автономно решает, когда их использовать, на основе контекста задачи. Расположение: каталог skills/ в корне плагина Формат файла: каталоги, содержащие файлы SKILL.md с frontmatter Структура навыка:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (опционально)
│   └── scripts/ (опционально)
└── code-reviewer/
    └── SKILL.md

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

Навыки плагинов автоматически обнаруживаются при установке плагина
Claude автономно вызывает навыки на основе соответствия контексту задачи
Навыки могут включать вспомогательные файлы рядом с SKILL.md

Для формата SKILL.md и полного руководства по созданию навыков см.:

Хуки

Плагины могут предоставлять обработчики событий, которые автоматически реагируют на события 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": "Brief plugin description",
  "author": {
    "name": "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": ["keyword1", "keyword2"],
  "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	Краткое объяснение назначения плагина	`"Deployment automation tools"`
`author`	object	Информация об авторе	`{"name": "Dev Team", "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	Теги обнаружения	`["deployment", "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
├── skills/                   # Agent Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── 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/, skills/, hooks/) должны находиться в корне плагина, а не внутри .claude-plugin/.

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

Компонент	Расположение по умолчанию	Назначение
Манифест	`.claude-plugin/plugin.json`	Обязательный файл метаданных
Команды	`commands/`	Файлы markdown команд с косой чертой
Агенты	`agents/`	Файлы markdown подагентов
Навыки	`skills/`	Agent Skills с файлами SKILL.md
Хуки	`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/plugins) - Руководства и практическое использование
- [Маркетплейсы плагинов](/ru/plugin-marketplaces) - Создание и управление маркетплейсами
- [Команды с косой чертой](/ru/slash-commands) - Детали разработки команд
- [Подагенты](/ru/sub-agents) - Конфигурация и возможности агентов
- [Agent Skills](/ru/skills) - Расширение возможностей Claude
- [Хуки](/ru/hooks) - Обработка событий и автоматизация
- [MCP](/ru/mcp) - Интеграция внешних инструментов
- [Параметры](/ru/settings) - Параметры конфигурации для плагинов

Справка

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

​Команды

​Агенты

​Навыки

​Хуки

​Серверы MCP

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

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

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

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

​Поля пути компонента

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

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

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

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

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

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

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

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

​Справочник распределения и версионирования

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

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

Команды

Агенты

Навыки

Хуки

Серверы MCP

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

Полная схема

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

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

Поля пути компонента

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

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

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

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

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

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

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

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

Справочник распределения и версионирования

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