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

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

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

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

Мы собрали плагин и разобрали правила его структуры. Теперь добавим цикл проверки: команда claude plugin validate с режимом --strict, локальная загрузка через --plugin-dir, вкладка Errors в панели /plugin, проверка компонентов через /context, /hooks и отладочный лог.

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

• Как проверить манифест командой claude plugin validate и что означает -strict
• Чем отличаются ошибки валидации от предупреждений
• Как тестировать плагин локально, не устанавливая его
• Что делает -plugin-dir, когда плагин с таким именем уже установлен
• Где искать причину, если компонент плагина не загрузился

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

• claude plugin validate — команда проверки плагина или marketplace на ошибки схемы и путей.
  • -strict — флаг валидатора, превращающий предупреждения в ошибки.
  • -plugin-dir — флаг запуска, загружающий плагин из каталога на время одной сессии.
• Вкладка Errors — раздел панели /plugin, где перечислены ошибки загрузки плагинов.
• /reload-plugins — команда перезагрузки плагинов и их компонентов без перезапуска сессии.

Валидатор: первая линия проверки

Начинать стоит с валидатора — он ловит проблемы схемы за секунду:

claude plugin validate ./my-plugin

Если всё в порядке, вы увидите Validation passed, а при наличии замечаний — Validation passed with warnings. Предупреждения не роняют проверку, но игнорировать их не стоит.

Разница между ошибкой и предупреждением здесь строгая и полезная:

• Ошибка — у известного поля неверный тип. Например, keywords задано строкой вместо массива. Такие поля ломают загрузку.
• Предупреждение — поле неизвестно валидатору. Обычно это опечатка, и валидатор подсказывает похожее правильное имя.

Чтобы предупреждения тоже считались ошибками, добавьте флаг:

claude plugin validate ./my-plugin --strict

Это удобная настройка для CI: сборка упадёт, если кто-то опечатался в поле манифеста. Тот же валидатор запускается в пайплайне ревью при подаче плагина в сообщественный marketplace, так что прогнать его локально стоит до отправки.

Важно понимать границы: валидатор не открывает файлы скиллов, подагентов, команд и хуков. Он проверяет манифест, схему и пути. Опечатка внутри SKILL.md или неверный матчер в hooks.json до него не доходят — это проверяется запуском.

Если у плагина нет манифеста, валидировать можно отдельную папку компонентов:

claude plugin validate ./my-plugin/agents

Локальный запуск: тест без установки

Второй уровень проверки — запустить плагин и посмотреть, как он себя ведёт:

claude --plugin-dir ./my-plugin

Плагин загружается на время одной сессии, из того каталога, где лежит, без копирования в кэш. Флаг принимает и zip-архив:

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

Здесь есть удобная деталь. Если плагин с таким же именем у вас уже установлен из marketplace, локальная копия имеет приоритет на эту сессию. Значит, можно тестировать правки в плагине, который вы используете, не удаляя установленную версию. Исключение — плагины, которые управляемые настройки принудительно включают или выключают: их --plugin-dir перекрыть не может.

Есть нюанс, который стоит запомнить: плагин из --plugin-dir попадает в список claude plugin list только если флаг стоит до подкоманды.

# Плагин виден в списке
claude --plugin-dir ./my-plugin plugin list

# Тот же плагин в списке не появится
claude plugin list

Проверяем компоненты по одному

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

Скиллы. Вызовите каждый по полному имени: /plugin-name:skill-name. Если скилл не появился в автодополнении, он не загрузился.

Подагенты. Проверьте, что они видны в /context в разделе Custom Agents, либо упомяните агента через @ по его полному имени с префиксом плагина.

Хуки. Спровоцируйте событие, на которое хук подписан: для PostToolUse с матчером Write|Edit — попросите Claude отредактировать файл. Какие хуки совпали, с каким кодом завершились и что вывели, записывается в отладочный лог:

claude --debug

MCP- и LSP-серверы. Сервер, который не смог стартовать, появляется на вкладке Errors панели /plugin — например, с сообщением Executable not found in $PATH, если бинарник не установлен. А вот сервер с некорректной конфигурацией просто пропускается: причину покажет claude --debug.

Отдельно полезная команда — claude plugin details: она показывает инвентарь плагина, то есть какие команды, скиллы, подагентов, хуки и серверы он на самом деле принёс.

Порядок разбора, когда плагин «не работает»

Документация предлагает такую последовательность:

1. Проверьте структуру. Убедитесь, что каталоги лежат в корне плагина, а не внутри .claude-plugin/. Это причина номер один.
2. Проверьте компоненты по отдельности. Скилл, подагент и хук проверяются разными способами — не делайте вывод обо всём плагине по одному неработающему скиллу.
3. Возьмите инструменты диагностики. Валидатор, вкладка Errors, claude --debug.

Есть ещё один частый сценарий, стоящий особняком: плагин установился, а его скиллы не появились. Документация даёт для этого прямое решение — очистить кэш плагинов и переустановить:

rm -rf ~/.claude/plugins/cache

После этого перезапустите Claude Code и установите плагин заново.

И самая частая мелочь, съедающая время: после установки посмотрите на итоговое сообщение. Если там написано Run /reload-plugins to activate., плагин ещё не активен в текущей сессии — выполните эту команду.

/reload-plugins

Если перезагрузка предупреждает, что она аннулирует кэш промпта, повторите её как /reload-plugins --force.

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

• Считать успешную валидацию гарантией работоспособности. Валидатор не открывает файлы скиллов, подагентов и хуков. Опечатка в теле SKILL.md или в матчере хука проверяется только запуском.
• Проверять плагин только по одному скиллу. Скиллы, подагенты, хуки и MCP-серверы загружаются независимо. Один рабочий скилл ничего не говорит о том, поднялся ли сервер: смотрите вкладку Errors.
• Не заметить сообщение Run /reload-plugins to activate. Установка прошла, но в текущей сессии плагин ещё неактивен. Люди перезапускают терминал и ищут проблему там, где её нет.
• Искать -plugin-dir плагин в claude plugin list. Он попадёт в список, только если флаг стоит до подкоманды: claude --plugin-dir <dir> plugin list.

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

• Что проверяет claude plugin validate? — Схему манифеста, типы полей и пути. Ошибка — неверный тип известного поля; предупреждение — неизвестное поле, обычно опечатка.
• Зачем нужен -strict? — Он превращает предупреждения в ошибки. Удобно в CI, чтобы опечатка в имени поля роняла сборку.
• Можно ли тестировать правки в уже установленном плагине? — Да. При совпадении имён локальная копия из -plugin-dir имеет приоритет на эту сессию, удалять установленную версию не нужно.
• Где смотреть, почему хук не сработал? — В отладочном логе: запустите claude --debug. Там записаны совпавшие хуки, их коды возврата и вывод.
• Скиллы плагина не появились после установки. Что делать? — Сначала выполните /reload-plugins. Если не помогло, удалите ~/.claude/plugins/cache, перезапустите Claude Code и переустановите плагин.

Итоги

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

Главное, что стоит унести из этого урока: плагины ломаются тихо, поэтому «вроде работает» — не проверка. Пара минут на валидатор и вкладку Errors экономит переписку с пользователями, которые уже поставили сломанную версию. А раз плагин теперь проверен, самое время его опубликовать — на следующем уроке мы разберём marketplace: как собрать каталог, раздать плагин команде и выкатывать обновления.