Справочник по плагинам: упаковываем свои настройки в готовый модуль
📚 Навигация по серии: Предыдущая статья 37 Чекпоинты (Checkpoints) научила вас сохранять и загружать состояние сессии, возвращаясь к безопасной точке в один клик. Эта статья переходит на другой уровень — если в статье 24 мы учились использовать чужие плагины, то здесь мы научимся создавать свои: как правильно расположить файлы в папке, за что отвечает каждое поле в
plugin.json, какие компоненты можно упаковать, как настроить зависимости и как развернуть свой маркетплейс для команды. Это подробный технический справочник по плагинам.
Запустив команду claude plugin details для одного из плагинов, в выводе можно заметить интересные цифры: этот плагин постоянно занимает около 180 token в сессии, а при срабатывании двух его встроенных skill расходуется еще по 2400 и 1800 token соответственно.
Казалось бы, безобидный плагин, но даже в режиме ожидания он занимает часть полезного пространства контекста. Это наводит на мысль: плагин не является черным ящиком — он состоит из понятных компонентов, каждый из которых занимает свое место, имеет определенный размер и правила вызова. Понимание этой структуры — ключ к созданию качественных и чистых плагинов.
В статье 24 мы разобрали основы работы с чужими плагинами: добавление маркетплейсов, установка, перезагрузка через /reload-plugins и вопросы доверия к коду. В этой статье мы не будем повторяться, а перейдем к более сложной теме — внутреннему устройству плагинов, их разработке и публикации. Если статья 24 учила «водить машину», то эта статья научит «разбирать двигатель и собирать собственный автомобиль с нуля».
Поскольку статья представляет собой технический справочник, плотность информации здесь выше, чем в предыдущих материалах. Вам не нужно запоминать всё сразу. Сначала пройдите путь создания и публикации простого плагина, а описание полей конфигурации используйте как справочник по мере необходимости.
Прочитав эту статью, вы получите:
- Стандартную структуру папок плагина и понимание железного правила: «в папке
.claude-plugin/должен лежать только файлplugin.json». - Полную таблицу полей
plugin.json: обязательные параметры, метаданные, пути к компонентам, пользовательские настройки и зависимости. - Список всех компонентов, которые можно упаковать в плагин (skill, command, agent, hook, MCP, LSP, monitor), с указанием мест их размещения и ограничений.
- Объяснение, почему в плагинах необходимо использовать переменные путей вроде
${CLAUDE_PLUGIN_ROOT}. - Пошаговый процесс создания, локального тестирования, настройки маркетплейса и публикации плагина для команды с примерами команд и вывода.
- Решения типичных проблем публикации, связанных с версионированием и зависимостями.
01 Структура папок плагина: собираем скелет
В статье 24 мы видели минимальный плагин — файл plugin.json и пара папок с компонентами. Для создания серьезного плагина нужно четко понимать его полную структуру, чтобы не запутаться в процессе разработки.
Главное правило: плагин представляет собой папку, в которой лежит файл манифеста, определяющий параметры плагина, а сопутствующие компоненты разложены по соответствующим папкам в корневом каталоге.
Аналогия: конструктор LEGO. В коробке лежат две вещи — инструкция по сборке, рассказывающая о названии набора и содержащихся деталях, и контейнер с отсеками, где детали разложены по типам (колеса отдельно, окна отдельно). Плагин устроен так же: plugin.json — это инструкция, а папки skills/, agents/, hooks/ — отсеки контейнера. Инструкция лежит в своем специальном месте, а детали разложены снаружи — отсюда и следующее важное правило.
Полная структура папок плагина выглядит так:
my-plugin/
├── .claude-plugin/ # Папка метаданных
│ └── plugin.json # Манифест (инструкция) — только он лежит здесь
├── skills/ # Навыки (Skills), по одной папке на навык: <имя>/SKILL.md
│ └── code-reviewer/
│ └── SKILL.md
├── commands/ # Старый формат записи Skills (простые .md файлы)
│ └── status.md
├── agents/ # Описание субагентов (Subagents)
│ └── security-reviewer.md
├── hooks/ # Конфигурация хуков (Hooks)
│ └── hooks.json
├── .mcp.json # Описание MCP-серверов
├── .lsp.json # Конфигурация LSP-серверов
├── bin/ # Исполняемые файлы, добавляемые в PATH
├── scripts/ # Скрипты хуков и утилит
└── settings.json # Настройки плагина по умолчанию⚠️ Критически важное правило, на котором часто спотыкаются новички: папка
.claude-plugin/предназначена только для файлаplugin.json. Все остальные папки (skills/,agents/,hooks/,commands/,output-styles/,themes/,monitors/) должны располагаться непосредственно в корневой директории плагина, а не внутри.claude-plugin/.
Проще говоря: внутри .claude-plugin/ должен лежать только один файл — plugin.json. Папки вроде skills/, agents/ и hooks/ должны находиться снаружи, на одном уровне с папкой .claude-plugin/. Об этой ошибке мы говорили в статье 24: если случайно положить папку skills/ внутрь .claude-plugin/, плагин загрузится, но описанные в нем skill работать не будут. Найти причину бывает непросто. Вспоминайте аналогию с LEGO: инструкция в своем кармане, детали — снаружи.
Еще одна деталь: файл CLAUDE.md в корневой директории плагина не загружается в качестве контекста проекта. Если плагину нужно передать инструкции для Claude, это делается через skill, agent или hook, а не через добавление CLAUDE.md в плагин. Это отличается от работы с CLAUDE.md на уровне проекта (описанной в статье 18).
💡 Резюме в одной фразе: Плагин состоит из манифеста (
.claude-plugin/plugin.json) и разложенных по папкам в корне компонентов; главное правило — не помещайте папки компонентов внутрь.claude-plugin/, они должны лежать в корне.
02 Файл plugin.json: разбор полей манифеста
Когда структура готова, перейдем к манифесту — plugin.json. Он задает имя, версию и конфигурацию плагина, являясь его центром управления.
Начнем с полезного факта: манифест не является строго обязательным. Если файл plugin.json отсутствует, программа Claude Code попытается автоматически найти компоненты в стандартных папках (skills/, agents/ и т.д.), а имя плагина определит по названию папки. Манифест необходим только тогда, когда вам нужно указать метаданные или задать нестандартные пути к компонентам. Но для полноценной публикации плагина манифест писать придется, поэтому разберем его структуру.
Аналогия: таможенная декларация. При отправке посылки вы прикладываете декларацию, где указано название груза, отправитель, версия, состав посылки. Таможня (в нашем случае Claude Code) проверяет этот документ, регистрирует посылку и размещает её на складе. plugin.json — это декларация плагина: имя, автор, версия и список компонентов описываются на одном листе.
Единственное обязательное поле
При создании манифеста обязательным является только одно поле:
| Поле | Тип | Описание |
|---|---|---|
name | string | Уникальный идентификатор плагина в формате kebab-case (строчные буквы и дефисы, без пробелов) |
Почему поле name так важно? Оно задает пространство имен (namespace) для всех компонентов плагина. Если плагин называется plugin-dev, а внутри него описан субагент agent-creator, в интерфейсе он будет доступен как plugin-dev:agent-creator. Вызов навыков этого плагина будет выполняться через префикс /plugin-dev:имя-навыка. Пространства имен гарантируют отсутствие конфликтов при совпадении имен компонентов из разных плагинов. Вы можете установить множество плагинов, и их функции не будут мешать друг другу благодаря уникальным префиксам.
Метаданные (описание плагина)
Эти поля не влияют на работу кода, но необходимы для пользователей при установке и просмотре информации:
| Поле | Назначение |
|---|---|
displayName | Понятное имя плагина для отображения в интерфейсе (может содержать пробелы и заглавные буквы). Если не указано, используется значение name |
version | Версия плагина в формате семантического версионирования (semver). При указании версии обновление у пользователей произойдет только при изменении этой строки (важная особенность, описанная в разделе 08) |
description | Краткое описание назначения плагина, отображаемое при поиске и установке |
author | Информация об авторе (поля name, email, url) |
homepage / repository / license | Ссылка на документацию / репозиторий кода / тип лицензии |
keywords | Теги для поиска и категоризации плагина |
Пути к компонентам (где лежат файлы)
По умолчанию программа ищет компоненты в стандартных папках skills/, agents/ и т.д., поэтому эти поля можно не указывать. Они нужны только при размещении файлов по нестандартным путям:
| Поле | Назначение |
|---|---|
skills | Указывает дополнительные папки с навыками (они добавляются к стандартной папке skills/) |
commands / agents / outputStyles | Задает папки компонентов (они заменяют стандартные папки) |
hooks / mcpServers / lspServers | Указывает пути к файлам конфигурации или содержит настройки непосредственно внутри манифеста |
dependencies | Список плагинов, от которых зависит работа текущего плагина (подробнее в разделе 08) |
Здесь кроется важная деталь поведения путей, описанная в документации: некоторые поля заменяют стандартные папки, а некоторые добавляют новые пути к существующим.
- Замена стандартных папок: это поля
commands,agentsиoutputStyles. Если вы укажете полеcommands, стандартная папкаcommands/сканироваться не будет. Если нужно сохранить сканирование стандартной папки и добавить новую, перечислите их списком:"commands": ["./commands/", "./extras/"]. - Добавление к стандартным папкам: это поле
skills. Стандартная папкаskills/сканируется всегда, а пути из поляskillsдобавляются к списку сканирования.
Эта особенность часто приводит к ошибкам: разработчик указывает "agents": ["./extra-agents/reviewer.md"], рассчитывая «добавить еще одного агента», но обнаруживает, что все агенты из стандартной папки agents/ пропали, так как поле agents заменило стандартный путь. Для решения проблемы нужно перечислить все папки в массиве. Сверяйтесь с этим правилом при настройке путей.
Пример заполненного манифеста с метаданными:
{
"name": "deployment-tools",
"displayName": "Deployment Tools",
"version": "1.2.0",
"description": "Инструменты автоматизации развертывания проектов",
"author": { "name": "Dev Team", "email": "dev@company.com" },
"license": "MIT",
"keywords": ["deployment", "ci-cd"]
}💡 Резюме в одной фразе: В файле
plugin.jsonобязательным является только полеname(задает пространство имен). При настройке путей помните, что поляcommandsиagentsзаменяют стандартные папки, аskillsдобавляет новые пути к существующим.
03 Состав компонентов плагина: семь типов деталей
Разберем, какие именно компоненты можно упаковать в папку плагина. В статье 24 мы упоминали некоторые из них, здесь же приведем полный список с указанием мест размещения и ограничений безопасности.
Аналогия: отсеки для деталей LEGO. Для удобства сборки колеса лежат в одном отсеке, окна в другом, фигурки в третьем. Компоненты плагина разложены по схожему принципу:
| Компонент | Папка размещения | Назначение | Способ вызова |
|---|---|---|---|
| Skills | skills/<имя>/SKILL.md | Вызываемые текстовые инструкции и навыки (статья 26) | Вручную через /имя-плагина:имя-навыка или автоматически силами Claude |
| Commands | commands/*.md | Упрощенный текстовый формат навыков (устаревает, используйте skills) | Аналогично Skills |
| Agents | agents/*.md | Специализированные субагенты (статья 23) | Отображаются в меню /agents, запускаются вами или Claude |
| Hooks | hooks/hooks.json | Автоматические действия по событиям жизненного цикла (статья 33) | Запускаются автоматически при наступлении событий в системе |
| MCP-серверы | .mcp.json | Интеграция внешних инструментов (статья 22) | Запускаются при активации плагина, инструменты добавляются в общий список |
| LSP-серверы | .lsp.json | Поддержка языковых серверов (переход к определению, поиск ссылок) | Срабатывают автоматически при работе с кодом (требуют наличия установленного LSP) |
| Monitors | monitors/monitors.json | Фоновый мониторинг файлов/логов с передачей данных в диалог | Запускаются автоматически при активации плагина (экспериментальная функция) |
Разберем важные ограничения и особенности работы с этими компонентами:
Ограничения безопасности для субагентов (Agents) в плагинах. Это важный момент безопасности. Документация указывает: субагенты, поставляемые в составе плагинов, не поддерживают параметры hooks, mcpServers и permissionMode в своем блоке frontmatter. Это сделано для того, чтобы устанавливаемый плагин не мог тайно прописать свои хуки, запустить сторонние MCP-серверы или изменить режим разрешений сессии без вашего ведома. Субагенты плагинов поддерживают только параметры name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background и isolation (для isolation единственным допустимым значением является "worktree").
Большое количество событий для хуков (Hooks). Хуки в плагинах работают с теми же событиями жизненного цикла, что и обычные хуки проекта (статья 33). Документация перечисляет около тридцати событий: от SessionStart (старт сессии), PreToolUse (перед вызовом инструмента, с возможностью блокировки), PostToolUse (после успешного вызова инструмента) до Stop (завершение генерации ответа) и SessionEnd (закрытие сессии). Вам не нужно учить их все, достаточно понимать, что автоматизировать действие можно практически в любой момент работы программы.
Разнообразие типов хуков. Помимо запуска shell-скриптов через тип command, плагины поддерживают отправку событий на вебхуки через тип http, вызов инструментов MCP через mcp_tool, оценку промптов моделью через prompt и запуск субагента-валидатора через тип agent.
Экспериментальный статус мониторов (Monitors). Этот компонент позволяет плагину в фоновом режиме отслеживать изменения файлов или логов и передавать новые строки в контекст диалога без явного запроса пользователя. Функция является экспериментальной, её архитектура может измениться в будущем. Для работы требуется Claude Code версии v2.1.105 или выше. Новичкам пока не рекомендуется использовать её в критически важных проектах.
Также плагин может содержать папку bin/ с исполняемыми файлами, путь к которой автоматически добавляется в переменную PATH при активации плагина (это позволяет вызывать скрипты плагина как обычные команды терминала). Файл settings.json задает настройки по умолчанию, но на данный момент поддерживает только два параметра: agent и subagentStatusLine. Параметр agent позволяет автоматически назначить субагента плагина главным исполнителем при запуске сессии.
💡 Резюме в одной фразе: Плагин может содержать семь типов компонентов: skill, command, agent, hook, MCP, LSP и monitor. Помните о снижении полномочий субагентов плагина (им запрещено настраивать хуки, MCP и менять режим разрешений) и об экспериментальном статусе мониторов.
04 Переменная путя ${CLAUDE_PLUGIN_ROOT}: пишем переносимый код
Этот раздел посвящен одной из самых частых ошибок при разработке плагинов и правилу её решения.
Представьте ситуацию: вашему плагину для работы хука нужно запустить скрипт scripts/format.sh или запустить файл server.js для MCP-сервера. Если прописать жесткий абсолютный путь вроде /Users/username/my-plugin/scripts/format.sh, то на компьютере другого пользователя плагин не запустится, так как имя пользователя и структура папок будут отличаться. Более того, при каждом обновлении плагина путь к его кэшу на диске меняется.
Для решения этой проблемы Claude Code предоставляет три переменные путей, которые автоматически заменяются на реальные пути в командах хуков, настройках MCP/LSP и текстах skill/agent:
| Переменная | На что заменяется | Назначение |
|---|---|---|
${CLAUDE_PLUGIN_ROOT} | Абсолютный путь к папке установки текущей версии плагина | Для обращения к скриптам, исполняемым файлам и конфигам внутри плагина |
${CLAUDE_PLUGIN_DATA} | Путь к постоянной папке данных плагина (сохраняется при обновлениях) | Для хранения установленных зависимостей (node_modules), кэша и состояния |
${CLAUDE_PROJECT_DIR} | Абсолютный путь к корневой директории текущего проекта | Для обращения к файлам и настройкам целевого репозитория |
Аналогия: указание «папка приложения» вместо жесткого пути. При написании инструкции к папке документов вы пишете «см. приложение в конце этой папки», а не «см. страницу 87 в папке на полке №5». При перекладывании папки на другую полку инструкция останется верной. Переменная ${CLAUDE_PLUGIN_ROOT} работает так же: где бы ни был установлен плагин и какая бы версия ни работала, она всегда указывает на корень папки этой версии.
Пример использования переменной в настройке хука (обратите внимание на кавычки для защиты от пробелов в путях):
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
}
]
}
]
}
}Важное системное правило, о котором нужно помнить:
При обновлении плагина путь
${CLAUDE_PLUGIN_ROOT}изменяется. Папка предыдущей версии сохраняется на диске около семи дней для завершения процессов, после чего удаляется. Не записывайте изменяемые данные и состояние в эту папку.
То есть, папка ${CLAUDE_PLUGIN_ROOT} является доступной только для чтения (read-only) и перезаписывается при каждом обновлении. Если плагину нужно сохранять состояние или устанавливать зависимости, делайте это в папке ${CLAUDE_PLUGIN_DATA}, данные в которой сохраняются при переходе между версиями. Распространенная ошибка — установка node_modules в папку ROOT, из-за чего при первом же обновлении плагина все зависимости стираются. Скрипты плагина храните в ROOT, записываемые данные и кэш — в DATA.
Еще одно ограничение безопасности: установленные плагины не могут обращаться к файлам вне своей директории по относительным путям. Попытка прописать путь вида ../shared-utils завершится ошибкой, так как при установке папка плагина целиком копируется в изолированный кэш (~/.claude/plugins/cache), и внешние файлы просто не переносятся на новое место. Для совместного использования файлов используйте символические ссылки (symlinks) или оформляйте их как зависимости.
💡 Резюме в одной фразе: При обращении к файлам внутри плагина всегда используйте переменную
${CLAUDE_PLUGIN_ROOT}вместо жестких путей. Храните изменяемые файлы и зависимости в папке${CLAUDE_PLUGIN_DATA}и не пытайтесь обращаться к файлам за пределами папки плагина.
05 Практика: создаем простой плагин и тестируем локально
Перейдем к практической части. Мы создадим с нуля простой плагин, подключим его локально и протестируем работу его навыка. Нам не потребуются сложные конфигурации, процесс автономен. Мы создадим плагин my-greeter с одним приветственным навыком.
Шаг 1: Инициализируем структуру плагина с помощью встроенной команды CLI
Проще всего создать заготовку плагина с помощью специальной команды plugin init, которая автоматически создаст правильную структуру папок:
claude plugin init my-greeter --with skillsФлаг --with skills указывает создать папку для навыков. Команда создаст файлы в папке ~/.claude/skills/my-greeter/, включая манифест .claude-plugin/plugin.json и файл навыка SKILL.md.
Ожидаемый результат: терминал выведет сообщение об успешном создании заготовки плагина по пути
~/.claude/skills/my-greeter/.
Системная особенность: папки внутри
~/.claude/skills/, содержащие файлplugin.json, автоматически распознаются программой как локальные плагины с суффиксом@skills-dirпри запуске сессии. Это избавляет от необходимости регистрировать маркетплейс и устанавливать плагин в процессе его разработки.
Шаг 2: Проверяем структуру созданных папок
Выведем список созданных файлов (для проверки структуры):
ls -R ~/.claude/skills/my-greeterОжидаемый результат: на экране отобразится структура с файлом
plugin.jsonвнутри папки.claude-plugin/и папкойskills/на внешнем уровне. Это соответствует правилу из раздела 01.
Шаг 3: Пишем логику нашего навыка
Откройте или создайте файл ~/.claude/skills/my-greeter/skills/hello/SKILL.md со следующим содержимым:
---
description: Приветствует пользователя в дружелюбном и воодушевляющем тоне
---
# Hello Skill
Пожалуйста, поприветствуй пользователя по имени "$ARGUMENTS" в очень дружелюбном и теплом тоне. Спроси, чем ты можешь помочь ему сегодня.Переменная $ARGUMENTS примет в себя текст, переданный при вызове навыка (стандартный синтаксис работы с аргументами навыков, описанный в статьях 26 и 27).
Шаг 4: Запускаем Claude с локальным плагином
Для тестирования плагина без публикации в маркетплейсе используйте флаг --plugin-dir для прямого указания папки плагина при запуске:
claude --plugin-dir ~/.claude/skills/my-greeterОжидаемый результат: программа Claude Code успешно запустится. При вводе команды
/helpв списке доступных команд отобразится наш новый навык с указанием пространства имен плагина.
Шаг 5: Проверяем работу навыка
Навыки плагинов вызываются с префиксом пространства имен:
/my-greeter:hello WalterОжидаемый результат: Claude выдаст приветственный текст на русском языке, обращаясь к вам по имени «Walter». Вызов навыка сработал по описанной инструкции, подтверждая правильность создания плагина.
Шаг 6: Тестируем изменение логики без перезапуска
Измените текст инструкции в файле SKILL.md (например, добавьте требование использовать смайлики). После этого в открытой сессии Claude Code запустите команду перезагрузки:
/reload-pluginsОжидаемый результат: при повторном вызове
/my-greeter:hello WalterClaude ответит с учетом внесенных изменений.
Важная особенность: изменения в файлах
SKILL.mdприменяются в текущей сессии мгновенно, но изменения хуков, MCP-серверов (.mcp.json) и субагентов (agents/) требуют вызова/reload-pluginsили перезапуска программы. Если вы изменили хук и не видите результата, сначала выполните reload.
Пройдя эти шаги, вы изучили полный цикл разработки: от инициализации структуры до локального тестирования и обновления кода.
💡 Резюме в одной фразе: Команда
claude plugin initсоздает скелет, флаг запуска--plugin-dirподключает плагин локально, а команда/reload-pluginsобновляет кэш. Это базовые инструменты разработчика плагинов.
06 Публикация плагина: создание собственного маркетплейса
Локальное подключение через ~/.claude/skills/ или --plugin-dir подходит для личного использования. Для распространения плагина среди коллег или сообщества необходимо настроить маркетплейс (marketplace). В статье 24 мы выступали в роли потребителей, здесь же мы станем авторами маркетплейса.
Сначала разграничим два похожих понятия, которые часто путают:
| Понятие | Назначение | Где прописывается |
|---|---|---|
| Источник маркетплейса (marketplace source) | Адрес репозитория с общим каталогом плагина (marketplace.json) | Указывается пользователем при вызове /plugin marketplace add |
| Источник плагина (plugin source) | Путь к коду конкретного плагина внутри каталога | Задается в файле marketplace.json в поле source для каждого плагина |
Аналогия: магазин и склад производителя. Источник маркетплейса — это адрес самого магазина, где лежит каталог товаров. Источник плагина — это адрес конкретного склада, откуда товар доставляется покупателю при заказе. Они могут находиться в разных местах: файл каталога может быть размещен на одном сервере, а код плагина скачиваться напрямую с репозитория разработчика.
Основой маркетплейса является один файл: marketplace.json в папке .claude-plugin/ в корне вашего репозитория маркетплейса. Он содержит имя каталога, информацию о владельце и список плагинов. Минимальный файл выглядит так:
{
"name": "my-plugins",
"owner": { "name": "Имя Владельца" },
"plugins": [
{
"name": "my-greeter",
"source": "./plugins/my-greeter",
"description": "Плагин для дружелюбного приветствия"
}
]
}Каждое описание плагина должно содержать имя name и путь к коду source. Поле source поддерживает различные типы источников:
| Тип источника | Формат записи | Применение |
|---|---|---|
| Относительный путь | "./plugins/my-greeter" | Плагин находится в том же репозитории, что и маркетплейс (наиболее частый случай) |
| GitHub | { "source": "github", "repo": "owner/repo" } | Код плагина расположен в отдельном репозитории GitHub |
| Git с подпапкой | Свойства url и path | Код плагина находится в подпапке крупного монорепозитория |
| NPM | { "source": "npm", "package": "@org/plugin" } | Плагин опубликован как пакет в реестре npm |
Практика: подключение тестового локального маркетплейса. Предположим, вы создали папку my-marketplace/, содержащую файл .claude-plugin/marketplace.json и папку с кодом плагина plugins/my-greeter/. Для тестирования введите в сессии Claude Code команды:
/plugin marketplace add ./my-marketplace
/plugin install my-greeter@my-pluginsОжидаемый результат: первая команда зарегистрирует локальный маркетплейс в системе, а вторая установит плагин
my-greeterиз каталогаmy-plugins. После этого вызов/my-greeter:helloстанет доступен. Этот процесс полностью повторяет установку официальных плагинов.
Перед отправкой изменений в общий доступ обязательно проведите валидацию структуры, запустив команду:
claude plugin validate ./my-marketplaceОжидаемый результат: утилита проверит структуру файла
marketplace.jsonна соответствие схеме, проверит отсутствие дубликатов имен плагинов, корректность относительных путей и версий. При указании пути к папке маркетплейса проверяется только файл каталога; для проверки настроек конкретного плагина укажите путь к его папке:claude plugin validate ./my-marketplace/plugins/my-greeter.
Для предоставления доступа коллегам опубликуйте репозиторий маркетплейса на GitHub. После этого другие разработчики смогут подключить его одной командой: /plugin marketplace add owner/repo. Для автоматической настройки окружения в проекте адрес маркетплейса можно прописать в параметре extraKnownMarketplaces в файле .claude/settings.json проекта. При первом открытии репозитория пользователи получат предложение установить необходимые плагины.
💡 Резюме в одной фразе: Для публикации плагина создайте каталог
.claude-plugin/marketplace.jsonс описанием плагинов и путей к ним (source). Проверьте корректность структуры командойclaude plugin validateперед публикацией репозитория.
07 Варианты работы с плагинами: выбор способа подключения
При разработке важно выбрать правильный способ подключения плагина в зависимости от текущей задачи. Использование маркетплейса при мелких правках или использование флагов запуска при командной разработке усложняют процесс. Сравним доступные варианты в таблице.
| Сценарий использования | Способ подключения | Инструкция | Особенности |
|---|---|---|---|
| Личное использование, быстрая разработка | Навыки в локальной папке | Размещение в ~/.claude/skills/<имя>/ с файлом plugin.json | Автоматически загружается в каждой сессии, изменения в SKILL.md применяются мгновенно |
| Тестирование локального кода | Флаг запуска CLI | claude --plugin-dir ./my-plugin | Подключается только на время текущей сессии. Позволяет временно переопределить настройки установленного плагина |
| Командная разработка и релиз | Маркетплейс | Описание в marketplace.json + вызов /plugin install | Поддерживает контроль версий, автоматические обновления и совместное использование |
Полезные нюансы использования:
Флаг --plugin-dir удобен для изоляции тестов. Он подключает плагин только для текущего запуска и не сохраняет настройки в системе. Это гарантирует чистоту окружения: после закрытия окна терминала следы плагина сотрутся. Также --plugin-dir временно переопределяет настройки установленного плагина с тем же именем, позволяя тестировать локальные правки без удаления стабильной версии.
Особенность путей для локальных навыков. Локальные плагины, размещенные в папке пользователя ~/.claude/skills/, доступны во всех проектах. Однако для плагинов, размещенных на уровне проекта в .claude/skills/, действует правило: они загружаются только при запуске Claude Code непосредственно из папки проекта и не ищутся вверх по дереву каталогов при запуске из подпапок. Запускайте сессию из корня проекта или выполняйте /reload-plugins при переходе между папками.
Не спешите создавать маркетплейс. На начальных этапах это избыточно. Рекомендуется отлаживать логику компонентов через --plugin-dir или размещая файлы в .claude/. Переходите к созданию манифеста маркетплейса только тогда, когда плагин протестирован и готов к совместному использованию.
💡 Резюме в одной фразе: Используйте папку
~/.claude/skills/для личных инструментов, флаг--plugin-dirдля отладки локального кода и маркетплейс для публикации стабильных версий. Не создавайте маркетплейс раньше времени.
08 Проблемы при публикации: управление версиями и зависимости
При публикации плагинов в маркетплейс разработчики часто сталкиваются с двумя проблемами: обновление версий и настройка зависимостей. Разберем, как устроена эта логика.
Проблема версионирования: кэширование при фиксированной версии
Это одна из самых частых ошибок. Программа Claude Code проверяет наличие обновлений плагина по следующему приоритету:
- Значение поля
versionв файлеplugin.jsonплагина. - Значение поля
versionв описании плагина в файлеmarketplace.json. - При отсутствии обоих полей используется хэш (SHA) последнего коммита в git.
В этом кроется важная особенность:
Фиксация версии через поле
versionблокирует автоматическое обновление кэша. Если вplugin.jsonуказана версия"version": "1.0.0", то внесение изменений в код и отправка коммитов в репозиторий без изменения этой строки не приведет к обновлению плагина у пользователей. Программа увидит ту же версию и продолжит использовать старый кэш.
Проще говоря: если вы указали версию "1.0.0", любые новые коммиты в репозитории будут игнорироваться пользователями при вызове /plugin update, так как для системы версия осталась прежней. Для применения изменений необходимо каждый раз увеличивать номер версии в манифесте (1.0.1, 1.1.0 и т.д.).
Выбирайте подходящую стратегию обновлений:
| Стратегия | Реализация | Поведение обновлений | Применение |
|---|---|---|---|
| Семантическое версионирование | Явное указание поля version в plugin.json с увеличением при релизах | Обновления приходят только при изменении номера версии разработчиком | Стабильные публичные плагины с редкими релизами |
| Обновление по коммитам (SHA) | Поле version не указывается, код хранится в git | Любой коммит в репозитории считается новой версией и скачивается пользователями | Внутренние командные плагины на этапе активной разработки |
Не указывайте версию одновременно в
plugin.jsonи в описании маркетплейсаmarketplace.json. Значение изplugin.jsonприоритетнее и перезапишет значение каталога без предупреждения, что может привести к путанице.
Типичный сценарий: команда разработала внутренний плагин, прописала версию "1.0.0", затем исправила баг, запушила код, но у коллег баг воспроизводится, а вызов /plugin update сообщает, что обновлений нет. Проблема в том, что система не увидела изменения версии. Для внутренних плагинов на этапе разработки просто удалите поле version из файлов настроек, и обновления по SHA коммита будут приходить автоматически.
Настройка зависимостей: поле dependencies
Если для работы вашего плагина требуются функции другого плагина, укажите это в поле dependencies:
{
"name": "my-plugin",
"dependencies": [
"helper-lib",
{ "name": "secrets-vault", "version": "~2.1.0" }
]
}При такой конфигурации установка вашего плагина автоматически запустит установку указанных зависимостей. Вы можете ограничивать версии зависимостей по правилам semver (например, ~2.1.0), чтобы обновление зависимого плагина не сломало ваш код. При удалении плагина команда claude plugin uninstall --prune автоматически очистит неиспользуемые зависимости, которые были установлены автоматически и больше не требуются другим плагинам (плагины, установленные вами вручную, удалены не будут).
💡 Резюме в одной фразе: При указании поля
versionобязательно увеличивайте его номер при каждом изменении кода, иначе пользователи не получат обновления (для частых обновлений не указывайте версию вовсе). Для автоматической установки связанных плагинов используйте массивdependencies.
09 Заключение
Мы подробно разобрали устройство, разработку и публикацию плагинов для Claude Code.
Обобщим ключевые выводы справочника:
| Тема | Главный вывод |
|---|---|
| Структура папок | Манифест лежит в .claude-plugin/plugin.json, все остальные компоненты располагаются строго в корневой папке плагина |
| Манифест plugin.json | Обязательным является только поле name (задает уникальное пространство имен). Поля путей могут заменять или дополнять стандартные папки |
| Компоненты | Поддерживается семь типов компонентов (skills, commands, agents, hooks, MCP, LSP, monitors). Субагенты плагинов ограничены в правах ради безопасности |
| Управление путями | Пути к файлам плагина должны быть относительными и использовать переменные вроде ${CLAUDE_PLUGIN_ROOT} |
| Разработка | Инициализация выполняется через plugin init, локальный запуск через флаг --plugin-dir, обновление кэша через /reload-plugins |
| Маркетплейс | Публикация каталога описывается в файле marketplace.json с указанием источников кода (source). Валидация выполняется через claude plugin validate |
| Версионирование | Фиксация версии блокирует обновление по коммитам. Для автоматических обновлений при разработке опустите поле version |
Теперь вы обладаете всеми знаниями для создания расширений: вы можете упаковать свои промпты, субагентов, MCP-инструменты и хуки в переносимый плагин, протестировать его локально с помощью переменных путей и опубликовать для команды через собственный маркетплейс GitHub.
В следующей статье 39 «Практика для начинающих» мы завершим изучение теоретических блоков и перейдем к решению реальной задачи. Мы объединим все изученные инструменты (CLAUDE.md, субагенты, MCP, команды, чекпоинты) в единый рабочий процесс для реализации небольшого проекта с нуля до этапа сдачи кода. Это позволит увидеть, как наши знания работают на практике.