Содержание

В Claude Code набор навыков, субагентов, хуков и конфигурации MCP называется плагином. Каталог, перечисляющий названия плагинов и источники их загрузки, — это маркетплейс. Вместе они позволяют повторно использовать процедуры в разных проектах или делиться единым набором расширений с командой.

В статье пройдём путь от установки готового плагина до создания навыка приветствия и его распространения через каталог. Помните о трёх различиях: (1) сам плагин и каталог его распространения находятся на разных уровнях; (2) регистрация каталога и установка плагина — разные операции; (3) успешная команда валидации не гарантирует правильной работы и безопасности. Порядок действий основан на официальном руководстве по созданию плагинов.

CLAUDE CODE · PLUGINS

Объединяйте функции и распространяйте их

— Выбирайте навыки, агентов, хуки и интеграции MCP из каталога

my-plugin/
.claude-plugin/plugin.json
skills/
agents/
hooks/
.mcp.json
commands/ …
/plugin marketplace add owner/repo
↓
/plugin install name@market
↓
✓ Проверьте результат установки, область и включение

Плагин — это набор функций, а маркетплейс — каталог для его распространения, например в Git-репозитории.
Зарегистрируйте каталог → установите отдельные плагины → проверьте нужные функции.
При создании своего решения проверяйте и плагин, и каталог перед распространением.

1. Что такое плагины Claude Code?

Плагин объединяет расширения Claude Code в каталог, которым можно делиться и пользоваться повторно. Необязательно включать все компоненты: плагин может состоять из одного навыка.

КомпонентРасположениеНазначение
Навыкиskills/<name>/SKILL.mdПроцедуры, выбираемые автоматически по описанию и настройкам либо через явный вызов пользователем (Подробнее о навыках)
Слеш-командыcommands/Прежний формат Markdown. Теперь они рассматриваются как навыки; для новых разработок рекомендуется skills/
Субагентыagents/Определения агентов с отдельными ролями. Проверяйте загрузку в разделе Custom Agents команды /context
Хукиhooks/hooks.jsonВыполняются по настроенным событиям и условиям, например PostToolUse
MCP-серверы.mcp.jsonПодключение к внешним инструментам и данным (MCP)
Манифест.claude-plugin/plugin.jsonНазвание, описание, версия и другие метаданные. Необязателен при использовании только стандартной структуры

Для личных процедур может хватить каталога .claude/skills/ в проекте. Плагины полезны, когда нужно распространять один набор в нескольких местах и управлять его обновлениями. Есть и расширения для LSP и мониторинга, но у них свои требования к среде и способу распространения. Начать с небольшого навыка проще: его легче проверить.

2. Структура плагина

Ниже показана стандартная структура отдельного плагина. Если нужен манифест, он располагается в .claude-plugin/plugin.json; каталоги skills/, agents/ и hooks/ находятся в корне самого плагина. Каталог распространения marketplace.json — отдельный файл. В примере ниже он находится в .claude-plugin/marketplace.json на уровне маркетплейса.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # метаданные этого плагина
├── skills/
│   └── code-review/SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/hooks.json
├── .mcp.json
└── README.md

Пример файла plugin.json. Если используется только стандартная структура каталогов, манифест можно полностью опустить. Если он есть, поле name обязательно, а описание и версия — нет.

