К этому моменту вы умеете настраивать Claude Code по частям: писать скиллы, описывать подагентов, вешать хуки, подключать MCP-серверы. Каждая из этих настроек живёт в своём месте — скилл в .claude/skills/, подагент в .claude/agents/, хук в settings.json, MCP-сервер в .mcp.json. Пока вы настраиваете один проект для себя, это удобно.

Проблема начинается, когда настройку нужно передать. Представьте: вы собрали рабочий процесс код-ревью — скилл с чек-листом, подагент-ревьюер, хук, который запускает линтер после каждой правки, и MCP-сервер к трекеру задач. Чтобы коллега получил то же самое, ему придётся вручную скопировать четыре разных файла в четыре разных места, ничего не перепутав. А через месяц вы поправите чек-лист — и повторите инструкцию заново, для каждого.

Плагин решает ровно эту задачу: он упаковывает все части настройки в один каталог, который устанавливается одной командой и обновляется централизованно. После этого урока вы будете понимать, из чего состоит плагин, когда он оправдан, а когда достаточно обычной папки .claude/.

Что уже умеем / что добавим

Вы уже создавали скиллы, подагентов, хуки и подключали MCP-серверы — каждый инструмент по отдельности. Теперь мы посмотрим на них сверху: как эти четыре сущности собираются в одну поставку, что при этом меняется в именах команд и почему установка плагина — это вопрос доверия, а не только удобства.

Что вы узнаете в рамках статьи

• Какие компоненты Claude Code плагин может нести в себе
• Чем плагин отличается от обычной настройки в каталоге .claude/
• Почему скиллы плагина получают префикс с именем плагина
• Как ведут себя хуки и подагенты плагина рядом с вашими собственными
• В каких случаях плагин оправдан, а в каких он лишний

Ключевые термины

• Плагин — самодостаточный каталог с компонентами Claude Code (скиллы, подагенты, хуки, MCP- и LSP-серверы), устанавливаемый и обновляемый как единое целое.
• Манифест плагина — файл .claude-plugin/plugin.json с именем, описанием и версией плагина.
• Корень плагина — каталог самого плагина: тот, который вы передаёте в --plugin-dir или в котором лежит .claude-plugin/plugin.json.
• Пространство имён (namespace) — префикс с именем плагина, который Claude Code добавляет к именам его скиллов и подагентов: /my-plugin:review.
• Marketplace — каталог плагинов, через который они распространяются и обновляются.
• Область установки (scope) — уровень, на котором плагин включён: user, project или local.

Что именно умещается в одну поставку

Плагин — это не «архив со скиллами». Он может нести весь набор расширений Claude Code сразу, и каждый компонент лежит в своей папке в корне плагина:

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # манифест: только он лежит здесь
├── skills/
│   └── code-review/
│       └── SKILL.md       # скилл
├── agents/
│   └── security-reviewer.md   # подагент
├── hooks/
│   └── hooks.json         # хуки
├── .mcp.json              # MCP-серверы
└── .lsp.json              # LSP-серверы

Здесь важна одна деталь, на которой спотыкаются почти все: внутри .claude-plugin/ лежит только plugin.json. Папки skills/, agents/, hooks/ и файл .mcp.json находятся в корне плагина, рядом с .claude-plugin/, а не внутри неё. Если положить их внутрь, Claude Code просто не увидит компоненты — ошибки не будет, плагин установится пустым.

Возьмём практический пример. Плагин «релизный процесс» может одновременно давать:

• скилл /release:checklist — чек-лист перед выкладкой;
• подагента release:changelog-writer — собирает changelog из истории коммитов;
• хук PostToolUse — прогоняет форматтер после каждой правки файла;
• MCP-сервер к вашему CI — чтобы Claude видел статусы сборок.

Всё это ставится одной командой и обновляется одним git push в репозиторий плагина.

Манифест: минимум, который нужен

Манифест описывает личность плагина. Обязательное поле в нём одно — name; остальное опционально, но полезно:

{
  "name": "release-tools",
  "description": "Чек-лист релиза, сборка changelog и проверки перед выкладкой",
  "version": "1.0.0",
  "author": {
    "name": "Platform Team"
  }
}

Поле name выполняет двойную работу: оно и идентификатор плагина, и префикс пространства имён для его скиллов. Поле version управляет обновлениями: если вы его задали, пользователи получат новую версию только когда вы измените эту строку. Забыли поднять версию — люди останутся на кэшированной копии, даже если вы залили десяток коммитов.

