Плагины Claude Code: упакуй инструментарий в один пакет

Накопил рабочие skills, пару агентов и несколько slash-команд — и всё это лежит россыпью в .claude/ твоего проекта. Работает. У тебя. Коллеге придётся вручную копировать каждый файл, повторять настройки — и это только по памяти, ничего не забыв. Плагины Claude Code решают эту проблему: упаковываешь весь инструментарий в один пакет с манифестом, коллега ставит его одной командой и получает то же самое без ручной донастройки.

Что такое плагин и зачем он нужен

Плагин — это директория с манифестом и компонентами: slash-команды, subagents, skills, hooks, при необходимости объявленные MCP-зависимости. Один пакет — один источник правды.

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

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

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

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

coffeecrm-plugin/
├── .claude-plugin/
│   └── plugin.json              # ← только манифест здесь
├── commands/
│   └── scaffold-resources.md    # slash-команда
├── agents/
│   └── resource-builder.md      # subagent
├── skills/
│   └── crud-resource-generator/
│       └── SKILL.md
└── README.md                    # как ставить и что внутри

Claude Code сам находит компоненты в стандартных папках — их не нужно перечислять в манифесте. Явные пути (commands, agents, skills) нужны только если файлы лежат в нестандартных местах.

Манифест: что обязательно, что нет

Сердце плагина — plugin.json. Минимально необходимое поле — name. Остальное — метаданные:

{
  "name": "coffeecrm-plugin",
  "displayName": "CoffeeCRM Toolkit",
  "version": "1.0.0",
  "description": "Генератор CRUD-ресурсов, агент-сборщик, команда параллельной сборки.",
  "author": { "name": "Your Team" },
  "keywords": ["coffeecrm", "nestjs", "crud"]
}

Если инструментарий опирается на MCP-сервер, объяви зависимость полем mcpServers. В путях к скриптам используй переменную ${CLAUDE_PLUGIN_ROOT} — она указывает на папку установленного плагина и не ломается при переносе или обновлении.

Конкретные поля манифеста развиваются вместе с платформой — всегда сверяй актуальную страницу plugins-reference в документации, а не память.

Как собрать плагин на практике (CoffeeCRM)

Для наглядности — пример из курсового проекта CoffeeCRM (Next.js + NestJS + PostgreSQL). За несколько модулей там накопились: skill генерации CRUD-ресурсов, агент resource-builder, команда /scaffold-resources для параллельной сборки через worktree. Всё это нужно переупаковать в плагин.

Шаг 1. Создай директорию и манифест.

mkdir -p coffeecrm-plugin/.claude-plugin
# создай .claude-plugin/plugin.json с содержимым выше

Шаг 2. Создай папки для компонентов на корне плагина — agents/, skills/, commands/. Не внутри .claude-plugin/, это частая ошибка.

Шаг 3. Перенеси агента. Файл resource-builder.md из .claude/agents/ проекта — в agents/ плагина. Формат остаётся тем же, агент становится частью пакета.

Шаг 4. Перенеси skill. Папка crud-resource-generator/ вместе с SKILL.md — в skills/ плагина. Проверь, что description в SKILL.md остался валидным триггером — Claude Code именно по нему решает, когда вызывать skill.

Шаг 5. Упакуй команду. commands/scaffold-resources.md описывает сценарий: раздели ресурсы по worktree → делегируй resource-builder → сведи общий слой отдельным шагом. Весь паттерн параллельной оркестрации — одна slash-команда.

Шаг 6. Напиши README.md. Что устанавливает плагин, как его поставить, от каких MCP зависит. Без документации плагин существует только у тебя — это не командный инструмент.

Установка в чистый проект

Когда плагин собран, проверяй его именно на чистом проекте — без локальных skills и агентов. Это имитация машины нового члена команды.

Подключение через маркетплейс или локальный путь — точные команды (claude plugin install ...) смотри в актуальной документации. После установки убедись, что:

• /scaffold-resources появилась в списке доступных команд;
• агент resource-builder виден;
• skill подхватился и срабатывает по триггеру.

Если всё три пункта работают без ручной донастройки — плагин готов к командному использованию.

Где ещё применять этот подход

Структура плагина не зависит от стека. Меняется только содержимое skills/, agents/, commands/ под конкретный язык и фреймворк — упаковка и установка идентичны. Django-проект, Go-сервис, iOS-приложение на Swift — логика та же: собери наработки в пакет, задокументируй, распространяй через плагин.

Хорошая эвристика: если ты настраивал Claude Code в новом проекте дольше 10 минут — это работа для плагина.

Итог

Плагин Claude Code — это не сложно. Папка с правильной раскладкой (commands/, agents/, skills/ на корне + манифест в .claude-plugin/), минимальный plugin.json и README.md. Подключается одной командой — весь инструментарий сразу доступен без ручной настройки.

Навык сборки плагинов замыкает цикл: от разовых экспериментов со skills и subagents — к воспроизводимому командному инструменту. Если хочешь пройти этот путь на реальном проекте с нуля и до деплоя — полный курс по Claude Code строится именно так.