{
  "name": "my-first-plugin",
  "description": "Учебный плагин приветствия",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

Поле name также задаёт пространство имён навыков: в этом примере вызов выглядит как /my-first-plugin:hello. При распространении с кэшированием через Git сначала учитывается версия из plugin.json, затем версия плагина в каталоге. Если нет ни одной, используется SHA коммита, определённого для источника. Если явно указанная версия не меняется, одного изменения кода недостаточно, чтобы плагин стал доступен для обновления. Прямая загрузка из локального каталога и источники типа command подчиняются другим правилам. Подробности — в документации по управлению версиями.

3. Работа с /plugin и маркетплейсами

Начните с /plugin. Откроется менеджер с вкладками Discover, Installed, Marketplaces и Errors. Основные команды:

# Добавить маркетплейс (каталог распространения)
/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace add ./my-marketplace              # локальный путь
/plugin marketplace add https://example.com/marketplace.json

# Выбрать область в интерфейсе, установить и проверить включение
/plugin install plugin-name@marketplace-name
/plugin enable  plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

# Установленные через маркетплейсы (фильтры --enabled / --disabled)
/plugin list
/plugin list --enabled

# При необходимости перезагрузить изменения и проверить результат
/reload-plugins

Добавление каталога само по себе не устанавливает плагины. После регистрации устанавливайте их по отдельности. Интерактивная команда /plugin install позволяет выбрать область действия на экране подробностей. Команда оболочки claude plugin install по умолчанию использует область user; для изменения укажите --scope.

После установки проверьте, что показывает результат: плагин активен, ожидает перезагрузки или не загрузился из-за ошибки. Перезагрузка может откладываться из-за влияния на кэш промпта. В сеансах без терминала изменения MCP в плагине иногда вступают в силу только в следующем сеансе. /plugin list охватывает только установки через маркетплейсы, а не всё, что поступает через синхронизацию или каталоги навыков. Проверьте условия установки и перезагрузки, а если MCP не подключается, обратитесь к разбору ошибок подключения MCP.

4. Что такое маркетплейс?

Маркетплейс — это каталог с файлом .claude-plugin/marketplace.json, перечисляющим плагины и их источники. Он распространяется через Git-репозиторий, локальный путь или размещённый в сети файл. Существуют официальный каталог и каталоги сообщества.

Официальный маркетплейс и каталог сообщества

• Официальный (claude-plugins-official): подборкой управляет Anthropic. Он регистрируется автоматически при первом интерактивном запуске, но предыдущее неинтерактивное использование, сетевые ограничения или политики организации могут этому помешать. Если каталог отсутствует, проверьте эти условия и выполните /plugin marketplace add anthropics/claude-plugins-official в среде, где это разрешено. Просматривайте плагины через Discover в /plugin или в официальном каталоге.

• Сообщество (claude-community): каталог заявок, прошедших автоматическую валидацию и проверку безопасности. Его репозиторий — anthropics/claude-plugins-community, поэтому добавляйте его командой /plugin marketplace add anthropics/claude-plugins-community. Для установки используйте /plugin install name@claude-community. Не путайте имя репозитория с зарегистрированным именем каталога.

Если не видно каталога, проверьте регистрацию; если отдельного плагина — его имя и источник. Для внутреннего каталога также важно, чтобы пользователи имели доступ и к репозиторию, и к самому плагину. При распространении JSON-файла по URL содержимое плагинов с относительными путями не загружается относительно этого URL.

5. Создание и распространение своего плагина

В примере создаётся один навык приветствия. Начните со следующей структуры. Внешний каталог .claude-plugin относится к каталогу распространения, внутренний — к отдельному плагину. Выполняйте команды из родительского каталога, содержащего my-marketplace.

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── my-first-plugin/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── hello/
                └── SKILL.md

(1) Сохраните JSON из предыдущего раздела во внутреннем файле my-marketplace/plugins/my-first-plugin/.claude-plugin/plugin.json. (2) Сохраните следующий текст в my-marketplace/plugins/my-first-plugin/skills/hello/SKILL.md. В примере указано disable-model-invocation: true, поэтому навык используется только при явном вызове.

---
name: hello
description: Коротко поприветствовать по имени
disable-model-invocation: true
---
Коротко поприветствуйте пользователя.
Если переданы аргументы, используйте указанное имя в приветствии.
Аргументы: $ARGUMENTS

(3) Запишите каталог во внешний файл my-marketplace/.claude-plugin/marketplace.json. Относительные пути source разрешаются относительно корня маркетплейса, а не каталога, содержащего marketplace.json.

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "description": "Учебный каталог для распространения навыка приветствия",
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./plugins/my-first-plugin",
      "description": "Навык короткого приветствия по имени"
    }
  ]
}

(4) Проверьте каталог и плагин по отдельности. Первая проверка охватывает схему каталога и plugin.json локальных записей, но не читает файлы каждого навыка или хука. Вторая охватывает также файлы стандартных каталогов отдельного плагина. Ни одна проверка не гарантирует правильного выполнения и безопасности.

claude plugin validate ./my-marketplace
claude plugin validate ./my-marketplace/plugins/my-first-plugin

# Загрузить отдельный плагин в этот сеанс для проверки
claude --plugin-dir ./my-marketplace/plugins/my-first-plugin

В открывшемся интерактивном сеансе выполните /my-first-plugin:hello Alex и убедитесь, что получено короткое приветствие с именем Alex. Проверка функции означает изучение результата и поиск нежелательных побочных действий, а не только наличие команды в интерфейсе. Если плагин не загружается, проверьте имена в обоих JSON-файлах, путь source, расположение и frontmatter файла SKILL.md.

(5) Чтобы проверить и установку через каталог, завершите предыдущий тестовый сеанс и запустите Claude Code без --plugin-dir. Следующие команды добавляют записи в вашу конфигурацию, поэтому выполняйте их в учебном проекте и выберите область установки.

/plugin marketplace add ./my-marketplace
/plugin install my-first-plugin@my-plugins
/my-first-plugin:hello Alex

