Plugins и marketplace

Слэш-команды, навыки, субагенты и хуки, рассмотренные в предыдущих статьях, живут в директории .claude/ проекта или пользователя — они персональны и привязаны к конкретному месту. Это удобно для экспериментов, но неудобно для обмена: чтобы дать коллеге тот же набор инструментов, нужно вручную копировать файлы. Плагин решает именно эту задачу — он упаковывает все компоненты в одну версионируемую, устанавливаемую и распространяемую единицу.

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

Плагин — это обычная директория с определённой структурой. Внутри могут находиться навыки, субагенты, хуки, MCP-серверы, LSP-серверы, фоновые мониторы и бинарники. Всё это вместе устанавливается одной командой и снимается одной же. Основное отличие от standalone-конфигурации — намеренное.

КритерийStandalone (.claude/)Плагин
Область видимостиОдин проектНесколько проектов, команда
Скиллы/hello/my-plugin:hello
РаспространениеВручнуюЧерез marketplace
ВерсионированиеНетversion в манифесте

Если вы всё ещё итерируете — оставайтесь в .claude/. Когда конфигурация стабилизировалась и её хочется отдать другим — оформляйте плагин.

Манифест: .claude-plugin/plugin.json

Единственный обязательный файл плагина — манифест. Он живёт строго в поддиректории .claude-plugin/ (не в корне!) и описывает идентичность плагина:

{
  "name": "code-quality",
  "description": "Автоформат, линт и проверка типов для TypeScript-проектов",
  "version": "1.2.0",
  "author": {
    "name": "Ваша команда"
  },
  "homepage": "https://github.com/your-org/code-quality-plugin",
  "repository": "https://github.com/your-org/code-quality-plugin",
  "license": "MIT"
}

Поле name — это и уникальный идентификатор, и префикс namespace. Навык review в плагине code-quality будет вызываться как /code-quality:review. Это не случайность — намеренное намеспейсирование предотвращает конфликты между плагинами с одноимёнными навыками.

Поле version необязательно, но важно для управления обновлениями: если оно задано, пользователи получают апдейт только когда вы его инкрементируете. Без него каждый git-коммит воспринимается как новая версия.

Проверь себя
Два разработчика создают плагины с навыком `review`. Плагин называется `frontend-tools` у одного и `backend-tools` у другого. Как будут называться команды после установки обоих?

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

code-quality/
├── .claude-plugin/
│   └── plugin.json          ← только сюда, больше ничего
├── skills/
│   └── review/
│       └── SKILL.md
├── agents/
│   └── strict-reviewer.md
├── hooks/
│   └── hooks.json           ← в плагине хуки живут здесь
├── .mcp.json                ← MCP-серверы
├── settings.json            ← настройки по умолчанию
└── bin/
    └── my-linter            ← добавляется в PATH

Частая ошибка: класть skills/, agents/ или hooks/ внутрь .claude-plugin/. Там должен быть только plugin.json. Все рабочие директории — в корне плагина.

Отличие от standalone-конфигурации: хуки больше не описываются в settings.json, а живут в hooks/hooks.json с тем же JSON-форматом. Это позволяет хранить их в самом плагине, не трогая глобальные настройки.

flowchart TD ROOT["code-quality/ (корень плагина)"] MANIFEST[".claude-plugin/\nplugin.json"] SKILLS["skills/\nreview/SKILL.md"] AGENTS["agents/\nstrict-reviewer.md"] HOOKS["hooks/\nhooks.json"] MCP[".mcp.json"] SETTINGS["settings.json"] BIN["bin/\nmy-linter"] ROOT --> MANIFEST ROOT --> SKILLS ROOT --> AGENTS ROOT --> HOOKS ROOT --> MCP ROOT --> SETTINGS ROOT --> BIN MANIFEST --> |"name, version, description, author"| NOTE1["Идентичность и namespace"] HOOKS --> NOTE2["Формат как в settings.json"] MCP --> NOTE3["Подключается при установке"] SETTINGS --> NOTE4["Только agent и subagentStatusLine"]
flowchart TD
    ROOT["code-quality/ (корень плагина)"]
    MANIFEST[".claude-plugin/\nplugin.json"]
    SKILLS["skills/\nreview/SKILL.md"]
    AGENTS["agents/\nstrict-reviewer.md"]
    HOOKS["hooks/\nhooks.json"]
    MCP[".mcp.json"]
    SETTINGS["settings.json"]
    BIN["bin/\nmy-linter"]

    ROOT --> MANIFEST
    ROOT --> SKILLS
    ROOT --> AGENTS
    ROOT --> HOOKS
    ROOT --> MCP
    ROOT --> SETTINGS
    ROOT --> BIN

    MANIFEST --> |"name, version, description, author"| NOTE1["Идентичность и namespace"]
    HOOKS --> NOTE2["Формат как в settings.json"]
    MCP --> NOTE3["Подключается при установке"]
    SETTINGS --> NOTE4["Только agent и subagentStatusLine"]
