Плагины (Plugins): Упаковка разрозненных конфигураций в один клик
📚 Навигация по серии: В предыдущей статье [23 Субагенты (Subagents)] мы научили вас создавать специализированного помощника своими руками. Но не замечали ли вы одну проблему — subagent, команды, skill, hook, все эти полезные вещи, это «разрозненные детали», которые настраиваются по отдельности. В этой статье мы научим вас упаковывать их в плагины (plugin): установка в один клик, остановка в один клик, а также возможность брать готовые сборки напрямую из «магазина плагинов».
Друзья, сегодня мы поговорим о том, как упаковать кучу разрозненных конфигураций в один клик. К слову, сталкивались ли вы с такой ситуацией: вы усердно настроили для команды набор «subagent + hook + MCP», а потом однажды пришел новый коллега, и вы полчаса объясняете ему — «этот файл нужно положить в agents/, этот hook добавить в settings.json, а да, еще .mcp.json, не забудь» — и после объяснений обнаруживаете, что он все равно что-то упустил, и у него работает не так, как у вас. Это ничья не вина, управление разрозненными деталями всегда таково: чем более распределена конфигурация, тем легче что-то упустить при устном объяснении.
Оглянитесь на то, что мы накопили за предыдущие статьи: в статье 18 мы написали CLAUDE.md, в статье 22 настроили MCP server, в статье 23 создали subagent, а между делом вставляли skill и hook. Каждая из этих вещей полезна сама по себе, но все они разрознены — subagent лежит в agents/, hook прописан в settings.json, MCP настроен в .mcp.json, все разбросано по нескольким файлам.
Возникает проблема: этот набор, который вы кропотливо настроили в проекте А, при попытке использовать в проекте Б придется переносить файл за файлом вручную. Если новый коллега в команде захочет эту же конфигурацию, вам придется устно объяснять структуру каталогов, и легко что-то упустить. Управление разрозненными деталями — это утомительно и чревато ошибками.
Проще говоря, плагин — это официальный ответ Claude Code на эту проблему: упаковка этих разрозненных деталей, таких как commands, subagents, skills, hooks, MCP server, в пакет, который можно распространять целиком и запускать/останавливать в один клик. В этой статье мы полностью разберем: что такое плагины, как брать готовые из магазина и как ими управлять.
Прочитав эту статью, вы получите:
- Четкое понимание в одной таблице: что именно упаковывает плагин и как выбирать между ним и «разрозненной конфигурацией»
- Двухэтапную логику «магазина плагинов (marketplace)»: сначала добавьте магазин, затем установите плагин — скопируйте команды и используйте
- Практический опыт установки плагина из официального демонстрационного магазина и запуска его команд, с ожидаемыми результатами на каждом шагу
- Знание структуры каталога плагина (
plugin.json+ папки компонентов), чтобы знать, как разложить файлы при самостоятельной упаковке - «Проверку на доверие», которую необходимо пройти перед установкой сторонних плагинов, чтобы не воспринимать незнакомые плагины как безобидное ПО
01 Сначала разберемся: что же такое плагин
Сразу дадим вывод: Плагин — это «самодостаточная папка», в которую упакованы все те расширения (skill, subagent, hook, команды, MCP server), которые вы изучили ранее, и которую можно устанавливать, останавливать и распространять как единое целое.
Зачем он нужен? Потому что у разрозненных конфигураций есть три неизбежных болевых точки: сложность использования между проектами, зависимость совместного использования в команде от ручного труда и невозможность отслеживания версий. Если вы настроили subagent и hook в одном проекте и хотите перенести их в другой, вам придется копировать и вставлять файлы вручную; если хотите поделиться с коллегами, придется объяснять, куда положить каждый файл. Плагин же собирает весь этот набор «в одну коробку» — вы просто переносите всю коробку или передаете ее целиком кому-то еще.
Аналогия: магазин расширений браузера. Если вы хотите добавить в Chrome блокировку рекламы, перевод или создание скриншотов — вам не нужно писать код или менять конфигурацию, вы идете в магазин расширений, нажимаете «Установить», и весь набор функций появляется. Если больше не нужно — нажимаете «Удалить» для чистой деинсталляции. Плагины в Claude Code работают по тому же принципу: выбираете в магазине, устанавливаете весь набор функций в один клик, без необходимости настраивать каждый элемент вручную; это превращает расширения, разбросанные по нескольким файлам, в один элемент магазина, который можно прямо «установить/удалить».
Официальная документация очень четко описывает выбор между «плагинами» и «разрозненной конфигурацией», я свел это в одну таблицу:
| Критерий | Разрозненная конфигурация (каталог .claude/) | Плагин (plugin) |
|---|---|---|
| Лучше всего подходит для | Личного использования в одном проекте, личных рабочих процессов, быстрых экспериментов | Совместного использования в команде/сообществе, использования между проектами, версионированного выпуска |
| Как поделиться | Вручную скопировать файлы другим | Через магазин, другие нажимают /plugin install для установки в один клик |
| Имя skill | Короткое, например /hello | С пространством имен, например /my-plugin:hello |
| Можно ли управлять версиями | Нет, при изменении нельзя уведомить пользователей | Да, только при наличии номера версии пользователи получают обновления |
Логика принятия решений из этой таблицы сводится к одной фразе: для самостоятельного использования в одном проекте достаточно разрозненной конфигурации; если нужно поделиться с другими, перенести в другой проект или обновлять — тогда создается плагин. Официально также рекомендуется «сначала использовать .claude/ для быстрой итерации, а когда будет готово к публикации, преобразовать в плагин» — не стоит сразу создавать плагин для одноразовой конфигурации, это излишнее усложнение (overengineering).
Здесь есть один момент, который часто путает новичков, и его нужно прояснить сразу: имена skill в плагинах всегда имеют «пространство имен». Если вы написали skill с именем hello в плагине под названием my-plugin, то вызывать его нужно не как /hello, а как /my-plugin:hello.
💡 Краткий итог: Плагин — это коробка, объединяющая skill, subagent, hook, команды, MCP server, которую можно устанавливать и удалять целиком; для личного использования достаточно разрозненной конфигурации, а для публикации, повторного использования и обновлений нужно упаковывать в плагин.
02 Почему упаковка в один пакет лучше, чем разрозненное хранение
В предыдущем разделе мы объяснили «что это», а в этом добавим «почему это того стоит» — ведь, зная только концепцию, вы все еще можете думать: «Мне не трудно вручную скопировать пару файлов».
Настоящая разница кроется в трех вещах, и, рассмотрев их на конкретных примерах, вы все поймете.
Во-первых, использование в разных проектах. Представьте, что у вас есть готовый набор конфигураций для «рабочего процесса git-коммитов» — skill, генерирующий стандартные сообщения коммитов, и hook, автоматически запускающий lint перед коммитом. Изначально этот набор разрозненный, и при переходе в новый проект вам придется переписывать skills/ и ту часть из settings.json. Как только вы забудете скопировать часть с hook, перед коммитом в новом проекте lint не запустится, и может закрасться ошибка форматирования. После упаковки в плагин в новом проекте достаточно ввести /plugin install, и все готово, вы больше ничего не упустите.
Во-вторых, совместное использование в команде. Когда вы делитесь разрозненной конфигурацией с коллегами, вы в основном полагаетесь на слова: «скопируй эту папку, положи ее в .claude/agents/, а потом не забудь добавить этот hook в settings» — после таких устных инструкций девять из десяти человек настроят что-то не так. С плагином все иначе: вы публикуете его в магазине (даже в приватном репозитории вашей компании), коллега устанавливает его одной командой, и конфигурация становится абсолютно идентичной, больше нет проблемы «у меня работает, а у тебя нет».
В-третьих, обновления версий. Это самый фатальный недостаток разрозненных конфигураций. Если разрозненная конфигурация изменится, пользователи даже не узнают об этом, вам придется уведомлять каждого лично. Плагины могут иметь номера версий, когда вы выпускаете новую версию, пользователи автоматически получают ее при обновлении; официально даже предусмотрено «автоматическое обновление» — для официального магазина оно включено по умолчанию, а для сторонних отключено (очень разумный дизайн: обновления от своих можно получать автоматически, а от чужих — только с вашего согласия).
Аналогия: приложение на телефоне и его связь с магазин приложений. Вы установили приложение, выходит новая версия, магазин приложений уведомляет вас об «обновлении», вы нажимаете и обновляетесь, вам не нужно заново скачивать установочный пакет. Плагин для магазина — это то же самое, что приложение для магазина приложений: установка происходит в один клик, а обновления приходят через магазин, вам не нужно переносить их вручную.
Сравните разницу между разрозненными конфигурациями и плагинами в этих трех аспектах:
| Что вам нужно сделать | ❌ Разрозненная конфигурация | ✅ Плагин |
|---|---|---|
| Перенести в новый проект | Ручное копирование каждого файла, легко упустить | Одной командой /plugin install |
| Дать использовать коллегам | Устно объяснять, куда положить и как настроить | Опубликовать в магазине, другой человек устанавливает одной командой |
| Продвигать обновления | Невозможно уведомить, только кричать вслух | Есть номер версии, пользователи обновляются автоматически/вручную |
Честно говоря, если вы работаете один над одним проектом, вы не особо почувствуете преимущества плагинов; но как только людей и проектов становится больше, разрозненные конфигурации начинают тормозить процесс. Я сам полностью перешел на плагины только когда стал руководить командой — раньше, чтобы настроить окружение новичку, приходилось садиться с ним за экран и файл за файлом объяснять «это положи в agents/, этот hook добавь в settings», это отнимало полдня, и все равно кто-то что-то упускал; после упаковки в плагины и размещения во внутреннем репозитории, новички устанавливают все одной командой, конфигурация у них точно такая же, как у меня, и больше не возникает ситуаций «у меня работает, а у тебя нет».
💡 Краткий итог: Истинная ценность плагинов заключается в «масштабе» — использование между проектами, совместное использование в команде и обновление версий. В разрозненном виде все это делается вручную, а с плагинами — одной командой; чем больше людей и проектов, тем больше эта разница.
03 Магазин плагинов: сначала добавляем «магазин», затем устанавливаем «приложение»
Теперь, когда мы знаем, что такое плагины, возникает следующий вопрос: где мне взять плагины, созданные другими? Ответ — в «магазине плагинов (marketplace)».
Здесь есть важнейший момент во всей статье, на котором новички чаще всего спотыкаются: использование магазина — это «два шага», а не «один».
- Шаг первый: Добавление магазина. Вы «регистрируете» магазин в Claude Code, чтобы он мог видеть, какие плагины есть в этом магазине. Обратите внимание, на этом шаге не устанавливается ни один плагин, вы просто получаете доступ к витрине.
- Шаг второй: Установка плагина. Выбираете нужный вам плагин на витрине и устанавливаете его отдельно.
Аналогия: установка нового «магазина приложений» на телефон. Помимо встроенного магазина на вашем телефоне, вы можете установить сторонний магазин приложений — но «установка этого магазина» не равна «установке всех приложений в нем». Магазин просто позволяет вам зайти, посмотреть его ассортимент, а конкретное приложение вы должны выбрать и скачать сами. Магазин плагинов работает так же: добавление позволяет вам изучать ассортимент, а установка плагина — это отдельное действие.
Как только вы поймете эти «два шага», все последующие команды станут понятны. Начнем с добавления магазина — официально предусмотрено несколько источников, самый частый — добавление из GitHub:
/plugin marketplace add owner/repoПросто замените owner/repo на реальное имя репозитория GitHub (например, официальный демонстрационный магазин — это anthropics/claude-code). Помимо GitHub, магазины можно добавлять из URL-адресов Git (GitLab, Bitbucket, self-hosted), локальных путей и удаленных URL-адресов. Синтаксис описан в официальной документации, но новичкам достаточно запомнить GitHub как самый частый вариант.
После добавления магазина используйте эту команду для установки плагина:
/plugin install plugin-name@marketplace-nameПосле @ идет имя магазина, что означает «установить этот плагин из этого магазина». Например, установка интеграции с GitHub из официального магазина:
/plugin install github@claude-plugins-officialЗдесь нужно отдельно упомянуть официальный встроенный магазин: claude-plugins-official. Вам не нужно добавлять его вручную — он доступен сразу при запуске Claude Code, и содержит подборку лучших плагинов от Anthropic (внешние интеграции вроде GitHub, GitLab, Slack, Figma, Sentry, а также LSP-плагины для интеллектуальной работы с кодом, плагины для проверки безопасности и т.д.). Так что если вы хотите установить официальный плагин, пропустите шаг «добавления магазина» и сразу используйте install.
💡 Краткий итог: Использование магазина — это всегда два шага: «сначала добавить магазин, затем установить плагин» —
/plugin marketplace addдобавляет витрину,/plugin install xxx@имя_магазинаоформляет заказ; исключением является только официальный магазинclaude-plugins-official, который встроен и доступен для установки «из коробки».
04 Три магазина: для чего они нужны
В предыдущем разделе упоминалось несколько названий магазинов, и новички могут легко запутаться. В этом разделе мы четко разложим три магазина, поддерживаемых официально, чтобы в будущем, увидев название, вы знали, чей он.
Аналогия: три торговых центра с разным позиционированием в одном городе. Один — это флагманский магазин брендов (товары тщательно отобраны официально), второй — это открытый гипермаркет (третьи лица могут ставить свои палатки, но перед входом проходят проверку безопасности), а третий — это временный выставочный зал (специально для показа образцов, чтобы вы могли оценить эффект). Три официальных магазина Claude Code точно соответствуют этим ролям:
| Магазин | Команда для его добавления | Позиционирование | Что внутри |
|---|---|---|---|
claude-plugins-official (Официальный) | Встроенный, добавлять не нужно | Официально отобранное | Плагины, выбранные Anthropic, самые надежные |
claude-community (Сообщество) | /plugin marketplace add anthropics/claude-plugins-community | Отправлено третьими лицами, прошло автоматическую проверку | Плагины от сообщества, каждый зафиксирован на конкретном коммите |
claude-code-plugins (Демонстрационный) | /plugin marketplace add anthropics/claude-code | Примеры от официальных лиц | Демонстрационные плагины, показывающие возможности системы плагинов |
Нужно прояснить несколько ключевых моментов:
Официальный магазин самый стабильный, но закрыт для подачи заявок. Anthropic сами решают, какие плагины туда включать. Все, что там есть, тщательно отобрано, вероятность наткнуться на проблему минимальна. То, что нужно для повседневной работы (интеграция с GitHub, LSP для разных языков, проверка безопасности), в основном находится там.
Магазин сообщества открыт, но имеет порог входа. После отправки сторонним разработчиком плагин должен пройти автоматическую проверку и проверку безопасности от Anthropic, чтобы попасть туда. Причем каждый плагин «зафиксирован на конкретном коммите» — это значит, что вы устанавливаете ту же версию, которая проверялась, и автор не может тайно подменить содержимое. Его нужно добавлять вручную, а после добавления использовать имя claude-community при установке.
Демонстрационный магазин нужен для обучения. Там лежат образцы, «показывающие, что может делать система плагинов». В следующем практическом разделе мы будем использовать именно его. Его тоже нужно добавлять вручную.
Рекомендуемый порядок поиска: сначала ищите в официальном магазине, если там нет — идите в магазин сообщества. Найдя нужный плагин, сначала посмотрите его домашнюю страницу и требуемые права доступа, и только потом устанавливайте. Демонстрационный магазин обычно используется только для обучения или тестирования — это образцы, а не плагины для повседневного использования в продакшене.
💡 Краткий итог: Официальный магазин встроенный и самый надежный, магазин сообщества нужно добавлять вручную, но он проходит проверку, демонстрационный магазин — это образцы для обучения; в повседневной работе сначала ищите в официальном, если чего-то не хватает — идите в сообщество, а демонстрационный используйте для практики.
05 Что именно мы получаем при установке плагина?
Когда вы вводите /plugin install, что именно попадает в вашу среду? В этом разделе мы проясним этот момент, чтобы после установки у вас не возникало вопроса: «И что дальше, как мне этим пользоваться?».
Плагин может принести с собой несколько типов компонентов, и у каждого типа свой «способ активации», и это очень важно понимать:
| Компонент | Как использовать после установки |
|---|---|
| Skills / Commands | Превращаются в команды с пространством имен вида /имя_плагина:имя_skill, которые вы вызываете вручную, или Claude вызывает автоматически |
| Subagents | Появляются в списке /agents, Claude назначает их автоматически в зависимости от задачи, или вы можете выбрать их вручную |
| Hooks | Активируются автоматически при соответствующих событиях (например, после изменения файла), вам не нужно о них заботиться |
| MCP server | Запускается автоматически, его инструменты сразу доступны в панели инструментов Claude |
| LSP server | Обеспечивает Claude интеллектуальной работой с кодом в реальном времени (переход к определению, поиск ссылок, мгновенные ошибки), требуется отдельная установка бинарного файла языкового сервера |
Заметили? Некоторые компоненты «вызываете вы» (skill, команды), а некоторые «работают сами по себе» (hook, MCP, LSP). Поэтому после установки плагина вам нужно знать, какие именно компоненты он принес с собой, чтобы понимать, как им пользоваться.
Хорошая новость в том, что новая версия Claude Code показывает вам этот список еще до установки. Если вы откроете подробности плагина в интерфейсе /plugin, там будет раздел «Будет установлено» (Will install), где перечислены все команды, agents, skills, hooks, MCP и LSP server, включенные в этот плагин. Там также будет примерная оценка «Стоимости контекста» (Context cost) — она покажет, сколько токенов этот плагин будет съедать из вашего окна контекста на каждом раунде.
На этой «стоимости контекста» стоит остановиться подробнее, это очень важно. Вспомните, как в статье 19 мы говорили об управлении контекстом: каждый компонент плагина занимает определенное место на вашем рабочем столе. Установка слишком большого количества плагинов означает, что вы еще даже не начали работать, а значительная часть контекста уже занята описаниями skill и определениями инструментов MCP. Перед установкой плагина обязательно смотрите на эту оценку: пара сотен токенов — это не проблема, но если счет идет на тысячи, стоит задуматься: «А действительно ли мне это нужно?». Устанавливать кучу ненужных плагинов, которые просто так съедают контекст — это частая ошибка новичков.
И еще одна деталь: после установки плагина не забудьте выполнить команду /reload-plugins, чтобы он заработал, перезапускать Claude Code не нужно. Установка, остановка и включение плагинов во время сессии обновляются с помощью этой команды:
/reload-pluginsПосле выполнения этой команды система сообщит вам, сколько сейчас загружено плагинов, сколько skill, сколько agent, сколько hook, а также сколько MCP server и LSP server от плагинов.
💡 Краткий итог: Компоненты плагина делятся на те, что «вызываете вы» (skill/команды), и те, что «работают сами» (hook/MCP/LSP); перед установкой смотрите раздел «Будет установлено» и стоимость контекста в описании, а после установки выполняйте
/reload-pluginsдля применения изменений.
На этом изображении объединены две основные темы этой статьи: слева — двухэтапный процесс «добавить магазин → установить плагин», справа — пять типов компонентов (skill, subagent, hook, MCP server, LSP server), упакованных в плагин, и как они работают после установки (вызываются вручную или работают автоматически).
06 Практика: добавляем магазин, устанавливаем плагин и используем его
Теория без практики мертва. Ниже мы пошагово пройдем процесс добавления демонстрационного магазина от официальных лиц, установки настоящего плагина и запуска принесенных им команд, без использования каких-либо сложных сред, просто повторяйте шаги. Мы будем устанавливать упомянутый в официальной документации commit-commands — плагин, добавляющий skill для рабочего процесса git.
Шаг первый: Запустите Claude Code, добавьте демонстрационный магазин
Зайдите в любую папку и запустите Claude Code:
claudeПосле запуска введите в строку ввода (это первый шаг из «двух шагов» — добавление магазина):
/plugin marketplace add anthropics/claude-codeОжидаемый результат: Claude Code скачает каталог этого магазина и сообщит об успешном добавлении. Теперь на вашей «витрине» есть товары, но вы еще не установили ни один плагин.
Шаг второй: Откройте менеджер плагинов и осмотритесь
Введите:
/pluginОжидаемый результат: Появится интерфейс с четырьмя вкладками — Открытие (Discover) / Установленные (Installed) / Магазины (Marketplaces) / Ошибки (Errors), переключайтесь между ними с помощью клавиши Tab (или Shift+Tab для движения назад). Перейдя на вкладку «Открытие», вы увидите те самые демонстрационные плагины в добавленном вами магазине. Если вы видите commit-commands в списке = магазин добавлен правильно.
Шаг третий: Установите плагин commit-commands
Вы можете выбрать его в интерфейсе и указать область установки, либо установить прямо из командной строки (это второй шаг из «двух шагов»):
/plugin install commit-commands@claude-code-pluginsОбратите внимание, что после @ идет claude-code-plugins — это внутреннее имя демонстрационного магазина (а не anthropics/claude-code, которое вы использовали при добавлении, это был адрес репозитория). При установке вам предложат выбрать область применения:
- Область пользователя (User scope) (по умолчанию): доступно вам во всех проектах
- Область проекта (Project scope): устанавливается в
.claude/settings.json, доступно всем соавторам этого репозитория - Локальная область (Local scope): доступно только вам и только в этом репозитории
Для начала выберите «Область пользователя» (по умолчанию).
Ожидаемый результат: В терминале появится сообщение об успешной установке плагина, и, возможно, список зависимостей, которые были установлены автоматически.
Шаг четвертый: Активируйте плагин, посмотрите добавленные им команды
/reload-pluginsОжидаемый результат: Claude Code перезагрузит плагины и выведет количество загруженных плагинов, skill, agent, hook, а также MCP server и LSP server. Так как skill из commit-commands имеют пространство имен, он добавит команду типа /commit-commands:commit.
Шаг пятый: Применяем на практике — посмотрите, как работает skill плагина
Сначала сделайте какое-нибудь изменение в текущей папке (например, создайте текстовый файл), а затем введите:
/commit-commands:commitОжидаемый результат: Этот skill поможет вам поместить изменения в индекс (stage), сгенерировать сообщение коммита и создать коммит. Увидев, как он проходит весь этот рабочий процесс git, вы убедитесь, что плагин не только установлен, но и его skill действительно работает — это и есть полное ощущение от «установки плагина и получения готового рабочего процесса».
⚠️ Если на пятом шаге при вводе
/commit-commands:commitпоявляется сообщение о том, что команда не найдена, сначала убедитесь, что вы выполнили/reload-pluginsна четвертом шаге; если это не помогло, перейдите в интерфейсе/pluginна вкладку «Ошибки» и посмотрите, есть ли ошибки при загрузке.
Пройдя эти пять шагов, вы собственноручно проверили всю цепочку «добавление магазина → установка плагина → активация → использование». В будущем установка любого плагина, по сути, будет проходить по этому же процессу.
💡 Краткий итог: Добавить магазин (
marketplace add) → Установить плагин (install) → Активировать (/reload-plugins) → Использовать команды с пространством имен — один раз пройти весь путь сcommit-commandsсвоими руками полезнее, чем запомнить десять команд.
07 Хотите собрать свой пакет? Сначала изучите структуру каталогов плагина
До этого мы обсуждали только «использование чужих плагинов», но рано или поздно вы подумаете: «А могу ли я упаковать свои конфигурации в плагин?». В этом разделе мы не будем учить вас создавать плагин с нуля (это тема для отдельной статьи), мы лишь покажем вам как выглядит каталог плагина, чтобы вы могли его читать и понимать.
Ядро плагина состоит всего из двух частей: один файл «удостоверения личности» + папки для различных компонентов.
Файл «удостоверения личности» — это .claude-plugin/plugin.json, в котором объявляются имя плагина, описание и версия:
{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0"
}Здесь самым важным является name — именно это имя станет префиксом пространства имен для skill. Skill в этом плагине превратятся в /my-first-plugin:xxx. version не обязателен, но только если вы укажете номер версии, пользователи будут получать обновления при выпуске новой версии, поэтому не забывайте менять номер версии при каждом релизе.
Папки компонентов располагаются в корневом каталоге плагина, сгруппированные по типу. Я составил таблицу с официальными соглашениями об именовании каталогов, просто следуйте ей:
| Что вы хотите добавить | В какой каталог положить |
|---|---|
| skill | skills/<имя>/SKILL.md |
| subagent | agents/ |
| hook | hooks/hooks.json |
| MCP server | В корень: .mcp.json |
| LSP server | В корень: .lsp.json |
Весь плагин будет выглядеть примерно так:
my-first-plugin/
├── .claude-plugin/
│ └── plugin.json ← Удостоверение личности, здесь находится только он
├── skills/
│ └── hello/
│ └── SKILL.md
├── agents/
│ └── reviewer.md
└── hooks/
└── hooks.jsonЗдесь есть подводный камень, о котором официально постоянно предупреждают, и на который часто натыкаются новички, я выделю его:
Частая ошибка: Не помещайте каталоги
commands/,agents/,skills/илиhooks/в каталог.claude-plugin/. Толькоplugin.jsonдолжен находиться в.claude-plugin/. Все остальные каталоги должны находиться на корневом уровне плагина.
Проще говоря: В папке .claude-plugin/ может находиться только один файл — plugin.json, все папки остальных компонентов должны располагаться в корневом каталоге плагина, на одном уровне с папкой .claude-plugin/. На эти грабли я наступил при первой же упаковке — ради удобства заодно закинул skills/ в .claude-plugin/, в результате плагин загружался успешно, /reload-plugins не выдавал ошибок, но тот самый skill упорно не появлялся. Я долго проверял имена, версию, пространство имен в plugin.json, все было правильно, пока не понял, что ошибся со структурой каталогов. Вытащил папки на один уровень с plugin.json, и все сразу заработало.
Вы могли заметить, что эта структура каталогов почти идентична структуре проекта .claude/, описанной в статье 13, папке agents/ из статьи 23 и файлу .mcp.json из статьи 22. Это не совпадение — суть плагина как раз в том, чтобы «собрать все ваши конфигурации, разбросанные по .claude/, в одну независимую папку, соблюдая те же форматы». Поэтому официально и говорится, что разрозненные конфигурации можно «преобразовать в плагин», потому что форматы совместимы, их нужно просто перенести.
Если вы хотите по-настоящему протестировать собственный собранный пакет, официально предусмотрен быстрый способ без установки магазина — используйте параметр --plugin-dir при запуске, чтобы напрямую загрузить локальный каталог плагина:
claude --plugin-dir ./my-first-pluginЭтот флаг специально предназначен для разработки и тестирования. Изменив плагин, запустите /reload-plugins, чтобы увидеть эффект, вам не нужно будет проходить полный цикл «публикации в магазине и установки».
💡 Краткий итог: Плагин =
.claude-plugin/plugin.json(удостоверение личности,nameзадает пространство имен) + папки компонентов в корневом каталоге; запомните железное правило — в.claude-plugin/лежит толькоplugin.json, все остальные папки лежат в корне.
08 Установка сторонних плагинов: сначала пройдите «проверку на доверие»
Это раздел, к которому нужно отнестись со всей серьезностью, и именно здесь новички чаще всего теряют бдительность: плагин — это не безобидная маленькая утилита, он может выполнять произвольный код на вашем компьютере с вашими правами доступа.
Вспомните границы безопасности, обсуждавшиеся в статье 21 — те принципы оценки применимы и к плагинам, и даже в большей степени. Официальная документация говорит об этом очень строго:
Плагины и магазины являются высокодоверенными компонентами, которые могут использовать права вашего пользователя для выполнения произвольного кода на вашем компьютере. Устанавливайте плагины и добавляйте магазины только из проверенных источников.
Что это значит? Плагин может содержать hook (автоматически запускаемые скрипты), MCP server (автоматически запускаемые программы), исполняемые файлы в bin/. Когда вы устанавливаете и включаете плагин, все эти вещи запускаются с вашими правами — плагин может читать ваши файлы, подключаться к сети, выполнять команды, у него те же права, что и у вас, когда вы вводите команды. Установить плагин из неизвестного источника — это примерно то же самое, что запустить скрипт от незнакомца прямо на вашем компьютере.
Аналогия: скачивание .exe файла с незнакомого сайта и его запуск двойным кликом. Вы же не скачиваете и не запускаете первый попавшийся исполняемый файл с незнакомого сайта? Потому что, запустив его, он может делать столько же, сколько и вы сами. Установка стороннего плагина имеет ту же природу — надежность источника — это вопрос, на который нужно ответить ДО установки, нельзя устанавливать плагины просто потому, что это удобно.
Поэтому вот три вопроса для самопроверки «перед установкой стороннего плагина», которые стоит считать строгими правилами:
| Что проверить | Как проверить |
|---|---|
| Надежен ли источник? | В первую очередь официальный магазин; для магазина сообщества — посмотрите автора, домашнюю страницу; для незнакомых личных репозиториев — если не уверены, не устанавливайте |
| Что внутри? | Перед установкой посмотрите раздел «Будет установлено» в подробностях плагина через /plugin, чтобы понять, есть ли там hook / MCP / исполняемые файлы |
| Какая область видимости? | Если не уверены, сначала попробуйте «Локальную область» (Local scope), не применяйте сразу «Область пользователя» (User scope) для всех проектов |
Несколько официальных механизмов, которые могут немного успокоить: плагины из магазина сообщества проходят автоматическую проверку и проверку на безопасность, и они фиксируются на конкретном коммите (автор не может подменить содержимое); официальный магазин отбирается самой Anthropic, он самый безопасный. Но все это не может заменить ваше собственное суждение — главное правило: «устанавливайте только из проверенных источников».
Надежная практика: Плагины из официального магазина устанавливайте напрямую; плагины из магазина сообщества — сначала загляните на главную страницу, чтобы узнать, кто автор, что делает плагин и какие права ему нужны, и только потом принимайте решение; частные плагины из незнакомых источников не трогайте, если не можете прочитать их код. Честно говоря, плагины — это удобно, но баланс между «удобством» и «безопасностью» всегда остается на вашей совести — не принимайте гладкость установки в один клик за доказательство безопасности плагина.
💡 Краткий итог: Плагины могут запускать произвольный код с вашими правами, установка стороннего плагина равносильна запуску скрипта от незнакомца на вашем компьютере; перед установкой выполните три проверки — надежен ли источник, что он принесет с собой и какова область применения, официальный магазин самый надежный, плагины из незнакомых источников лучше не устанавливать вообще.
09 Заключение
В этой статье мы разобрали концепцию «плагинов» в Claude Code от теории к практике — по сути, это способ собрать те разрозненные элементы, которые вы изучили ранее, в единую коробку, которую можно целиком устанавливать, распространять и обновлять.
Давайте соберем вместе все ключевые моменты:
| Что вам нужно сделать | Что использовать | Ключевые моменты |
|---|---|---|
| Понять, что такое плагин | plugin = коробка с разрозненными элементами | Упаковывает skill/subagent/hook/MCP/LSP, для себя — разрозненно, для других — в плагин |
| Взять чужие плагины | Магазин плагинов | Два шага: marketplace add добавить магазин → install установить плагин |
| Распознавать магазины | Три официальных магазина | Встроенный официальный — самый надежный, сообщество — нужно добавлять вручную, демонстрационный — для практики |
| Активировать плагин | /reload-plugins | Обновляет установку/остановку на лету, без перезапуска |
| Посмотреть, что установлено | Подробности в /plugin | Список «Будет установлено» + стоимость контекста, смотрите перед установкой |
| Упаковать свой | plugin.json + папки компонентов | В .claude-plugin/ лежит только plugin.json |
| Установка сторонних | Три проверки на доверие | Может выполнять любой код, устанавливайте только из проверенных источников |
Теперь вы должны уметь: Понимать, как выбирать между плагинами и разрозненной конфигурацией, использовать трехшаговый процесс «добавить магазин → установить плагин → /reload-plugins» для получения готовых функций из магазина, понимать список «Будет установлено» и оценку стоимости контекста в подробностях плагина, знать, как выглядит структура каталогов плагина, и четко понимать, что перед установкой стороннего плагина необходимо пройти проверку на доверие. С этими навыками вам больше не придется настраивать все с нуля — берите готовые наборы из магазина и используйте.
С 18-й по эту статью вы собрали полный «ящик с инструментами расширений» Claude Code: CLAUDE.md, MCP, subagent, skill, hook, и, наконец, плагины для управления всем этим. На этом сборка инструментов завершена.
Следующая статья 25 «Система памяти (memory)» — инструменты собраны, но не заметили ли вы одну неприятность: при открытии каждой новой сессии Claude снова как чистый лист, он мгновенно забывает ваши предпочтения, которые вы ему сообщили в прошлый раз, и жесткие правила проекта. В следующей статье мы поговорим о том, как заставить Claude «запоминать» вас между сессиями — запомнить ваш любимый стек технологий, запомнить жесткие правила проекта, чтобы не приходилось объяснять все с нуля каждый раз. Подумайте: разве не было бы намного проще, если бы он, как старый напарник, с которым вы работаете долгое время, с первых слов знал ваши привычки?