Сам манифест необязателен: без него Claude Code найдёт компоненты в стандартных папках и возьмёт имя из имени каталога. Но для плагина, который вы собираетесь распространять, манифест стоит писать всегда — иначе не будет ни версии, ни описания в списке плагинов.

Почему у скиллов плагина появляется префикс

Скилл плагина всегда вызывается с префиксом: скилл в папке skills/review/ внутри плагина release-tools становится /release-tools:review.

# Установили плагин и вызываем его скилл
/release-tools:review

Это сделано намеренно. Представьте, что вы поставили три плагина от разных команд и в каждом есть скилл review. Без префикса они бы конфликтовали, и было бы непонятно, какой из них сработал. С префиксом все три доступны одновременно и различимы.

Побочный полезный эффект: скилл плагина не перекрывает ваш собственный. Если у вас есть .claude/skills/deploy/SKILL.md, а плагин my-plugin тоже приносит скилл deploy, то доступны обе команды: /deploy — ваша, /my-plugin:deploy — плагина. Ничего не теряется.

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

Хуки ведут себя третьим образом: они не перекрывают друг друга, а добавляются. Хук из плагина и ваш хук на то же событие сработают оба.

Когда плагин нужен, а когда лишний

Плагин — не всегда правильный выбор. Официальная документация проводит границу так:

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

Ещё один аргумент за плагин, о котором легко забыть: контекст. Каждый включённый плагин добавляет свои описания скиллов и подагентов в контекстное окно на каждом ходу. Панель /plugin показывает для плагина оценку Context cost и раздел Will install со списком того, что плагин добавит. Смотреть туда до установки полезно: десяток включённых «на всякий случай» плагинов заметно съедает контекст.

Частые ошибки

• Положить skills/, agents/ или hooks/ внутрь .claude-plugin/. Внутри этой папки живёт только plugin.json. Компоненты, оказавшиеся внутри, просто не загрузятся — без сообщения об ошибке. Проверяйте структуру: всё, кроме манифеста, лежит в корне плагина.
• Не поднять version при обновлении. Если поле version задано, Claude Code считает его пином. Новые коммиты без изменения версии до пользователей не доедут: они останутся на кэшированной копии.
• Оставить старые файлы в .claude/agents/ после переноса в плагин. Проектные и пользовательские подагенты перекрывают одноимённых подагентов плагина, поэтому кажется, что плагин «не работает».
• Ставить плагины «про запас». Каждый включённый плагин тратит контекст на каждом ходу. Перед установкой посмотрите на оценку Context cost в панели /plugin.

Наиболее частые вопросы

• Может ли плагин состоять из одного скилла? — Да. Плагин, который поставляет ровно один скилл, может положить SKILL.md прямо в корень, без папки skills/. Для плагина, который может вырасти, лучше сразу использовать skills/.
• Обязателен ли plugin.json? — Нет. Без манифеста Claude Code найдёт компоненты в стандартных папках и возьмёт имя из имени каталога. Но для распространяемого плагина манифест нужен: без него нет ни версии, ни описания.
• Конфликтуют ли скиллы двух плагинов с одинаковым именем? — Нет. Каждый получает свой префикс: /plugin-a:review и /plugin-b:review живут рядом.
• Плагин заменит мои настройки в .claude/? — Скиллы — нет, они добавляются рядом под префиксом. Подагенты — наоборот: ваши файлы перекрывают одноимённых подагентов плагина. Хуки складываются: сработают и ваши, и плагина.
• Можно ли отключить плагин, не удаляя его? — Да, командой /plugin disable plugin-name@marketplace-name. Установка сохранится, компоненты перестанут загружаться.

Итоги

Отличная работа — вы разобрались в идее, которая превращает набор личных настроек в продукт, готовый к передаче. Теперь вы знаете, что плагин упаковывает скиллы, подагентов, хуки и MCP-серверы в один каталог; понимаете структуру этого каталога и главную ловушку с папкой .claude-plugin/; видите, почему скиллы плагина получают префикс и как ведут себя рядом с вашими собственными настройками подагенты и хуки.

Это тот случай, когда понимание правил конфликтов экономит часы отладки: большинство вопросов «почему плагин не работает» решаются проверкой того, где лежит файл и что его перекрывает. На следующем уроке мы перейдём от теории к практике и соберём собственный плагин с нуля — от пустой папки до работающего скилла с префиксом.