Структура директории плагина: все компоненты в корне, манифест в .claude-plugin/

Создание плагина: от нуля до рабочего состояния

Самый быстрый путь — claude plugin init:

claude plugin init my-tool

Команда создаёт ~/.claude/skills/my-tool/ с готовым манифестом и стартовым SKILL.md. Плагин загружается автоматически при следующем запуске под именем my-tool@skills-dir — без маркетплейса и установки.

Для более контролируемого пути — создайте структуру вручную и тестируйте через флаг --plugin-dir:

# Запустить Claude Code с локальным плагином
claude --plugin-dir ./code-quality

# Можно подключить несколько сразу
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

# Или тестировать zip-архив (v2.1.128+)
claude --plugin-dir ./code-quality.zip

Пока плагин загружен, команда /reload-plugins перечитывает все файлы без перезапуска — это экономит время в процессе разработки.

# Проверить плагин перед публикацией
claude plugin validate

validate запускает те же проверки, что и review-пайплайн маркетплейса. Лучше узнать о проблемах до сабмита, чем после.

Проверь себя
Вы создали плагин и запустили Claude Code с `--plugin-dir ./my-plugin`. Изменили `SKILL.md` внутри плагина. Нужно ли перезапускать Claude Code, чтобы изменения подхватились?

MCP-серверы и настройки в плагине

Плагин может поставлять MCP-серверы через файл .mcp.json в корне:

{
  "mcpServers": {
    "quality-db": {
      "command": "npx",
      "args": ["-y", "@your-org/quality-mcp-server"]
    }
  }
}

Это значит, что установка плагина автоматически подключает нужный MCP-сервер. Пользователю не нужно отдельно делать claude mcp add — всё приходит вместе.

Файл settings.json в корне плагина позволяет задать поведение по умолчанию. Поддерживаемые ключи — agent и subagentStatusLine. Через agent можно назначить один из субагентов плагина активным по умолчанию:

{
  "agent": "security-reviewer"
}

При включении такого плагина Claude Code будет использовать системный промпт, ограничения инструментов и модель именно этого субагента.

Marketplace: от локального до публичного

Anthropic поддерживает два публичных маркетплейса:

  • claude-plugins-official — курируемый набор плагинов от Anthropic, регистрируется автоматически при первом запуске.
  • claude-community — сторонние плагины, прошедшие review. Подключается через /plugin marketplace add anthropics/claude-plugins-community.

Для внутреннего использования команда может создать собственный приватный маркетплейс — обычный git-репозиторий с marketplace.json. Каждый проект указывает его в .mcp.json или настройках — и все разработчики получают доступ к корпоративным плагинам командой /plugin install.

Для подачи плагина в community-маркетплейс:

1. Запустить claude plugin validate — исправить все ошибки

2. Отправить через claude.ai/admin-settings/directory/submissions/plugins/new (Team/Enterprise) или platform.claude.com/plugins/submit (Console, для индивидуалов)

3. После одобрения плагин пинируется к конкретному commit SHA в каталоге anthropics/claude-plugins-community

Проверь себя
Почему хуки в плагине хранятся в `hooks/hooks.json`, а не в `settings.json`, как в standalone-конфигурации?

Миграция standalone-конфигурации в плагин

Если у вас уже есть навыки и хуки в .claude/, их легко перепаковать. Суть изменений:

# Создать структуру
mkdir -p my-plugin/.claude-plugin

# Скопировать компоненты
cp -r .claude/commands my-plugin/
cp -r .claude/agents  my-plugin/
cp -r .claude/skills  my-plugin/

# Хуки: извлечь из settings.json → my-plugin/hooks/hooks.json
mkdir my-plugin/hooks
# (перенести объект "hooks" из settings.json)

После создания плагина удалите оригиналы из .claude/ — иначе будут дубликаты. Важно: определения субагентов из .claude/agents/ имеют приоритет над одноимёнными агентами из плагина, поэтому пока оригинал на месте, плагинный вариант не используется.

Практический итог

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

Быстрое повторение
Какая частая ошибка при создании структуры плагина?
Быстрое повторение
Где должен находиться файл `plugin.json` в структуре плагина?
Быстрое повторение
Когда стоит создавать плагин вместо standalone-конфигурации в `.claude/`?

See also

Источники

  1. Create plugins — Claude Code Documentation
  2. Plugins reference — Claude Code Documentation