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

Плагины Claude Code выглядят как небольшая функция для упаковки, но решают более серьёзную проблему. До их появления настройка Claude Code была разбросана по папке .claude/. Делиться ею было неудобно, версионировать — хлопотно, проверять — трудно. Плагин собирает всё это в одну стандартную единицу.

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

Отдельная конфигурация или плагин?

Два варианта различаются именованием и тем, для кого они:

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

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

Первый плагин за три шага

1. Создайте папку и манифест.

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

Файл манифеста plugin.json кладётся в эту скрытую папку и задаёт плагину идентичность:

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

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

2. Добавьте скил. Скилы лежат в каталоге skills/, каждый в своей папке с файлом SKILL.md:

mkdir -p my-first-plugin/skills/hello---
description: Greet the user with a friendly message
disable-model-invocation: true
---

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

3. Попробуйте локально.

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

Когда Claude запустится, ввод /my-first-plugin:hello выполнит скил.

Пространства имён стоит отметить отдельно. Каждый скил плагина следует шаблону /plugin-name:skill-name, поэтому два плагина могут поставлять скилы с одинаковым именем и никогда не конфликтовать.

Чтобы скил принимал входные данные, вставьте в его SKILL.md заполнитель $ARGUMENTS:

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

После правок /reload-plugins применяет изменения. Одна странность: число скилов, которое показывается после перезагрузки, учитывает только каталог commands/, так что там может стоять ноль, хотя новый скил загружен и работает.

Есть и короткий путь. Команда claude plugin init my-tool создаёт плагин в ~/.claude/skills/, и он загружается во всех следующих сессиях как my-tool@skills-dir без всякого --plugin-dir.

Что может содержать плагин

У каждого места в корне плагина своя фиксированная роль:

• .claude-plugin/ содержит только манифест plugin.json
• skills/ содержит скилы в виде <skill-name>/SKILL.md
• commands/ — старый формат скилов с плоскими Markdown-файлами, новым плагинам лучше использовать skills/
• agents/ содержит определения собственных агентов
• hooks/ содержит обработчики событий, описанные в hooks.json
• .mcp.json настраивает MCP-серверы
• .lsp.json настраивает языковые серверы для анализа кода
• monitors/ настраивает фоновые мониторы
• bin/ содержит исполняемые файлы, которые добавляются в PATH, пока плагин включён
• settings.json задаёт настройки по умолчанию, которые применяются при включении плагина

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

Если в плагине один скил, SKILL.md может лежать в корне, а name из его frontmatter станет именем для вызова. Плагинам с несколькими скилами стоит использовать структуру skills/.

Дополнения для более сложных плагинов

Языковые серверы. Чтобы поддержать язык, который Claude Code не покрывает сам, добавьте файл .lsp.json:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Тем, кто установит плагин, понадобится на машине соответствующий бинарник языкового сервера. Без него на вкладке Errors в менеджере /plugin появится ошибка запуска.

Фоновые мониторы. Опишите их в monitors/monitors.json, и они запустятся при активации плагина. Каждая строка, которую команда выводит в stdout, приходит Claude как уведомление:

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

Настройки по умолчанию. settings.json пока понимает только два ключа, agent и subagentStatusLine, а неизвестные ключи молча игнорируются. Ключ agent может сделать одного из агентов плагина основным потоком, и это меняет поведение Claude Code по умолчанию:

{
  "agent": "security-reviewer"
}

Тестирование

Главный инструмент разработки — флаг --plugin-dir. Он принимает как папку, так и упакованный архив:

claude --plugin-dir ./my-plugin.zip

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

Для удалённого тестирования есть --plugin-url:

claude --plugin-url https://example.com/my-plugin.zip

Если загрузка не удалась или архив повреждён, Claude Code всё равно запустится и запишет проблему на вкладку Errors в /plugin. Как и с любыми плагинами, загружайте только источники, которым доверяете.

Во время разработки /reload-plugins применяет изменения без перезапуска. Если что-то не работает, проверьте структуру папок, протестируйте каждый компонент отдельно и воспользуйтесь отладочными средствами CLI, описанными в справочных страницах Anthropic.

Как попасть в маркетплейс

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

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

Перед отправкой проведите проверку:

claude plugin validate ./your-plugin

При успехе выводится сообщение «Validation passed» и список предупреждений, если они есть. С --strict предупреждения превращаются в ошибки.

Заявку подают через одну из двух форм. Первый путь — форма на claude.ai, доступная только организациям с тарифами Team или Enterprise. Авторы-одиночки используют форму в Console. После одобрения плагин закрепляется за конкретным SHA коммита в репозитории сообщества, и CI переносит закрепление при каждом новом коммите. Публичные каталоги синхронизируются раз в сутки ночью, так что задержка между одобрением и появлением в marketplace.json — это нормально.

Официальный маркетплейс устроен иначе. Что туда попадёт, решает Anthropic, и открытой подачи заявок нет.

Перенос существующей настройки

Отдельные конфигурации конвертируются легко. Создайте папку плагина и манифест, затем скопируйте содержимое:

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

С хуками нужно разобраться отдельно. Возьмите объект hooks из существующего settings.json и поместите его в hooks/hooks.json.

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

Что меняют плагины

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

Это сдвигает Claude Code от инструмента к платформе. Инструмент хорошо делает одну работу, а платформа позволяет другим строить поверх неё. Что вырастет в маркетплейсе, предсказать трудно, но копирование целых папок .claude/ между машинами явно уходит в прошлое. Другие ИИ-продукты для программирования, в том числе Cursor, тоже запустили маркетплейсы плагинов, так что по всей экосистеме разрозненные компоненты превращаются в упакованные единицы, которыми можно делиться.