Плагины Claude Code: как упаковать и раздать свои скиллы

Плагин или обычная папка .claude/

У Claude Code два способа добавить свои скиллы, агентов и хуки. Обычная папка .claude/ подходит для личных рабочих процессов, настроек под конкретный проект и быстрых экспериментов - скиллы там вызываются коротко, вроде /hello. Плагин - самостоятельная директория со скиллами, агентами, хуками или манифестом .claude-plugin/plugin.json - подходит, когда нужно делиться с командой, распространять в сообществе, выпускать версии и переиспользовать между проектами. Скиллы плагина всегда идут с пространством имён: /имя-плагина:hello.

Разумный путь - начинать с обычной папки .claude/ для быстрой итерации, а когда конфигурация созрела для распространения, конвертировать её в плагин.

Быстрый старт: первый плагин со скиллом

Создайте папку плагина и внутри - манифест:

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Поле name - это ещё и пространство имён для скиллов плагина, description показывается в менеджере плагинов, а version определяет, когда пользователи получают обновление.

Дальше - сам скилл, в папке skills/:

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

Проверка - флаг --plugin-dir, без установки:

claude --plugin-dir ./my-first-plugin

Внутри сессии скилл вызывается как /my-first-plugin:hello. Список подхваченных скиллов плагина виден во вкладке Custom commands команды /help.

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

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

Полный набор возможных компонентов в корне плагина: skills/ - скиллы как папки с SKILL.md, agents/ - определения кастомных субагентов, hooks/ - обработчики событий в hooks.json, .mcp.json - конфигурация MCP-серверов, .lsp.json - конфигурация языковых серверов для аналитики кода, monitors/ - фоновые наблюдатели в monitors.json, bin/ - исполняемые файлы, добавляемые в PATH для Bash, пока плагин включён, и settings.json - настройки по умолчанию при включении плагина.

Плагин с ровно одним скиллом может держать SKILL.md прямо в корне, без отдельной папки skills/ - но если плагин может вырасти до нескольких скиллов, лучше сразу использовать структуру с skills/.

Тестирование и обновление на лету

По мере правок вместо перезапуска Claude Code можно выполнить команду /reload-plugins - она перезагружает плагины, скиллы, агентов, хуки, MCP- и LSP-серверы плагинов. Можно загрузить сразу несколько плагинов, повторив флаг:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

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

Как поделиться плагином

У Anthropic два публичных маркетплейса для плагинов Claude Code. claude-plugins-official - курируемый набор от самой Anthropic, регистрируется автоматически при первом интерактивном запуске Claude Code. claude-community - открытый маркетплейс сообщества, куда сторонние плагины попадают после проверки; пользователи подключают его командой /plugin marketplace add anthropics/claude-plugins-community.

Перед подачей заявки стоит прогнать локальную проверку:

claude plugin validate ./your-plugin

Ревью-пайплайн выполняет ту же проверку на каждой заявке, плюс автоматический скрининг безопасности. Одобренные плагины попадают в публичный каталог, привязанные к конкретному коммиту в репозитории - CI автоматически обновляет привязку по мере новых коммитов в исходном репозитории плагина.

Перевод существующей папки .claude/ в плагин

Если скиллы или хуки уже накопились в личной папке .claude/, их можно превратить в плагин: создать структуру плагина с манифестом, скопировать папки commands, agents, skills в корень плагина, а хуки из settings.json перенести в отдельный файл hooks/hooks.json - формат тот же самый, меняется только расположение. После переноса стоит удалить оригиналы из .claude/, чтобы не путаться в дублирующихся версиях - определения агентов на уровне проекта или пользователя перекрывают одноимённые определения плагина, поэтому версия плагина вступит в силу только после удаления оригиналов.

Чек-лист