Плагіни 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, теж запустили маркетплейси плагінів, тож по всій екосистемі розрізнені компоненти перетворюються на запаковані одиниці, якими можна ділитися.