(6) Для распространения опубликуйте содержимое my-marketplace в корне Git-репозитория, доступного пользователям для загрузки. Включите в коммит каталог plugins вместе с каталогом распространения. Пользователи добавят реальный owner/repo и установят тот же my-first-plugin@my-plugins. Эта структура с относительными путями работает при регистрации через Git или локальный каталог; её нельзя без изменений использовать с отдельным URL файла marketplace.json. Подробности — в руководстве по созданию, распространению и проверке каталогов.

Для распространения через собственный Git-репозиторий не нужна заявка на включение в официальный каталог. Если требуется также публикация в каталоге сообщества, индивидуальные авторы могут воспользоваться формой отправки в Console. Форма на claude.ai требует организации Team/Enterprise и административных прав. Заявка в каталог сообщества не равнозначна включению в официальный каталог, подборкой которого управляет Anthropic.

6. Области установки и безопасность

Области установки: user (все ваши проекты), project (общие настройки проекта) и local (только вы в этом проекте). Не путайте интерактивный выбор области с областью user по умолчанию в CLI оболочки. Управляемые настройки контролируются администраторами и ограничивают изменение конфигурации пользователями.

Команда может совместно использовать источники и состояние включения через extraKnownMarketplaces и enabledPlugins в .claude/settings.json. Однако записать общие настройки — не то же самое, что завершить установку на компьютерах всех участников. Каждый участник должен установить плагины из внешних источников. После подтверждения доверия проекту проверьте регистрацию каталога, права доступа и результаты установки в каждой среде.

⚠️ Безопасность: плагины могут исполнять произвольный код

В официальных рекомендациях по безопасности указано, что плагины могут запускать произвольный код с вашими правами. Публикации сообщества проходят автоматическую валидацию и проверку безопасности, но это не гарантирует ожидаемого поведения. Проверяйте издателя, навыки, хуки и включённые MCP-серверы. Организации могут ограничить источники каталогов параметром strictKnownMarketplaces в управляемых настройках; пустой массив запрещает источники маркетплейсов, включая официальный. Эта настройка не контролирует каждую сетевую или файловую операцию плагина. Для других путей, например синхронизации с claude.ai, предусмотрены отдельные настройки.

Итоги

Плагин — единица распространения расширений, маркетплейс — его каталог. Пользователь регистрирует каталог → устанавливает отдельные плагины → проверяет включение и работу. Автор готовит плагин и каталог → проверяет оба → вызывает функцию → распространяет через доступный репозиторий. Проверка области установки, прав доступа и версии, используемой для обновлений, помогает воспроизвести конфигурацию в другой среде.

Автоматическая регистрация официального каталога имеет условия, а прошедшие проверку публикации не получают безусловной гарантии правильной работы. Начните с одной нужной функции, проверьте результат и затем расширяйте набор. Связанные механизмы разобраны в статьях Хуки Claude Code, Claude Agent Skills, MCP и Артефакты Claude Code.

Частые вопросы

В. Чем плагин отличается от навыка?
О. Навык — процедура для выполнения; плагин — единица распространения, объединяющая её с хуками, настройками MCP и другими компонентами. Для явного вызова навыка плагина используйте /plugin-name:skill-name. Возможность автоматического выбора зависит от описания и настроек.

В. Не могу найти официальный маркетплейс.
О. Официальный claude-plugins-official регистрируется автоматически при первом интерактивном запуске, но предыдущее неинтерактивное использование, сетевые ограничения или управляемые политики могут этому помешать. В среде, где это разрешено, попробуйте /plugin marketplace add anthropics/claude-plugins-official. Одна регистрация не устанавливает отдельные плагины.

В. Может ли любой автор распространять свой плагин?
О. Один из вариантов — разместить плагин и каталог в собственном доступном Git-репозитории. Заявка в каталог сообщества подаётся отдельно; индивидуальные авторы могут использовать форму Console. Для отправки через claude.ai есть требования к организации и правам. Проверьте также, что source в каталоге указывает на фактическое расположение плагина.

В. Почему плагин не обновляется после изменения кода?
О. При распространении с кэшированием через Git наивысший приоритет имеет версия в plugin.json. Если оставить её прежней, изменение только версии в каталоге не обновит плагин. Если версия не указана ни там, ни там, используется SHA определённого Git-коммита, но также важны операция обновления и ref источника. Загрузка на месте из локального каталога, архивные источники и источники типа command подчиняются другим правилам.

В. Безопасен ли плагин, если validate завершился успешно?
О. Нет. Проверка структуры и конфигурации отличается от проверки фактического поведения и безопасности. Валидация одного каталога не читает тела навыков и подобные файлы. Проверьте отдельный плагин и испытайте его функции и побочные действия. Проверка перед публикацией в сообществе также не заменяет проверки издателя и включённого кода.