Плагіни у Claude Code

Плагін — це каталог із компонентами (скіли, агенти, hooks, MCP-сервери та інше), який Claude Code встановлює й завантажує як один пакет. Найчастіше плагін беруть із маркетплейсу — каталогу, що описує, які плагіни існують і звідки їх завантажити. Під час розробки плагін можна вантажити просто з папки чи zip-архіву, без маркетплейсу.

Маніфест .claude-plugin/plugin.json дає плагіну назву, версію й опис. Він необов’язковий: без нього Claude Code знаходить компоненти за стандартною структурою, а назву бере з запису в маркетплейсі (або з імені каталогу при --plugin-dir). Усередині маніфесту обов’язкове лише поле name.

Що може містити плагін

Жоден компонент не обов’язковий: плагін може складатися з одного скілу — або лише з dependencies (тоді це «набір» інших плагінів). Детальний опис кожного компонента — у розділах «Структура», «plugin.json» і «Компоненти».

Простір імен

Усе, що додає плагін, Claude Code ставить під назву плагіна (поле name маніфесту). Тому два плагіни можуть мати по скілу review і не конфліктувати. Для плагіна acme-django ви побачите:

/acme-django:migration-check                  # скіл skills/migration-check/SKILL.md
/acme-django:about                            # команда commands/about.md
@agent-acme-django:reviewer                   # агент agents/reviewer.md
plugin:acme-django:gitlab                     # MCP-сервер у /mcp
mcp__plugin_acme-django_gitlab__list_issues   # назва MCP-інструмента (для permissions і matcher’ів hooks)

• Ім’я скілу — /<plugin>:<тека>. Якщо в frontmatter задано name, воно замінює лише останній сегмент; префікс плагіна лишається.
• Агенти в підпапках додають сегменти: agents/review/security.md → my-plugin:review:security. Ім’я агента не може містити : — двокрапка зарезервована під префікс.
• Hooks префікса не мають. Якщо той самий hook лежить і в settings, і в плагіні, він спрацює двічі.
• Ім’я в маркетплейсі (запис у marketplace.json) — це ключ для встановлення й enabledPlugins; ім’я в маніфесті — простір імен. Тримайте їх однаковими.

Зв’язок з іншими сторінками

Плагін нічого не вигадує — він пакує те, що Claude Code вміє й так. Усі ці компоненти працюють і без плагіна (у .claude/ проєкту чи ~/.claude/):

• Скіли — формат SKILL.md, frontmatter, аргументи; у плагіні вони лише отримують префікс.
• Агенти — субагенти, їхній frontmatter і моделі (у плагіні частину полів ігноровано — див. «Компоненти»).
• Hooks і MCP — події, matcher’и, формат серверів; у плагіні той самий формат.
• Налаштування плагінів — ключі enabledPlugins, extraKnownMarketplaces, pluginConfigs та політики для організації.

Що додає увімкнений плагін до кожної сесії

Увімкнений плагін — частина кожної сесії, а не лише тих, де ви ним користуєтесь:

• Контекст і витрати. Назва й опис кожного скілу, агента й команди, які Claude може викликати сам, потрапляють у контекст на кожному ході. Повний текст підвантажується лише під час використання.
• Процеси. MCP-сервери плагіна працюють поруч із кожною сесією, а його hooks спрацьовують на своїх подіях.
• Права. Усе, що плагін запускає, він запускає від вашого імені. Hooks, монітори та сервери працюють поза sandbox — див. розділ «Обмеження та безпека».

Офіційні джерела: огляд плагінів, компоненти.

Усе, що можна покласти в плагін, працює й без нього. Тож правило просте: поки налаштування обслуговує один проєкт або лише вас — лишайте його у .claude/ чи ~/.claude/. Робіть плагін, коли треба роздати налаштування команді, поставити їх у кілька репозиторіїв або випускати версіями.

Особисте, проєктне чи плагін

Коли плагін — правильний вибір

Типові сценарії для Django/Vue-команди на GitLab

Плагін проходить шлях «маркетплейс → встановлення → кеш на диску → ввімкнення → завантаження компонентів у сесію → оновлення». Кожен крок змінює свій шар: налаштування, диск або запущену сесію — і розуміння цього шару пояснює більшість «чому плагін не працює».

Три шари: налаштування, диск, сесія

Де лежать файли

Корінь — ~/.claude/plugins (змінюється через CLAUDE_CODE_PLUGIN_CACHE_DIR). Шляхи нижче — відносно нього:

Звідки взявся плагін: суфікс ідентифікатора

У файлах налаштувань та в claude plugin list --json кожен плагін має id виду <name>@<origin>. Частина після @ каже, де Claude Code його знайшов:

Назви inline, skills-dir і synced зарезервовані — маркетплейс так називати не можна. Якщо збігаються назви плагінів із різних джерел, діє порядок: managed settings → --plugin-dir/--plugin-url → встановлений з маркетплейсу → skills-dir → synced.

Довіра й згода

• Код виконується від вашого імені. Правила permissions і sandbox стосуються викликів інструментів Claude, але не hooks, моніторів та MCP/LSP-процесів плагіна — вони працюють поза sandbox. Тож перегляньте плагін до встановлення (розділ «Обмеження та безпека»).
• Перед установкою ви бачите деталі. /plugin install name@marketplace у сесії нічого не ставить одразу — відкриває панель плагіна: що буде встановлено (команди, агенти, скіли, hooks, MCP/LSP-сервери), Context cost, вибір scope.
• Попередження про довіру показується для будь-якого маркетплейсу; адміністратор може дописати своє через pluginTrustMessage.
• Плагіни з командою встановлення (джерело command): Claude Code показує команду і питає Run this command now? [y/N]. У скриптах — --yes.
• Контент із репозиторію (проєктні extraKnownMarketplaces, проєктні плагіни в .claude/skills/) вантажиться лише після діалогу довіри до папки. Довіри до батьківської папки чи режиму -p недостатньо. MCP-сервери такого плагіна проходять те саме схвалення, що й проєктний .mcp.json; монітори не завантажуються.
• Три рівні маркетплейсів: офіційні (claude-plugins-official та ін.), спільнотні (claude-community) і сторонні — усе інше, зокрема маркетплейс вашої компанії. Назви перших двох груп приймаються лише з репозиторіїв github.com/anthropics/.

Докладніше: Plugin loading reference, Install and manage plugins, Plugin security and trust.

Плагінами керують двома способами: інтерактивною панеллю /plugin у сесії та командами claude plugin ... у shell (працюють без запуску сесії — зручно для скриптів і CI). Обидва змінюють одні й ті самі налаштування. Нижче — головне; компактну таблицю всіх команд дає розділ «Шпаргалка команд».

Панель /plugin

Меню деталей плагіна: Disable/Enable plugin, Update now, Uninstall, а для плагінів з налаштуваннями ще Configure options (поля userConfig) і Configure (налаштування вбудованого MCP-сервера). Плагіни зі scope Managed поставила ваша організація — їх тут не вимкнути й не видалити. Закриваючи панель із відкладеними змінами, Claude Code сам виконує /reload-plugins.

Команди /plugin у сесії

Працюють лише в інтерактивній сесії; у claude -p відповідь буде /plugin isn't available in this environment. Аліаси: /plugins, /marketplace.

Команди в shell

Усі підкоманди повертають код 0 при успіху й 1 при помилці (validate додає 2 для збою самого валідатора). claude plugins — синонім claude plugin. Плагін задається як name або name@marketplace (за однакових назв у двох маркетплейсах — лише з маркетплейсом; configure приймає тільки повну форму).

# маркетплейс компанії на GitLab (повний URL з https:// — не "gitlab.acme.example/group/repo")
claude plugin marketplace add https://gitlab.acme.example/platform/claude-plugins.git --scope project

# поставити плагін для всієї команди (запис у .claude/settings.json) і задати параметри без діалогу
claude plugin install acme-django@acme-plugins --scope project \
  --config gitlab_url=https://gitlab.acme.example

# тимчасово вимкнути лише для себе в цьому репозиторії
claude plugin disable acme-django@acme-plugins --scope local

# оновити, подивитися вартість і прибрати непотрібні залежності
claude plugin update acme-django@acme-plugins
claude plugin details acme-django
claude plugin prune --dry-run

Scope: хто отримує плагін

• Пріоритет: local > project > user; керовані налаштування організації переважують усе. Значення зливаються по ключу для кожного плагіна. Повний порядок джерел від нижчого до вищого: каталоги --add-dir (діє лише true) < user < project < local < --settings < managed.
• Відмовитись від проєктного плагіна на своїй машині: поставте false для нього в .claude/settings.local.json. Вимкнення в user settings не допоможе — проєктне true має вищий пріоритет (у списку буде Disabled in ~/.claude/settings.json but still loads).
• Видалення проєктного плагіна з панелі питає: y — «Disable for me» (пише false у settings.local.json), u — «Uninstall for everyone» (прибирає зі спільного файла).
• Термінал, локальні сесії десктопного застосунку й розширення VS Code на одній машині читають однакові файли налаштувань, тож user-плагін видно в усіх трьох. Хмарні сесії (claude.ai/code) локальні плагіни не завантажують.

Автооновлення, версії й закріплення

Плагін оновлюється сам, якщо в його маркетплейсу увімкнене автооновлення. Типові значення:

• Коли оновлює: у інтерактивній сесії після першого повідомлення, із випадковою затримкою до 10 хвилин. Запущена сесія лишається на завантажених версіях; ви побачите Plugin updated: <name> · Run /reload-plugins to apply, а наступний запуск візьме нове.
• Вимкнути все: DISABLE_UPDATES=1, DISABLE_AUTOUPDATER=1 або CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1; FORCE_AUTOUPDATE_PLUGINS=1 залишає оновлення плагінів попри вимкнений основний апдейтер.
• Вручну: «Update now» у деталях плагіна або claude plugin update name@marketplace. Команди «оновити все» немає; Update marketplace на вкладці Marketplaces оновлює всі плагіни цього маркетплейсу. Голе claude plugin marketplace update без імені лише оновлює списки, а встановлені плагіни лишає на місці.
• Як визначається версія (за нею Claude Code бачить, що оновлення є, і називає теку кешу): 1) version у plugin.json; 2) version у записі маркетплейсу; 3) інакше з джерела — 12 символів SHA коміту для github/url/git-subdir та відносного шляху у git-маркетплейсі, SHA-256 для archive, unknown для npm і локальних не-git каталогів.
• Закріплення (pinning): якщо в маніфесті є "version": "1.0.0", користувачі лишаються на кеші, поки автор не змінить цей рядок — скільки б комітів не було. Звідси <name> is already at the latest version попри нові коміти. Або піднімайте version у кожному релізі, або не вказуйте її взагалі (тоді версія = SHA коміту). Не вказуйте в обох місцях: тоді мовчки перемагає plugin.json. Додатково зафіксувати можна #v1.2.0 при marketplace add, ref/sha у записі маркетплейсу або діапазон ~2.1.0 у залежності.

/reload-plugins

/reload-plugins [--force] застосовує до поточної сесії все, що ви встановили, оновили, ввімкнули, вимкнули чи відредагували на диску. Виводить підсумок: Reloaded: N plugins · N skills · N agents · N hooks · N plugin MCP servers · N plugin LSP servers (плюс N errors during load. Run /plugin for details., якщо були помилки).

Офіційний маркетплейс і де шукати плагіни

• Корисні офіційні плагіни: plugin-dev (допомагає створювати плагіни: /plugin-dev:create-plugin), commit-commands, code-review, feature-dev, security-guidance та LSP-плагіни (наприклад, pyright-lsp для Python і typescript-lsp для TypeScript/JavaScript; потрібен ще й сам бінарний файл мовного сервера в PATH).
• Як шукати: вкладка Discover (з пошуком); /plugin install <name> за назвою; сайт Claude Marketplace на claude.com; файл .claude-plugin/marketplace.json у репозиторії маркетплейсу.
• Багато популярних плагінів немає в жодному маркетплейсі Anthropic — вони в репозиторіях авторів. Anthropic їх не перевіряє, тож перед додаванням прочитайте розділ «Обмеження та безпека».
• Демо-маркетплейс (anthropics/claude-code) дублює частину офіційних плагінів під тими самими назвами — ставте їх з офіційного, щоб не мати двох копій.

Скільки коштує плагін і чи ним користуються

• claude plugin details <name> показує склад плагіна й рядок Always-on — скільки токенів він додає до кожної сесії, а також частку кожного скілу чи агента (hooks і MCP-схеми там не рахуються; MCP-інструменти дивіться в /context).
• У панелі: Context cost (Every turn / When invoked) для плагінів офіційного маркетплейсу — рядок Every turn підсвічується від 2 000 токенів; Last used у деталях і група Not used recently на Installed.

Плагіни з акаунта claude.ai (id <name>@synced) синхронізуються у термінал при запуску, коли ви ввійшли через claude.ai. Видалити такий плагін можна лише вимкнувши його на claude.ai; плагіни, встановлені локально, на claude.ai не потрапляють. Докладніше: Install and manage plugins, Plugin commands reference.

Корінь плагіна — каталог, який ви передаєте в --plugin-dir (або який Claude Code копіює в кеш). Усе, крім маніфесту, лежить у корені, а не всередині .claude-plugin/. Додавайте лише ті теки, які потрібні, — жодна не обов’язкова.

acme-django/                          # корінь плагіна (= ${CLAUDE_PLUGIN_ROOT} після встановлення)
├── .claude-plugin/
│   └── plugin.json                   # маніфест — єдиний файл у цій теці
├── skills/
│   └── migration-check/
│       ├── SKILL.md                  # скіл → /acme-django:migration-check
│       └── reference.md              # допоміжні файли скілу
├── commands/
│   └── about.md                      # команда (старий формат) → /acme-django:about
├── agents/
│   └── security-reviewer.md          # субагент → acme-django:security-reviewer
├── hooks/
│   └── hooks.json                    # hooks (обгортка "hooks" обов’язкова)
├── .mcp.json                         # MCP-сервери → plugin:acme-django:<server>
├── .lsp.json                         # LSP-сервери (без обгортки)
├── monitors/
│   └── monitors.json                 # фонові монітори (масив)
├── output-styles/
│   └── terse.md                      # output style → acme-django:terse
├── themes/
│   └── dracula.json                  # тема для /theme
├── workflows/
│   └── release-audit.js              # workflow → /acme-django:release-audit
├── bin/
│   └── lint-report                   # виконуваний файл, на PATH Bash tool
├── scripts/
│   └── format.sh                     # лише конвенція: на скрипти посилаються hooks
├── evals/                            # кейси для claude plugin eval
├── settings.json                     # лише ключі agent і subagentStatusLine
├── package.json                      # якщо є й lockfile — залежності встановляться в кеш
└── package-lock.json

Що Claude Code не завантажує

• CLAUDE.md у корені плагіна. Він не стає контекстом проєкту, а claude plugin validate попереджає: CLAUDE.md at the plugin root is not loaded as project context. Інструкції для Claude оформлюйте як скіл.
• Усе в .claude-plugin/, крім plugin.json. Часта помилка — покласти туди skills/ (скіли «зникають»).
• .mcp.json у ~/.claude/: корінь плагіна — це його власна тека, а не ~/.claude/.
• Проєктна тека .claude/plugins/. Claude Code її не сканує. Щоб поділитись плагіном через репозиторій, внесіть його в enabledPlugins файла .claude/settings.json або покладіть у .claude/skills/<name>/ з власним .claude-plugin/plugin.json.
• Файли поза текою плагіна і symlink’и, що ведуть за її межі: шляхи, які виходять за корінь (../shared), відхиляються з помилкою path escapes plugin directory. Шляхи зі зворотними скісними рисками на macOS/Linux відхиляються теж — пишіть ./commands/deploy.md.

Плагін з одного скілу

Якщо в корені є SKILL.md, немає skills/ і немає ключа skills, плагін завантажується як один скіл. Обов’язково задайте name у frontmatter, інакше при установці з маркетплейсу скіл назветься за текою кешу. Саме так виглядає результат claude plugin init: кореневий скіл викликається як /my-tool (він також особистий скіл), а скіли в skills/ — як /my-tool:example.

bin/ на PATH

Поки плагін увімкнений, його bin/ потрапляє на PATH оболонки, у якій Bash tool виконує команди — тож Claude (або інструкція скілу) викликає утиліту за іменем, а користувачеві нічого ставити не треба. Теки плагінів стоять після ваших власних записів PATH, тому плагін не може підмінити git чи ls. Змінні ${CLAUDE_PLUGIN_ROOT} та ін. у середовищі команд Bash tool відсутні: в утиліті розраховуйте шлях від власного розташування, а в тексті скілу пишіть ${CLAUDE_PLUGIN_ROOT} — Claude Code підставить його при завантаженні. Запуск утиліти з bin/ — звичайний виклик Bash: на нього діють ваші правила permissions.

settings.json плагіна

{
  "agent": "security-reviewer"
}

• agent запускає головний потік сесії як агента плагіна: діють його системний промпт, обмеження інструментів і модель. subagentStatusLine задає рядок статусу субагентів. Будь-які інші ключі відкидаються.
• Той самий об’єкт можна вказати у полі settings маніфесту; якщо файл settings.json задає хоча б один підтримуваний ключ, він перемагає, а settings ігнорується.
• Налаштування плагіна — найнижчий шар: ваш власний agent у ~/.claude/settings.json його перекриває. Якщо два плагіни задали один ключ, діє той, що завантажений останнім (у claude --debug буде overrides setting).

Специфікація формату: Standard layout.

Маніфест — файл .claude-plugin/plugin.json. Він несе метадані, значення userConfig і оголошення компонентів, що лежать не за замовчуванням або описані прямо в JSON. Обов’язкове лише name. Невідомий ключ верхнього рівня відкидається (плагін вантажиться, а validate попереджає); невідомий ключ усередині userConfig, channels, lspServers чи monitors — помилка, плагін не завантажиться.

Усі поля

Назва плагіна

claude plugin validate перевіряє, що назва не видає себе за плагін Anthropic (регістр і роздільники ігноруються):

claude plugin init і claude plugin tag відмовляться від такої назви; сам Claude Code все одно встановить і завантажить плагін. Назва — постійна: від неї залежать усі префікси, тож змінювати її після релізу боляче.

Шляхи компонентів: додає чи замінює

• Кожен шлях у маніфесті — відносно кореня плагіна й мусить починатись з ./ (commands/foo.md не пройде валідацію). Винятки: skills приймає ".", mcpServers — https-URL бандла.
• Шлях має вести всередину кореня і існувати. Інакше: <component> path escapes plugin directory або <component> path not found на вкладці Errors.

Поле commands як об’єкт: ключ стає іменем команди після префікса плагіна, значення має рівно одне з source (шлях до .md) чи content (вбудований Markdown); необов’язкові description, argumentHint, model, allowedTools. Файл hooks, на який посилається hooks, мусить мати обгортку "hooks"; вбудований об’єкт у маніфесті — це одразу мапа подій без обгортки.

Реалістичний приклад

{
  "name": "acme-django",
  "displayName": "Acme Django Toolkit",
  "version": "1.4.0",
  "description": "Стандарти Django/DRF і Vue 3: review, перевірка міграцій, GitLab MCP",
  "author": {
    "name": "Acme Platform Team",
    "email": "platform@acme.example",
    "url": "https://gitlab.acme.example/platform"
  },
  "homepage": "https://gitlab.acme.example/platform/claude-plugins/-/tree/main/acme-django",
  "repository": "https://gitlab.acme.example/platform/claude-plugins.git",
  "license": "MIT",
  "keywords": ["django", "drf", "vue", "gitlab"],
  "dependencies": [
    "secrets-vault",
    { "name": "db-migrate", "version": "^3.0" }
  ],
  "skills": ["./extra-skills/"],
  "agents": ["./agents/security-reviewer.md", "./agents/vue-reviewer.md"],
  "hooks": "./config/extra-hooks.json",
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/gitlab-mcp.js"],
      "env": {
        "GITLAB_URL": "${user_config.gitlab_url}",
        "GITLAB_TOKEN": "${user_config.gitlab_token}"
      }
    }
  },
  "outputStyles": "./styles/",
  "experimental": {
    "monitors": "./config/monitors.json"
  },
  "userConfig": {
    "gitlab_url": {
      "type": "string",
      "title": "GitLab URL",
      "description": "Адреса вашого GitLab, напр. https://gitlab.acme.example",
      "required": true
    },
    "gitlab_token": {
      "type": "string",
      "title": "GitLab token",
      "description": "Personal access token зі scope read_api",
      "sensitive": true
    }
  }
}

Тут agents перелічує файли з типової теки — це замінює сканування, але без попередження, бо шляхи лежать усередині agents/. Теку skills/ Claude Code сканує й так, extra-skills/ додається до неї. Перевірте результат: claude plugin validate ./acme-django --strict. Як ці поля поєднуються із записом у marketplace.json (strict) — у розділі «Власний маркетплейс».

Довідка: Plugin manifest reference.

Кожен компонент має типову теку, необов’язковий ключ маніфесту, що її замінює чи доповнює, і назву, яку бачить користувач. Після додавання компонента виконайте /reload-plugins у відкритій сесії (або почніть нову), а файл перевірте claude plugin validate . з теки плагіна.

Скіли

Кожен скіл — окрема тека в skills/ із файлом SKILL.md. Формат і frontmatter — як у звичайних скілів (сторінка Скіли); у плагіні змінюється лише ім’я: /<plugin>:<тека>.

---
description: Перевіряє нові Django-міграції на зворотність і порядок залежностей. Використовуй, коли в diff є файли migrations/.
disable-model-invocation: true
---

Знайди нові файли в `*/migrations/` у поточній гілці.
Для кожної міграції перевір: є `reverse_code` у `RunPython`, немає `RunSQL` без `reverse_sql`,
залежності вказують на існуючі міграції. Запусти `${CLAUDE_PLUGIN_ROOT}/scripts/check_migrations.py`
і поясни кожну знахідку.

• У тілі скілу працює підстановка ${CLAUDE_PLUGIN_ROOT} та інших змінних плагіна (у Bash-командах Claude вони відсутні).
• Хто запускає скіл (Claude, користувач чи обидва), керується frontmatter, як у звичайних скілів.
• Додаткові теки: ключ skills додає їх до сканування skills/.
• Інструкції для Claude — тільки через скіл: CLAUDE.md плагіна не вантажиться. Правило, яке має виконуватись завжди, краще оформити як hook.

Команди

Команда — один Markdown-файл у commands/: commands/about.md → /acme-django:about, commands/db/migrate.md → /acme-django:db:migrate. Frontmatter той самий, що в скілів. Це старіший формат: скіл запускається так само й може мати допоміжні файли, тож нові речі пишіть скілами, а commands/ лишайте для перенесених з .claude/commands/.

Команду можна задати і прямо в маніфесті, без файла. Поле commands тоді замінює скан теки:

{
  "name": "acme-django",
  "commands": {
    "about": {
      "content": "Коротко опиши, що робить цей репозиторій (3 речення).",
      "description": "Опис репозиторію"
    },
    "status": {
      "source": "./commands/status.md",
      "argumentHint": "[env]"
    }
  }
}

Агенти

Кожен .md-файл в agents/ — субагент із власним промптом і вікном контексту. Ім’я — <plugin>:<name> (де name — з frontmatter, а за його відсутності — ім’я файла); явний виклик — @agent-acme-django:security-reviewer. Теки в agents/ вантажаться рекурсивно: agents/review/security.md → acme-django:review:security. Ключ agents замінює скан теки.

---
name: security-reviewer
description: Перевіряє зміни на проблеми безпеки. Використовуй після правок автентифікації, серіалізаторів DRF чи обробки введення.
model: sonnet
tools: Read, Grep, Glob
---

Ти — рецензент безпеки Django/DRF. Прочитай змінені файли й повідом про: SQL-ін’єкції у raw-запитах,
відсутні permission_classes, небезпечні serializer fields, секрети в коді.

• Агент не може додати власні hooks чи MCP-сервери — оголошуйте їх як hooks і MCP-сервери плагіна (вони діють, поки плагін увімкнений). Або скопіюйте агента в .claude/agents/ — там ці поля працюють.
• Якщо frontmatter не розбирається, агент усе одно завантажиться — з усіма ігнорованими полями, під ім’ям файла й описом Agent from my-plugin plugin. Такі файли знаходить claude plugin validate.
• У matcher’ах hooks для агента плагіна ставте прив’язку: ^acme-django:security-reviewer$.

Hooks

Hooks плагіна лежать у hooks/hooks.json під верхнім ключем "hooks" — формат такий самий, як hooks у settings, тож існуючий hook можна скопіювати без змін. Опційно додайте верхній ключ description. Hooks з файла й з поля hooks маніфесту завантажуються разом. Подія й типи handler’ів — на сторінці Hooks.

{
  "description": "Форматування Python/Vue після правок і захист від небезпечних Bash-команд",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\"" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3",
            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/check_command.py"]
          }
        ]
      }
    ]
  }
}

• Shell-форма і exec-форма. Без args command іде через оболонку — шлях із ${CLAUDE_PLUGIN_ROOT} беріть у подвійні лапки (як у першому hook), щоб шлях із пробілами лишився одним словом. З args (другий hook) команда запускається напряму, кожен елемент — окремий аргумент, лапки не потрібні.
• Середовище. Кожен процес hook отримує CLAUDE_PLUGIN_ROOT, CLAUDE_PLUGIN_DATA і CLAUDE_PROJECT_DIR, а також CLAUDE_PLUGIN_OPTION_<KEY> для кожного значення userConfig.
• Коли спрацьовують. Hooks реєструються при завантаженні плагіна й не чекають на виклик його скілів. Звужуйте за допомогою matcher.
• MCP-інструменти плагіна у matcher’і — повною назвою mcp__plugin_<plugin>_<server>__<tool>. Matcher лише з іменем сервера ніколи не спрацює.
• Файл мусить мати обгортку "hooks", а об’єкт, вбудований у маніфест, — без неї. Файл без обгортки не завантажиться.
• Якщо той самий hook лишився в settings, він спрацює двічі: у hooks немає префіксів.
• Модуль із JS-функціями-хуками (ключ modules у цьому ж файлі) робить плагін модом; моди не ізольовані sandbox і мають доступ до вашої сесії, тож ставте їх лише з довірених джерел.

MCP-сервери

Сервери оголошують у .mcp.json у корені, у форматі проєктного .mcp.json (обгортка mcpServers необов’язкова). У /mcp сервер з’явиться як plugin:acme-django:gitlab, а його інструменти називатимуться mcp__plugin_acme-django_gitlab__<tool> — саме цю назву вживайте в правилах permissions і matcher’ах hooks.

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/gitlab-mcp.js"],
      "env": {
        "GITLAB_URL": "${user_config.gitlab_url}",
        "GITLAB_TOKEN": "${user_config.gitlab_token}"
      }
    },
    "docs": {
      "type": "http",
      "url": "https://mcp.acme.example/docs",
      "headers": { "Authorization": "Bearer ${user_config.docs_token}" }
    }
  }
}

• У command, args і env підставляються змінні плагіна; в args лапки не потрібні. Для http/sse/ws-серверів змінні діють у url, headers, headersHelper.
• Ключ mcpServers маніфесту приймає вбудовану мапу, шлях до JSON-файла або масив таких; однойменний сервер із маніфесту замінює сервер із .mcp.json.
• Також приймається запакований сервер: "mcpServers": "./servers/db.mcpb" (файли .mcpb/.dxt, шлях або https-URL). Його власні обов’язкові налаштування вводять на вкладці Installed (Configure) або через claude plugin install --config <server>.<key>=<value> (v2.1.285+).
• Локальний stdio-сервер працює в Claude Code та Cowork на вашій машині, але не на claude.ai; для claude.ai вказуйте віддалений https-сервер.
• claude plugin validate перевіряє записи .mcp.json і повідомляє про ті, які Claude Code відкинув би (v2.1.281+); помилкою є й посилання ${user_config.KEY} на опцію, не оголошену в userConfig (у прикладі вище плагін має оголосити ще й docs_token).
• При /reload-plugins сервер із незмінною конфігурацією зберігає з’єднання, змінений — перепідключається, видалений — відключається.

LSP-сервери

LSP-сервер дає Claude діагностику після правок і навігацію по символах. Якщо для вашої мови є офіційний плагін (наприклад, pyright-lsp для Python чи typescript-lsp для TypeScript/JavaScript) — ставте його. Для Vue такого плагіна в офіційному списку немає: тоді пишіть власний .lsp.json зі своїм сервером. Формат файла: без обгортки, ім’я сервера → конфігурація.

{
  "pyright": {
    "command": "pyright-langserver",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".py": "python"
    }
  }
}

• Плагін налаштовує підключення, але сам сервер не ставить: бінарний файл має бути в PATH (інакше LSP server <name> failed to start).
• Одне розширення — один сервер: якщо два увімкнені сервери претендують на нього, працює перший, а на вкладці Errors буде попередження.
• Логи пишіть у stderr; stdout сервера — лише протокол (заголовок до 64 KiB, тіло до 32 MiB, інакше з’єднання розривається).
• claude plugin validate цей файл не читає; один невалідний запис призводить до пропуску всього файла (Invalid LSP server config for ".lsp.json"). У хмарних сесіях LSP-сервери плагінів не запускаються.

Output styles

Файл output-styles/<name>.md з frontmatter name і description (формат власних output styles) з’являється в /output-style як acme-django:terse. Ключ outputStyles замінює теку. Тільки для плагінів є поле force-for-plugin: true: стиль застосовується автоматично, коли плагін увімкнений, і перекриває outputStyle користувача (якщо таких плагінів кілька — перший завантажений).

---
name: terse
description: Короткі відповіді без вступів і підсумків
keep-coding-instructions: true
---

Відповідай коротко. Без вступів, без повторення питання, без підсумку наприкінці.

Workflows

Файли .js у workflows/: блок meta і скрипт, що оркеструє кількох субагентів. Запуск — /<plugin>:<meta.name> (тут /acme-django:audit-routes). Ключ workflows замінює теку. Докладніше про формат — документація workflows.

export const meta = {
  name: 'audit-routes',
  description: 'Перевірити всі DRF-в’юхи на відсутні permission_classes',
}

const found = await agent('Знайди всі файли views.py та viewsets.py у backend/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Перевір ${file}: чи в кожного view є permission_classes?`, { label: file }),
)

return audits.filter(Boolean)

Теми

Файл themes/<slug>.json у форматі власної теми Claude Code з’являється в /theme під своїм name з позначкою плагіна. Теми плагінів лише для читання: правка в /theme зберігається копією у вашій теці тем. Ключ — experimental.themes.

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

Монітори

Монітор — shell-команда, яку Claude Code запускає у фоні на початку сесії й тримає до кінця; її вивід приходить Claude як сповіщення, тож він реагує на лог чи зміну статусу без прохання стежити. Записи — в monitors/monitors.json:

[
  {
    "name": "django-error-log",
    "command": "tail -F ./logs/django-error.log",
    "description": "Помилки Django-сервера"
  },
  {
    "name": "pipeline-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-pipeline.sh",
    "description": "Зміни статусу пайплайна GitLab",
    "when": "on-skill-invoke:deploy"
  }
]

• Працює з повними правами користувача, поза sandbox.
• Тільки інтерактивні сесії (ніколи -p), і не там, де API-провайдер чи налаштування телеметрії роблять недоступним інструмент Monitor (зокрема Bedrock, Google Cloud, Foundry).
• У command діють змінні шляхів плагіна й ${ENV_VAR}, але не ${user_config.*} (такий монітор не запуститься), і процес не отримує CLAUDE_PLUGIN_OPTION_<KEY>.
• Вимкнення плагіна посеред сесії монітори не зупиняє — вони живуть до кінця сесії. Після оновлення плагіна нову версію монітора підхоплює лише перезапуск.
• Монітори плагіна, що прийшов з репозиторію (проєктний плагін у .claude/skills/), не завантажуються.

Решта: bin/, settings.json, канали

• bin/ і settings.json описані в розділі «Структура плагіна».
• Канали (channels у маніфесті): запис має обов’язкове server (ключ із mcpServers плагіна), необов’язкові displayName та userConfig (значення підставляються в env сервера). Канал дозволяє зовнішній системі, як-от чат-бот, надсилати повідомлення в сесію; на Team/Enterprise потрібен channelsEnabled.

Довідка: Add components to a plugin, Code intelligence plugins.

Плагіну часто потрібні значення від користувача: адреса GitLab, токен, тека проєкту. Замість того щоб просити редагувати settings.json, плагін оголошує їх у ключі userConfig — Claude Code покаже діалог. Ключі налаштувань, що стосуються плагінів (pluginConfigs тощо), описані на сторінці Налаштування → plugins; тут — те, що потрібно автору плагіна.

Поля userConfig

Ключ опції — ідентифікатор із літер, цифр і підкреслень, що не починається з цифри. Кожне значення — строгий об’єкт: невідоме поле — помилка, плагін не завантажиться.

{
  "userConfig": {
    "gitlab_url": {
      "type": "string",
      "title": "GitLab URL",
      "description": "Адреса вашого GitLab",
      "required": true
    },
    "gitlab_token": {
      "type": "string",
      "title": "GitLab token",
      "description": "Personal access token (scope read_api)",
      "sensitive": true
    },
    "review_tone": {
      "type": "string",
      "title": "Тон review",
      "description": "Як формулювати зауваження",
      "options": ["neutral", "strict", "mentoring"],
      "default": "neutral"
    },
    "max_files": {
      "type": "number",
      "title": "Ліміт файлів",
      "description": "Скільки файлів перевіряти за один запуск",
      "min": 1,
      "max": 200,
      "default": 50
    }
  }
}

Коли з’являється діалог і де зберігаються значення

• Діалог — частина інтерактивного /plugin: він відкривається для незаданих опцій під час установки в панелі, /plugin install <plugin>@<marketplace> у сесії або вмикання на вкладці Installed. У будь-який момент його можна відкрити командою /plugin configure <plugin>@<marketplace>. Розширення VS Code показує форму після установки (v2.1.285+).
• Не з’являється при завантаженні через --plugin-dir і при claude plugin install у shell. З shell: --config KEY=VALUE під час установки або claude plugin configure <plugin@marketplace> --values-stdin < values.json (JSON з рядковими значеннями) пізніше. Якщо опції лишились незаданими, install друкує N userConfig options not yet set.
• Кожна опція (крім sensitive і multiple) є рядком у панелі /config (v2.1.269+).
• Сховище: не секретні значення — у pluginConfigs користувацьких налаштувань; секретні — у сховищі облікових даних платформи (macOS Keychain; запасний варіант — файл ~/.claude/.credentials.json). Проєктні й локальні pluginConfigs ігноруються, щоб клонований репозиторій не підсунув значення.
• Видалення плагіна з останнього scope стирає й збережені опції та секрети.

Як компонент отримує значення

Змінні шляхів

• У командах, які Claude запускає через Bash tool (головна сесія чи субагент), цих змінних немає. Пишіть ${CLAUDE_PLUGIN_ROOT} у тексті скілу — Claude Code підставить шлях при завантаженні.
• Лапки. У shell-формі hook і в командах моніторів беріть змінну в подвійні лапки ("\"${CLAUDE_PLUGIN_ROOT}\"/scripts/x.sh" у JSON), інакше шлях із пробілами розпадеться; validate попереджає про незакриту лапками змінну в shell-формі hook (крім shell: "powershell"). В exec-формі (args) лапки не потрібні.
• На Windows підставлені шляхи мають прямі скісні риски (C:/Users/...), щоб shell не сприйняв зворотні як екранування.

Приклад: залежності в каталозі даних. Для плагіна з Node-залежностями при установці з маркетплейсу Claude Code сам ставить npm/Bun-пакети (якщо є package.json і package-lock.json / npm-shrinkwrap.json / bun.lock; тільки реєстрові пакети з точними версіями, без lifecycle-скриптів, ліміт 60 с; вимкнути не можна). Python-залежності, yarn/pnpm та пакети, що збираються в install-скриптах, ставте самі — hook на SessionStart кладе їх у ${CLAUDE_PLUGIN_DATA} і повторює після зміни файла залежностей:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/requirements.txt\" \"${CLAUDE_PLUGIN_DATA}/requirements.txt\" >/dev/null 2>&1 || (python3 -m venv \"${CLAUDE_PLUGIN_DATA}/venv\" && \"${CLAUDE_PLUGIN_DATA}/venv/bin/pip\" install -r \"${CLAUDE_PLUGIN_ROOT}/requirements.txt\" && cp \"${CLAUDE_PLUGIN_ROOT}/requirements.txt\" \"${CLAUDE_PLUGIN_DATA}/requirements.txt\") || rm -f \"${CLAUDE_PLUGIN_DATA}/requirements.txt\""
          }
        ]
      }
    ]
  }
}

Після першої сесії скрипти плагіна запускають ${CLAUDE_PLUGIN_DATA}/venv/bin/python. Якщо встановлення впало, копія файла видаляється, і наступна сесія спробує знову.

Залежності між плагінами

Поле dependencies каже, які плагіни мають бути ввімкнені, щоб цей працював. Запис — рядок "name" (в тому ж маркетплейсі), "name@marketplace" або об’єкт { "name", "version", "marketplace" }. Без обмеження версії залежність рухається за останнім релізом свого маркетплейсу — і якщо в ньому перейменують MCP-інструмент, що ви викликаєте, ваш плагін зламається в усіх, хто оновився.

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Стандартний набір плагінів для бекенд-інженерів",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

• Бандл для ролі. Плагін лише з name та dependencies — валідний; установка ставить усі залежності. Платформна команда публікує backend-standard і frontend-standard, а нова людина виконує одну команду. Щоб додати плагін у набір, випустіть нову версію бандла.
• Діапазон версій — semver-діапазон npm: ~2.1.0, ^2.0, >=1.4, =2.1.0. Залежність встановлюється з найвищого git-тега, що задовольняє діапазон. Пререлізи (2.0.0-beta.1) не підходять, якщо діапазон не має суфікса на кшталт ^2.0.0-0.
• Теги релізів мають вигляд <plugin-name>--v<version> (наприклад secrets-vault--v2.1.0) у репозиторії, на який вказує джерело плагіна: для github/url/git-subdir — власний репозиторій плагіна, для відносного шляху — репозиторій маркетплейсу. Створює тег claude plugin tag --push.
• Немає тега, що підходить: для плагіна з власним репозиторієм установка падає (has no git tag satisfying); для відносного шляху береться поточна копія маркетплейсу, а на завантаженні перевіряється діапазон — залежний плагін лишається вимкненим (Requires "x@m" ~2.1.0, installed 3.0.0).
• Кілька плагінів із різними діапазонами на одну залежність → найвища версія, що задовольняє всі; без перетину встановлення другого плагіна падає з has conflicting version requirements. =2.1.0 заморожує залежність, і автооновлення її не рухає.
• Для джерел npm, archive, command діапазон не керує тим, що завантажується, але перевіряється при завантаженні проти version у plugin.json залежності — задайте її там.
• Інший маркетплейс: без дозволу не встановлюється. Корінний маркетплейс має перелічити ціль у allowCrossMarketplaceDependenciesOn у marketplace.json (або користувач уже має залежність увімкненою в тому ж scope).
• Поведінка команд: install ставить залежності в тому ж scope; enable вмикає встановлені, але вимкнені (нестачу — помилка); disable відмовляє, поки на плагін спирається інший; uninstall залишає автоматично встановлені залежності до claude plugin prune.
• Локальна розробка: claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin — локальна копія задовольняє запис без установки й без version.

Довідка: Plugin dependencies, User configuration.

Маркетплейс для розробки не потрібен: плагін вантажиться просто з папки. Цикл такий: створити → завантажити → змінити → /reload-plugins → перевірити → протестувати → позначити версію.

Створення: claude plugin init

claude plugin init acme-tools --description "Командні інструменти" --with skills hooks
# ✔ Created plugin "acme-tools" at ~/.claude/skills/acme-tools
# It will auto-load next session as acme-tools@skills-dir. Run /reload-plugins to load it now.

• Плагін створюється в ~/.claude/skills/<name>/ (синонім команди — new) і вантажиться в кожній вашій сесії як <name>@skills-dir — без прапорців і установки. Зупинити: видалити теку або claude plugin disable <name>@skills-dir. Іншого місця прапорцем не задати.
• Для спільного репозиторію зробіть таку ж структуру вручну: <проєкт>/.claude/skills/<name>/.claude-plugin/plugin.json. Він вантажиться лише з .claude/skills/ основної робочої теки сесії і лише після діалогу довіри — з підтеки, де запущено Claude, плагін у корені репозиторію не підхопиться (запустіть з кореня або /cd).
• Хочете, щоб Claude допоміг спроєктувати й перевірити плагін? Поставте офіційний plugin-dev і запустіть /plugin-dev:create-plugin <опис>.

Те саме вручну (мінімальний плагін зі скілом):

mkdir -p acme-tools/.claude-plugin acme-tools/skills/hello
cat > acme-tools/.claude-plugin/plugin.json <<'EOF'
{ "name": "acme-tools", "description": "Мій перший плагін", "version": "0.1.0", "author": { "name": "Taras" } }
EOF
cat > acme-tools/skills/hello/SKILL.md <<'EOF'
---
name: hello
description: Привітатись з користувачем
disable-model-invocation: true
---
Привітай користувача й запитай, чим допомогти.
EOF
claude plugin validate ./acme-tools
claude --plugin-dir ./acme-tools      # у сесії: /acme-tools:hello

Завантаження без маркетплейсу

• Це «session-only» плагіни з id <name>@inline: нічого не пишеться в settings. Правите файли → /reload-plugins. Додавання й видалення підтек-плагінів у теці з плагінами підхоплюється під час сесії.
• Якщо назва збігається зі встановленим плагіном, перемагає завантажений прапорцем (мовчки; про це лише запис у debug-логу). Не хочете цього — "enabledPlugins": {"acme-tools@inline": false}. Плагіни, закріплені managed settings, прапорець не перекриє.
• Адміністратор може заборонити ці прапорці й змінну через disableSideloadFlags.
• Типова помилка: --plugin-dir на корінь маркетплейсу нічого не завантажує й не пише помилки. Вказуйте теку одного плагіна або додайте маркетплейс.
• claude plugin list показує такі плагіни лише якщо прапорець стоїть перед підкомандою: claude --plugin-dir ./acme-tools plugin list.

Перевірка: claude plugin validate

claude plugin validate ./acme-django            # ✔ Validation passed
claude plugin validate ./acme-django --strict   # попередження теж роблять збій
claude plugin validate ./acme-django --json     # звіт одним JSON-об’єктом (v2.1.259+)

• Перевіряє маніфест, frontmatter скілів/агентів/команд, JSON hooks, записи .mcp.json (v2.1.281+) та шляхи компонентів. Попередження: невідомі поля, назва не в kebab-case, відсутні version/description/author, CLAUDE.md у корені, нецитована ${CLAUDE_PLUGIN_ROOT} у shell-формі hook.
• Не читає: .lsp.json, SKILL.md у корені плагіна; з каталогу маркетплейсу не відкриває файли компонентів інших плагінів — перевіряйте кожен окремо. Symlink’и не розкриває.
• Що саме перевіряється в теці, залежить від вмісту: marketplace.json → plugin.json → компонентні теки (skills, agents, commands, .claude; v2.1.233+). Якщо є обидва маніфести, перевіряються обидва (v2.1.289+).
• Якщо ви свідомо не вказуєте version, не вживайте --strict: відсутність версії теж є попередженням.
• У сесії те саме робить /plugin validate <path>. Ідеальне місце для pre-commit та CI.

Налагодження

1. claude plugin validate <path> — синтаксис і схема.
2. /reload-plugins у сесії: має з’явитись рядок Reloaded: …; перевірте, що /acme-tools:hello існує.
3. /plugin → Installed (які компоненти знайдено) і Errors (що й чому не завантажилось, напр. commands path not found).
4. claude plugin list — секції Session-only/Skills-directory із Status: ✔ loaded або помилкою.
5. /mcp — стан MCP-сервера; для hooks спровокуйте подію й читайте debug-лог: claude --debug (лог у ~/.claude/debug/<session-id>.txt, у термінал не друкується) або claude --debug-file <path>; докладніші рядки — CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose.

• Скіли «зникли» → skills/ опинилась у .claude-plugin/ або запис skills веде на файл, а не теку.
• Hook не спрацьовує → регістр назви події, matcher, чи справді була така подія; файл без обгортки "hooks".
• Працює з --plugin-dir, але не після установки → посилання на файли поза плагіном, або шляхи без ${CLAUDE_PLUGIN_ROOT}.
• Діалог userConfig не з’являється → він є лише в /plugin; при --plugin-dir викличте /plugin configure <plugin-name>.
• Повний перелік повідомлень — розділ «Типові проблеми».

Локальний маркетплейс перед публікацією

claude plugin marketplace add ./my-marketplace
# ✔ Successfully added marketplace: my-marketplace (declared in user settings)
claude plugin install acme-django@my-marketplace
claude plugin list                    # Status: ✔ enabled
claude plugin details acme-django     # Skills (N) ...
claude plugin marketplace remove my-marketplace     # прибрати експеримент (разом з його плагінами)

Релізний тег: claude plugin tag

Створює анотований git-тег <name>--v<version>. Перед тим перевіряє плагін, що plugin.json і запис маркетплейсу збігаються за версією, що робоче дерево чисте і що тега ще немає.

claude plugin tag plugins/acme-django --dry-run   # лише показати план
claude plugin tag plugins/acme-django --push      # Created tag acme-django--v1.4.0 / Pushed to origin

claude plugin test [dir] запускає тести модів (плагінів із JS-хуками): усі файли *.test.ts / *.test.tsx у теці, без сесії й мережі; код виходу 1, якщо тест падає. Для звичайних плагінів тестуйте поведінку через eval.

Тести поведінки: claude plugin eval

Валідатор перевіряє файли, але не те, чи плагін справді спрямовує Claude. claude plugin eval (v2.1.269+) ганяє набір кейсів: кожен — реалістичний промпт плюс graders (автоматичні перевірки). Кожен кейс виконується (за замовчуванням 3 рази) у свіжій ізольованій неінтерактивній сесії, де завантажено лише ваш плагін, і ще стільки ж разів без плагіна — звіт показує WITH, W/OUT і різницю Δ. Якщо кейс проходить і без плагіна, значить, не плагін його «витягнув».

claude plugin eval init                  # інтерв’ю: Claude читає плагін, пропонує кейси й graders, пише evals/
claude plugin eval init --bare first-case   # порожній шаблон (для CI та середовищ без терміналу)
claude plugin eval .                     # усі кейси з evals/
claude plugin eval . --case migration-check --runs 1 --ablation none   # швидка ітерація, одна гілка

acme-django/
└── evals/
    ├── migration-check-fires/
    │   ├── prompt.md                # frontmatter: ліміти й інструменти; тіло: промпт
    │   └── graders/
    │       ├── criteria.md          # type: llm — рубрика для судді
    │       └── skill-fired.md       # type: tool_used, tool: Skill
    ├── ignores-unrelated/
    │   └── ...
    ├── mocks/                       # необов’язково: моки MCP-інструментів для всього набору
    └── results/                     # пишеться кожним запуском — додайте у .gitignore

---
max_turns: 10
allowed_tools: [Read, Glob, Grep, Skill]
---

Я додав у модель Order поле status і згенерував міграцію. Переглянь, чи міграція безпечна для відкату.

---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?migration-check"'
---

---
type: llm
---

PASS, якщо відповідь явно перевіряє зворотність міграції (reverse_code / reverse_sql) і перелічує знахідки.
FAIL, якщо відповідь загальна й не згадує зворотність або відкат.

• Промпт пишіть так, як його б написала людина, не називаючи скіл — інакше перевіряєте не опис, а ім’я. Робоча тека кожного запуску порожня; усе потрібне вкладайте в промпт або готуйте через case.yaml (context.scaffold_script, history_file, add_dirs).
• Кейс без жодного grader не завантажується. Оцінка запуску — частка пройдених graders (з вагами weight); оцінка кейса — середнє по запусках; кейс проходить, коли оцінка ≥ --threshold (за замовчуванням 1.0).
• Найтиповіша знахідка — Δ ≈ 0 і падаючий grader tool_used: Skill: Claude не обирає скіл на природне формулювання. Правте description скілу й запускайте знову.

• Спільні поля grader: type, weight (1), arm (with-only / both). Власних grader-ів із кодом немає.
• Що бачить grader (target для regex, focus для llm): last_message (за замовчуванням), trace (JSON по рядку на повідомлення; лапки екрануються), files (перелік створених шляхів, не вміст), { source: file, path: <path> } (вміст файла) та mock_calls.
• Перевірка «скіл спрацював» (tool_used: Skill) і graders по моках власних серверів плагіна у двогілковому прогоні не входять в оцінку — вони лише індикатори; примусово оцінювати можна через arm: both.
• Права: за замовчуванням дозволені лише читальні інструменти зі списку allowed_tools кейса. Bash, Write, Edit, WebFetch, WebSearch прибрані з сесії, доки ви не дасте --allow-tools Write Edit "Bash(npm test *)" (діє на всі кейси). Bash виконується під OS-sandbox; без sandbox-бекенду запуск відхиляється (Windows — через WSL2, Linux — потрібні bubblewrap і socat).
• MCP-сервери плагіна за замовчуванням не стартують: їх підміняють моки з evals/mocks/<server>/<tool>.md (тіло — відповідь, підстановки {{input.<field>}}, перевірка expect:). Реальні сервери — --allow-real-servers або --mocks off плюс --allow-tools "mcp__plugin_<plugin>_<server>__*".
• Ізоляція: тимчасові home/cwd/конфіг; ваші settings, hooks, CLAUDE.md, MCP, інші плагіни й пам’ять не завантажуються. Hooks та реальні сервери самого плагіна працюють поза sandbox, тож результати — орієнтовні, доки ви не ганяєте їх у контейнері чи на CI-раннері.
• Перший запуск на теці питає Trust this plugin directory?; без TTY і з --json запуск відхиляється, доки не передано --trust-plugin (тільки для плагінів, яким довіряєте).

У CI (офіційний рецепт; зверніть увагу — Δ ніколи не впливає на код виходу):

claude plugin eval . --trust-plugin --json results.json --threshold 0.8 \
  --model claude-sonnet-5 --judge-model claude-haiku-4-5 --no-publish --max-cost-usd 20

JSON-результат (schemaVersion: 1) містить aggregates.overallScore, casesPassed/casesTotal, meanDelta, cases[].aggregates.score/delta, partial/partialReason, costUsd. Частковий результат не включайте в графіки трендів.

plugin-checks:
  stage: test
  script:
    - claude plugin validate . --strict
    - claude plugin eval . --trust-plugin --json results.json --threshold 0.8 --ablation none --no-publish --max-cost-usd 20
  artifacts:
    when: always
    paths: [results.json, evals/results/]
  # Claude Code має бути встановлений в образі, а ANTHROPIC_API_KEY — masked CI/CD variable

Перенесення існуючого .claude/ у плагін

1. mkdir -p my-plugin/.claude-plugin і plugin.json з name, description, version.
2. cp -r .claude/commands .claude/agents .claude/skills my-plugin/ (лише ті теки, що є).
3. Перенесіть об’єкт hooks із .claude/settings.json у my-plugin/hooks/hooks.json в обгортці {"hooks": {...}} — формат той самий.
4. claude --plugin-dir ./my-plugin і перевірте: скіл /deploy став /my-plugin:deploy, агент reviewer — my-plugin:reviewer, hooks спрацьовують.
5. Видаліть оригінали з .claude/ і hooks зі settings: поки вони є, скіли й агенти існують у двох іменах, а hooks виконуються двічі.

Довідка: Create a plugin, Plugin commands reference, Test plugins with evals, Measure plugin cost and usage.

Маркетплейс — це каталог плагінів: один файл marketplace.json, який каже Claude Code, які плагіни існують і звідки кожен із них завантажувати. Це може бути git-репозиторій (наприклад, на вашому self-hosted GitLab), URL до готового JSON-файлу або тека на спільному диску. Користувач реєструє каталог один раз (marketplace add) і далі встановлює з нього плагіни як plugin@marketplace.

Файл лежить у .claude-plugin/marketplace.json. Тека, що містить .claude-plugin/, — корінь маркетплейсу; усі відносні шляхи плагінів рахуються від нього, а не від .claude-plugin/. Якщо файл лежить деінде в репозиторії, користувачі мусять оголосити маркетплейс у extraKnownMarketplaces із полем path (команда marketplace add такої опції не має). Кожен користувач може мати лише один маркетплейс з певною name.

Мінімальний каталог

{
  "name": "acme-tools",
  "owner": { "name": "Acme Platform Team", "email": "platform@acme.example" },
  "description": "Командні плагіни Claude Code для Django/Vue",
  "plugins": [
    {
      "name": "acme-django-vue",
      "source": "./plugins/acme-django-vue",
      "description": "Міграції Django, рев’ю, лінтинг, GitLab MCP",
      "category": "development",
      "tags": ["django", "vue", "gitlab"]
    }
  ]
}

Повний робочий приклад із плагіном усередині — у розділі «Приклад».

Поля верхнього рівня

Обов’язкові: name, owner, plugins.

Поля запису плагіна

Обов’язкові: name і source. Крім перелічених, запис приймає будь-яке поле plugin.json (author, commands, hooks, mcpServers …), але не «directory listing» поля (icon, documentationUrl, supportUrl, privacyPolicyUrl, termsOfServiceUrl) — їх задають тільки в plugin.json.

Відображувані поля (displayName, description, author, homepage, repository, license, keywords) можна задати і в записі, і в plugin.json: якщо запис їх задав — користувач бачить значення запису, інакше — з plugin.json. До встановлення plugin.json можна прочитати лише для записів із відносним шляхом; для решти типів джерел видно тільки поля запису.

Строгий режим (strict)

Якщо у плагіна немає власного plugin.json, запис сам є маніфестом незалежно від strict (діють усі поля, зокрема mcpServers, lspServers, userConfig, channels). Якщо plugin.json є, він — маніфест, а strict вирішує, що робити з компонентними полями запису (commands, agents, skills, hooks, outputStyles, themes). Поля mcpServers, lspServers, userConfig, channels у записі при наявному plugin.json не діють — оголошуйте їх у plugin.json.

Типи джерел плагіна (source)

source запису — або рядок (відносний шлях), або об’єкт, де поле source називає тип. Імена url і github зустрічаються й серед джерел маркетплейсу, але мають там інший зміст (див. нижче).

Спільні для github, url, git-subdir: ref — гілка чи тег (за замовчуванням — типова гілка репозиторію); sha — повний 40-символьний commit SHA малими літерами. Якщо задано обидва, береться sha: установка спрацює, навіть якщо гілку/тег потім видалили (на GitHub, GitLab, Bitbucket; деякі сервери на кшталт AWS CodeCommit не вміють видавати коміт за SHA).

Відносний шлях. Підходить для плагіна в тому ж репозиторії, що й каталог. Розв’язується лише тоді, коли Claude Code має файли маркетплейсу (джерела github, git, file, directory); для маркетплейсу-url відносні шляхи не працюють, для settings — відхиляються. У macOS/Linux зворотний слеш у шляху відхиляється.

{ "name": "acme-django-vue", "source": "./plugins/acme-django-vue" }

З metadata.pluginRoot (v2.1.239+) можна писати «голі» імена; шлях із / усе одно потребує ./:

{
  "name": "acme-tools",
  "owner": { "name": "Acme Platform Team" },
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [ { "name": "acme-django-vue", "source": "acme-django-vue" } ]
}

github — із фіксацією на тег і коміт:

{
  "name": "formatter",
  "source": {
    "source": "github",
    "repo": "your-org/formatter",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

url — повний git URL (https://, http://, file:// або git@); суфікс .git не обов’язковий; скорочення owner/repo тут не працює. Окремий репозиторій плагіна на GitLab:

{
  "name": "acme-django-vue",
  "source": {
    "source": "url",
    "url": "https://gitlab.example.com/platform/acme-django-vue.git",
    "ref": "v1.0.0"
  }
}

git-subdir — підтека монорепо; url приймає повний URL або GitHub owner/repo. Через https/SSH Claude Code просить у сервера partial clone, тож плагін із великого монорепо не тягне решту репозиторію:

{
  "name": "acme-django-vue",
  "source": {
    "source": "git-subdir",
    "url": "https://gitlab.example.com/platform/monorepo.git",
    "path": "tools/claude/acme-django-vue",
    "ref": "main"
  }
}

npm — package (ім’я, ім’я@версія або https-посилання на tarball), version (версія, діапазон semver або dist-tag; без нього береться latest), registry (https, якщо не реєстр за замовчуванням). Відхиляються git-адреси, шляхи file:, aliases npm:, tarball-посилання на github.com / gist.github.com / gitlab.com / bitbucket.org / git.sr.ht (виняток — npm-реєстр GitLab за gitlab.com/api/v4/) та http-tarball, окрім власного реєстру користувача.

{
  "name": "formatter",
  "source": {
    "source": "npm",
    "package": "@your-org/formatter",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

archive — zip по https:// (не на loopback, link-local чи cloud-metadata хости); корінь плагіна — у корені архіву або на один рівень глибше. Із sha256 (64 hex-символи) Claude Code відхиляє файл, що не збігається. Зручно для користувачів без акаунта в git-хостингу.

{
  "name": "formatter",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/formatter-2.0.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

command — для плагінів, які генерує встановлений на машині інструмент (наприклад, IDE). Команда виконується через sh (на Windows — cmd.exe) з домашньої теки при встановленні, оновленні та раз на сесію; вона має надрукувати одним рядком абсолютний шлях до теки плагіна й завершитися з кодом 0. Команду показують користувачу й просять підтвердити (--yes у скриптах). Адміністратор може вимкнути такі джерела ключем disableCommandPluginSources.

{
  "name": "formatter",
  "source": {
    "source": "command",
    "command": "my-tool claude-plugin-path",
    "timeout": 120
  }
}

Типи джерел маркетплейсу

Джерело маркетплейсу каже, звідки брати сам marketplace.json. Його будує marketplace add або ви пишете в extraKnownMarketplaces; адміністратори використовують ті самі об’єкти в allowlist/blocklist. Імена url, git, github мають тут інший зміст, ніж у джерелах плагінів: маркетплейс-url — це пряме посилання на JSON-файл (git-репозиторій він не клонує), а git існує тільки як джерело маркетплейсу.

path для github/git — розташування файлу в репозиторії (типово .claude-plugin/marketplace.json). sparsePaths — масив тек для sparse checkout (--sparse у CLI). Для file корінь маркетплейсу — тека на два рівні вище файлу, тож тримайте його як <root>/.claude-plugin/marketplace.json. Приклад у settings:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "git",
        "url": "https://gitlab.example.com/platform/acme-claude-plugins.git",
        "ref": "main"
      }
    }
  }
}

Усі параметри ключа — на сторінці settings: extraKnownMarketplaces.

Приватний маркетплейс на self-hosted GitLab

Репозиторій з каталогом — звичайний git-проєкт. Рекомендована схема для команди: marketplace.json у корені репозиторію і плагіни у plugins/<name>/ з відносними шляхами. Тоді все, що потрібно, клонується одним запитом, а доступ до плагінів дає доступ до самого репозиторію.

acme-claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   ├── acme-django-vue/
│   │   ├── .claude-plugin/plugin.json
│   │   └── skills/ …
│   └── acme-release-tools/
│       └── …
└── README.md

Як користувачі додають маркетплейс

Хост, чиї clone-URL не мають суфікса .git (наприклад, AWS CodeCommit), додають як git-запис у extraKnownMarketplaces — тоді URL клонується як є. Після успішного додавання Claude Code пише Successfully added marketplace: acme-tools; ім’я береться з поля name у marketplace.json, а не з назви репозиторію.

Автентифікація до приватного репозиторію

У marketplace.json немає поля для токена, і сам Claude Code git-токена не має. Він запускає git на машині користувача без інтерактивних запитів і покладається на облікові дані, які там уже є. Тому кожен розробник має заздалегідь налаштувати доступ.

Користувачам без акаунта в GitLab (підрядники, CI-образи) підійдуть: джерела archive (потрібен лише HTTPS-доступ до URL), публічні git-репозиторії, directory-маркетплейс на спільному диску або seed-тека. Для GitHub-репозиторію з owner/repo є CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 (клонувати по HTTPS замість SSH); для GitLab потреби в ньому немає, бо ви все одно даєте повний URL.

Версії, теги й оновлення

Користувач отримує нову копію плагіна лише тоді, коли змінюється його обчислена версія. Порядок: version у plugin.json → version у записі маркетплейсу → ознака з типу джерела.

• Задали version (наприклад, 1.0.0) і запушили нові коміти без зміни рядка — користувачі нічого не отримають. Піднімайте версію з кожним релізом.
• Не задавали version — користувачі йдуть за комітами (кожен новий коміт = нова версія).
• Не задавайте version одночасно в plugin.json і записі: перемагає plugin.json без попередження (validate покаже розбіжність).
• Теги релізів: <plugin>--v<version>. Створює їх claude plugin tag --push (перевіряє, що версії в plugin.json і записі збігаються, робоче дерево чисте, тег ще не існує). Теги потрібні, щоб залежності з діапазоном версій (^2.0) мали проти чого розв’язуватися.
• Закріпити користувачів на версії: ref/sha у джерелі плагіна, або #ref у команді додавання маркетплейсу (…git#stable).
• Плагіни з відносним шляхом у маркетплейсі, доданому з локального шляху, вантажаться «на місці» й не залежать від version — зміни видно в наступній сесії чи після /reload-plugins.

Автооновлення для сторонніх маркетплейсів вимкнене за замовчуванням, і в marketplace.json поля для його вмикання немає. Увімкнути можна так: користувач — /plugin → Marketplaces → маркетплейс → Enable auto-update; адміністратор — "autoUpdate": true у managed-записі extraKnownMarketplaces. Без нього зміни приходять після /plugin marketplace update <name> та claude plugin update <plugin>@<name>. Фонова перевірка приватного репозиторію використовує ті самі git-облікові дані без запитів; якщо credential helper мусить питати, оновлення тихо не відбудеться, а наявна копія лишиться. В інтерактивній сесії автооновлення стартує після першого повідомлення з випадковою затримкою до десяти хвилин; запущена сесія зберігає завантажені версії й показує Plugin updated: … Run /reload-plugins to apply.

Канали стабільний/ранній доступ. У Claude Code немає поняття каналів: створіть два маркетплейси з різними name (stable-tools, latest-tools), чиї записи вказують на різні ref того самого плагіна, і давайте командам потрібний. Версії на цих ref мають відрізнятися (або не задавайте version).

Перейменування й видалення плагінів

name плагіна — його ідентифікатор у enabledPlugins, pluginConfigs та /plugin install, тож зміна ламає наявні встановлення. Щоб змінити лише підпис у UI, міняйте displayName. Якщо ім’я змінити мусите — додайте renames:

{
  "name": "acme-tools",
  "owner": { "name": "Acme Platform Team" },
  "forceRemoveDeletedPlugins": true,
  "plugins": [
    { "name": "acme-django-vue", "source": "./plugins/acme-django-vue" }
  ],
  "renames": {
    "django-helpers": "acme-django-vue",
    "legacy-linter": null
  }
}

• Перейменований запис: плагін завантажується під новим ім’ям, один раз показується Renamed to "…" in the "…" marketplace, а Claude Code переписує старий ключ на новий в enabledPlugins і pluginConfigs у user/project/local. Managed-settings він переписати не може — нагадування повторюватиметься, доки адмін не оновить enabledPlugins. Для git/URL-маркетплейсів користувач одноразово виконує /plugin install acme-django-vue@acme-tools (інакше Plugin "…" not cached at …).
• null: старий ключ видаляється, користувач бачить Removed from the "…" marketplace.
• renames — «лише додавати»: після повного переходу старі рядки не видаляють; при новому перейменуванні додають ще один рядок (ланцюжок іде від найстарішого імені). claude plugin validate . відхиляє цикли та ланцюжки, що не завершуються на null або імені з plugins (renames.<name>: chain does not resolve).
• forceRemoveDeletedPlugins: true: на кожному старті сесії плагіни, яких немає ні в plugins, ні в renames, видаляються з user/project/local (встановлені лише через managed — лишаються) і показуються в /plugin під заголовком Flagged зі статусом Removed from marketplace. Без поля видалений запис лишається встановленим і скаржиться Plugin "…" not found in marketplace.

Залежності між маркетплейсами

За замовчуванням залежність з іншого маркетплейсу не ставиться (якщо користувач сам не встановив її на тому ж scope): це захист від мовчазного встановлення з неперевіреного джерела. Щоб дозволити, перелічіть ім’я цільового маркетплейсу в allowCrossMarketplaceDependenciesOn кореневого маркетплейсу (того, звідки встановлюють плагін); діє лише його список, на весь ланцюг залежностей.

{
  "name": "acme-tools",
  "owner": { "name": "Acme Platform Team" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "acme-release-tools",
      "source": "./plugins/acme-release-tools",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}

Якщо поля немає чи цільовий маркетплейс у ньому не названий: залежність із запису маркетплейсу — встановлення відхиляється повідомленням … is in marketplace "…", which is not in the allowlist; залежність із plugin.json — установка завершується без неї, і плагін не завантажується. Діапазон version у залежності (^2.0, ~2.1.0) розв’язується проти git-тегів <plugin>--v<version>; для npm/archive/command діапазон лише перевіряється під час завантаження за version у plugin.json. Пакетний плагін (лише name + dependencies) зручний для ролей: «backend-standard» ставить усе потрібне однією командою.

Маркетплейс як URL, спільна тека, Git LFS, симлінки

• Hosted marketplace.json за URL: Claude Code завантажує лише цей файл (до 5 MiB, відповідь протягом 10 с, редирект на інший origin лише по https). Відносні шляхи в записах не працюють (its marketplace entry path does not stay inside the marketplace directory) — давайте кожному запису самодостатнє джерело (github, url, archive …) або тримайте каталог у git-репозиторії.
• Спільна тека (/plugin marketplace add /Volumes/shared/claude-plugins): плагіни з відносними шляхами читаються прямо звідти, правки видно з наступної сесії чи /reload-plugins без підняття версії.
• Git LFS: клон не завантажує LFS-вміст, файли лишаються pointer-файлами — не кладіть файли плагіна в LFS.
• Симлінки в плагіні: усередині теки плагіна зберігаються; на інше місце того ж маркетплейсу — розіменовуються (вміст копіюється в кеш); за межі маркетплейсу — пропускаються. Для локальних шляхів і command у режимі copy зберігаються лише внутрішні посилання.
• Організаційна синхронізація: на планах Team/Enterprise каталог можна роздавати через Organization settings → Plugins & skills на claude.ai (через GitHub/GitLab-з’єднання організації, без git-облікових даних користувачів). Репозиторій на github.com/gitlab.com має бути private/internal, приймаються не всі типи джерел, а плагін із верхньорівневим bin/ claude.ai відхиляє (тримайте виконувані файли в scripts/).

Зарезервовані імена маркетплейсу

Зареєстрований маркетплейс із забороненим іменем перестає завантажуватися разом із плагінами; claude plugin list і /plugin пишуть Claude Code refuses the marketplace name "…" — вилучення маркетплейсу також видалить його плагіни та їхні збережені дані. Claude Desktop додатково відхиляє імена org, org-provisioned, unknown та імена довші за 128 символів (validate попереджає). Тримайте імена плагінів у kebab-case.

Команди marketplace

У сесії те саме: /plugin marketplace add|list|update|remove (псевдоніми /plugin market …, /plugins, /marketplace). Повна шпаргалка — у розділі «Шпаргалка команд».

Є два рівні роздачі плагінів. Репозиторій (.claude/settings.json у проєкті) — для команди, що працює над одним кодом. Managed settings — для всієї компанії, коли політику не можна обійти. Обидва використовують пару ключів: extraKnownMarketplaces реєструє маркетплейс, enabledPlugins вмикає плагіни (plugin@marketplace).

1. Проєктні налаштування (.claude/settings.json)

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "git",
        "url": "https://gitlab.example.com/platform/acme-claude-plugins.git",
        "ref": "main"
      }
    }
  },
  "enabledPlugins": {
    "acme-django-vue@acme-tools": true
  }
}

Те саме можна отримати командою claude plugin marketplace add <url> --scope project (вона й запише extraKnownMarketplaces у .claude/settings.json) та claude plugin install … --scope project; результат закомітьте. Що саме станеться в колеги після git pull:

• Відмовитись особисто: вимкнення в ~/.claude/settings.json не допоможе (проєктне true сильніше). Запишіть "acme-django-vue@acme-tools": false у .claude/settings.local.json — він має вищий пріоритет. У /plugin → Uninstall для плагіна, який вмикає проєкт, питає: y — вимкнути лише для себе (запише false у local), u — видалити з спільного settings.json для всіх.
• Пріоритет enabledPlugins: --add-dir < user < project < local < --settings < managed. Для кожного id перемагає значення з найвищого джерела, яке його згадує; у managed true примусово вмикає, false блокує.
• Локальне directory/file-джерело з відносним шляхом розв’язується від головного checkout; у git worktree шлях усе одно вказує на головний checkout.
• Набір для ролі: опублікуйте пакетний плагін (лише name + dependencies) і вмикайте тільки його — решта встановиться як залежності.
• Плагіни, закомічені в .claude/skills/ репозиторію (skills-dir, project scope): вантажаться лише після workspace trust; їхні MCP-сервери проходять той самий покроковий approval, що й проєктний .mcp.json; MCPB-бандли та MCP-файли поза текою плагіна пропускаються; монітори не вантажаться.

2. Managed-роздача на всю компанію

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "git",
        "url": "https://gitlab.example.com/platform/acme-claude-plugins.git"
      },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "acme-django-vue@acme-tools": true
  }
}

На відміну від репозиторію, managed extraKnownMarketplaces + enabledPlugins справді встановлюють плагіни на початку наступної сесії користувача (для будь-якого типу джерела). Користувач бачить їх у /plugin, але вимкнути не може: managed має вищий пріоритет за всі scope, а false блокує плагін усюди й ховає з каталогу. Managed-запис маркетплейсу повністю замінює однойменний із нижчого рівня (поля не зливаються). autoUpdate у managed-записі закріплює політику: спроба вимкнути перемикач у /plugin завершується помилкою Auto-update for '…' is set by …. Якщо приватний каталог — користувачам усе одно потрібен git-доступ.

За замовчуванням діє лише одне джерело: перше, що доставляє ключ політики (server → MDM → файл). Якщо server-managed доставляє бодай один сторонній ключ, плагінні ключі з MDM чи файлу на тій машині ігноруються; щоб застосувати всі джерела, задайте managedSourcesBehavior: "merge". Різні канали для різних груп (stable/latest) — окремі endpoint-managed налаштування або політики шлюзу Claude apps.

CI та контейнери

• У claude -p/CI маркетплейси й плагіни встановлюються у фоні, тому плагіна може не бути на першому ході. CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1 змушує чекати встановлення (обмежити очікування — CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS; CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH=1 оновлює стан плагінів на межах ходів після фонового встановлення).
• Seed-тека для образів без доступу до git: під час збірки CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add … та … claude plugin install …; у рантаймі CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed (кілька — через :, на Windows ;). Seed лише для читання, autoUpdate примусово вимкнений, його записи перекривають однойменні користувацькі; marketplace update/remove дають is seed-managed. Плагіни з seed треба ще й увімкнути через enabledPlugins. Політика (allowlist/blocklist) застосовується і до seed.
• Перевірити: на машині — /plugin; у CI — claude -p --output-format stream-json --verbose, у події init є список plugins; для seed шляхи плагінів починаються з seed-теки.
• Без вихідного git: seed + маркетплейс directory/file на спільному диску + CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 (також вимикає автооновлення плагінів).

3. Політики обмеження

Параметри ключів описані на сторінці settings — тут лише огляд. enabledPlugins і extraKnownMarketplaces діють з будь-якого рівня, pluginConfigs — з user або managed, syncClaudeAiPlugins — з user/local/managed; решта ключів працює лише з managed settings.

Приклад «дозволити лише наш GitLab і офіційний маркетплейс»:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "hostPattern", "hostPattern": "^gitlab\\.example\\.com$" },
    { "source": "skills-dir" }
  ],
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": { "source": "github", "repo": "anthropics/claude-plugins-official" }
    },
    "acme-tools": {
      "source": { "source": "git", "url": "https://gitlab.example.com/platform/acme-claude-plugins.git" }
    }
  },
  "enabledPlugins": { "acme-django-vue@acme-tools": true },
  "disableSideloadFlags": true
}

• Будь-який allowlist без запису {"source": "skills-dir"} мовчки вимикає плагіни зі skills-директорій (.claude/skills/ із .claude-plugin/plugin.json); звичайні скіли без маніфесту працюють.
• hostPattern — регулярний вираз, що збігається будь-де в імені хоста, тож обмежуйте його якорями ^…$; у JSON крапку екранують як \\.. Для GitLab, де розробники створюють власні маркетплейси, це зручніше, ніж точні URL (форми .git, ssh://, слеш у кінці — різні значення).
• Allowlist ніяк не реєструє маркетплейс — для цього потрібні явні записи в extraKnownMarketplaces, які мають самі пройти allowlist. Офіційний маркетплейс сам реєструється лише в інтерактивному терміналі й лише якщо політика дозволяє.
• Політика застосовується до завантаження й при кожному старті: встановлений плагін із маркетплейсу, що більше не підпадає під allowlist, не завантажується (Marketplace "…" is not in the allowed marketplace list).
• Окремих ключів немає для: політики по групах (використовуйте окремі endpoint-налаштування чи шлюз), обмеження окремих записів усередині дозволеного маркетплейсу (ставте їм false у managed enabledPlugins), приховування /plugin.
• Аудит: OpenTelemetry-події claude_code.plugin_installed і claude_code.plugin_loaded (імена сторонніх плагінів редагуються без OTEL_LOG_TOOL_DETAILS=1), Analytics API на Enterprise, /status → Enterprise managed settings у Setting sources.

Onboarding нового розробника

1. Налаштувати доступ до GitLab без запитів: SSH-ключ в ssh-agent + ssh -T git@gitlab.example.com один раз, або PAT у git credential helper; перевірити git ls-remote https://gitlab.example.com/platform/acme-claude-plugins.git.
2. Клонувати проєкт, запустити claude у корені репозиторію і прийняти workspace trust dialog.
3. Дочекатися фонового клонування каталогу; за повідомленням Plugins changed. Run /reload-plugins to activate. виконати /reload-plugins.
4. Якщо плагін із зовнішнім джерелом — виконати у shell claude plugin install acme-django-vue@acme-tools --scope project.
5. Ввести значення userConfig (URL GitLab, токен) у діалозі або /plugin configure acme-django-vue@acme-tools.
6. Перевірити: claude plugin list (статус enabled), у сесії / показує /acme-django-vue:…, /mcp — сервер plugin:acme-django-vue:gitlab.
7. Ввімкнути автооновлення маркетплейсу в /plugin → Marketplaces (якщо його не задано політикою).

Сценарій: платформна команда Acme веде Django-бекенд і Vue-фронтенд у self-hosted GitLab. Вона публікує репозиторій-каталог acme-claude-plugins з одним плагіном acme-django-vue: скіл для міграцій, агент-рев’юер, хук лінтингу після правок та два MCP-сервери (GitLab, Sentry).

Дерево репозиторію

acme-claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   └── acme-django-vue/
│       ├── .claude-plugin/
│       │   └── plugin.json
│       ├── skills/
│       │   └── django-migrations/
│       │       ├── SKILL.md
│       │       └── checklist.md
│       ├── agents/
│       │   └── code-reviewer.md
│       ├── hooks/
│       │   └── hooks.json
│       ├── scripts/
│       │   └── lint-after-edit.sh
│       ├── .mcp.json
│       └── README.md
└── README.md

У .claude-plugin/ лежить тільки plugin.json; усі компоненти — у корені плагіна. CLAUDE.md у корені плагіна не завантажується — інструкції живуть у скілі.

plugin.json

{
  "name": "acme-django-vue",
  "displayName": "Acme Django + Vue",
  "version": "1.0.0",
  "description": "Міграції Django, рев’ю, лінтинг після правок, GitLab і Sentry MCP",
  "author": { "name": "Acme Platform Team", "email": "platform@acme.example" },
  "homepage": "https://gitlab.example.com/platform/acme-claude-plugins",
  "keywords": ["django", "vue", "gitlab"],
  "userConfig": {
    "gitlab_url": {
      "type": "string",
      "title": "GitLab URL",
      "description": "Адреса інстансу GitLab",
      "default": "https://gitlab.example.com"
    },
    "gitlab_token": {
      "type": "string",
      "title": "GitLab token",
      "description": "Personal access token з правом read_api",
      "sensitive": true,
      "required": true
    }
  }
}

version задано лише тут (не в записі маркетплейсу): користувачі оновлюються, коли ви піднімаєте цей рядок. Ключі userConfig — літери, цифри, підкреслення. sensitive: true маскує введення й зберігає значення в захищеному сховищі системи, а не в settings.json.

Скіл django-migrations

---
name: django-migrations
description: Створює та перевіряє міграції Django. Use when a task changes models.py, adds a field, or the user asks about migrations, makemigrations, or schema changes.
allowed-tools: Bash(python manage.py makemigrations *) Bash(python manage.py sqlmigrate *) Read Grep
---

# Міграції Django

1. Після змін у `models.py` запусти `python manage.py makemigrations --dry-run -v 3`
   і покажи, що саме буде створено.
2. Для полів `NOT NULL` без default — роби в три кроки: nullable → data migration → NOT NULL.
3. Перед завершенням переглянь SQL: `python manage.py sqlmigrate <app> <номер>`.
4. Не редагуй уже застосовані міграції; не змінюй чужі файли в `migrations/`.

Деталі й типові пастки — у [checklist.md](checklist.md).

Команда скілу буде /acme-django-vue:django-migrations; Claude може викликати його й сам за описом. Рядок allowed-tools дозволяє перелічені команди без запиту лише на час ходу, у якому викликано скіл.

Агент code-reviewer

---
name: code-reviewer
description: Рев’ю змін у Django-бекенді та Vue-компонентах. Use after finishing a feature or before opening a merge request.
model: sonnet
tools: Read, Grep, Glob, Bash
maxTurns: 15
---

Ти рев’юер коду команди Acme. Перевір зміни (`git diff main...HEAD`):

- Django: N+1 запити, відсутні індекси, небезпечні міграції, права доступу в DRF.
- Vue 3: реактивність, зайві watcher’и, типізація props, доступність.
- Тести: чи покриті нові гілки.

Відповідай списком зауважень за важливістю; сам код не виправляй.

Агент називається acme-django-vue:code-reviewer; користувач може викликати його явно як @agent-acme-django-vue:code-reviewer. Для агентів плагіна ігноруються поля permissionMode, hooks, mcpServers, initialPrompt — їх не варто писати у frontmatter.

Хук: лінтинг після правок

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/lint-after-edit.sh\""
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# Читає JSON події з stdin, форматує змінений файл. Потрібні jq, ruff, eslint у проєкті.
file=$(jq -r '.tool_input.file_path // empty')
[ -z "$file" ] && exit 0
cd "$CLAUDE_PROJECT_DIR" || exit 0

case "$file" in
  *.py)
    ruff check --fix --quiet "$file"
    ruff format --quiet "$file"
    ;;
  *.vue|*.ts|*.js)
    npx --no-install eslint --fix "$file" >&2
    ;;
esac
exit 0

Зробіть скрипт виконуваним (chmod +x scripts/lint-after-edit.sh) і закомітьте з цим бітом. Шлях узято в подвійні лапки: інакше шлях встановлення з пробілом розламає shell-команду. У файлі обов’язковий зовнішній ключ "hooks". Хуки плагіна реєструються при завантаженні плагіна й діють усю сесію — не чекають на виклик скілу.

.mcp.json: GitLab і Sentry

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "${user_config.gitlab_url}/api/v4/mcp",
      "headers": { "Authorization": "Bearer ${user_config.gitlab_token}" }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

• ${user_config.KEY} підставляється у url, headers та інші поля MCP-конфігурації; у shell-хуках і headersHelper воно заборонене.
• Інший варіант без userConfig — змінні оточення зі стандартним синтаксисом .mcp.json: ${GITLAB_URL:-https://gitlab.example.com} і ${VAR}. Але змінні з «обліковими» іменами (як ANTHROPIC_API_KEY, NPM_TOKEN) у url/headers віддалених серверів читаються порожніми; для секретів надійніше userConfig із sensitive.
• Sentry-сервер без секретів у файлі: автентифікація йде через OAuth окремим кроком (у /mcp).
• Сервери в /mcp називаються plugin:acme-django-vue:gitlab та plugin:acme-django-vue:sentry, а їхні інструменти — mcp__plugin_acme-django-vue_gitlab__<tool> (саме так їх треба писати в permission-правилах і matcher’ах хуків).

marketplace.json у GitLab-репозиторії

{
  "name": "acme-tools",
  "owner": { "name": "Acme Platform Team", "email": "platform@acme.example" },
  "description": "Командні плагіни Claude Code Acme",
  "plugins": [
    {
      "name": "acme-django-vue",
      "source": "./plugins/acme-django-vue",
      "description": "Міграції Django, рев’ю, лінтинг, GitLab і Sentry MCP",
      "category": "development",
      "tags": ["django", "vue", "gitlab", "sentry"]
    }
  ]
}

Перевірка перед пушем

# перевірка каталогу (marketplace.json) і окремо плагіна
claude plugin validate . --strict
claude plugin validate ./plugins/acme-django-vue --strict

# пробний запуск без встановлення
claude --plugin-dir ./plugins/acme-django-vue

# реліз: тег acme-django-vue--v1.0.0
cd plugins/acme-django-vue && claude plugin tag --push

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

claude plugin marketplace add https://gitlab.example.com/platform/acme-claude-plugins.git --scope project
claude plugin install acme-django-vue@acme-tools --scope project
git add .claude/settings.json && git commit -m "Enable acme-django-vue plugin"

Що відбувається при встановленні

1. Оновлення каталогу
  назва містить @acme-tools → Claude Code спершу оновлює цей маркетплейс (git fetch/clone по GitLab)
2. Панель деталей і згода
  Will install: skill, agent, hook, 2 MCP servers  (для власного маркетплейсу може бути «Components will be discovered at installation»)
  попередження «Make sure you trust a plugin before installing…»
  вибір scope: user / project (для колег) / local
3. Копіювання в кеш
  ~/.claude/plugins/cache/acme-tools/acme-django-vue/1.0.0/    ← ${CLAUDE_PLUGIN_ROOT}
  запис у installed_plugins.json, enabledPlugins у settings обраного scope
4. Діалог userConfig
  gitlab_url, gitlab_token → url у settings (pluginConfigs), токен у захищеному сховищі
5. Активація
  «Plugin is now active.»  (або «Run /reload-plugins to apply.» — Claude Code виконає reload сам)
6. Результат у сесії
  /acme-django-vue:django-migrations      ← скіл з простором імен
  @agent-acme-django-vue:code-reviewer   ← агент
  PostToolUse hook (Write|Edit)          ← активний від завантаження, не чекає на скіл
  /mcp → plugin:acme-django-vue:gitlab, plugin:acme-django-vue:sentry
  Sentry: пройти OAuth; GitLab: токен уже підставлений з userConfig

• Якщо reload змінює MCP-інструменти і це знецінює prompt cache, Claude Code не застосовує зміни мовчки, а пише This reload changes MCP tools … Run /reload-plugins --force to apply. Один запит буде без кешу.
• Перевірка: claude plugin list (версія, scope, Status: ✔ enabled), /plugin → Installed, claude plugin details acme-django-vue (інвентар компонентів і витрата токенів).
• Для колег, які відкрили проєкт з уже закоміченим .claude/settings.json (відносний шлях у маркетплейсі): trust dialog → фонове клонування каталогу → Plugins changed. Run /reload-plugins to activate. → плагін завантажується з копії маркетплейсу. Значення userConfig задайте через /plugin configure acme-django-vue@acme-tools, інакше GitLab-сервер не стартує. Установка з shell (claude plugin install) діалог userConfig теж не показує — значення передають --config gitlab_url=… --config gitlab_token=… або пізніше /plugin configure.
• Оновлення: підніміть version у plugin.json (1.0.1), запушіть, поставте тег. Колеги отримують зміни після claude plugin marketplace update acme-tools + claude plugin update acme-django-vue@acme-tools або автоматично, якщо в маркетплейсу ввімкнено автооновлення; у відкритій сесії — /reload-plugins.

Шукайте точний текст повідомлення: Claude Code показує помилки завантаження у вкладці Errors панелі /plugin (кожна помилка з рядком-підказкою), а claude plugin list у shell додає їх до рядка плагіна. Повні довідники: Troubleshoot plugins.

Швидка діагностика

# 1. Що встановлено, у якому scope, чи є помилки (errors / notes / errorDetails)
claude plugin list
claude plugin list --json

# 2. Що саме додає плагін (компоненти, витрата токенів); для ще не встановленого — з теки
claude plugin details acme-django-vue
claude --plugin-dir ./plugins/acme-django-vue plugin details acme-django-vue

# 3. Валідація маніфестів і компонентів (код 1 = помилка; --strict: попередження теж помилки)
claude plugin validate ./plugins/acme-django-vue --strict

# 4. Лог запуску: хуки, MCP, LSP (--debug у термінал не друкує)
claude --debug      # файл ~/.claude/debug/<session-id>.txt
claude --debug-file /tmp/claude-debug.log

# 5. Доступ до приватного репозиторію каталогу — так само, як це робить Claude Code
git ls-remote https://gitlab.example.com/platform/acme-claude-plugins.git
ssh -T git@gitlab.example.com

У сесії: /plugin → Installed та Errors; /reload-plugins (друкує Reloaded: N plugins · N skills · N agents · N hooks · N plugin MCP servers · N plugin LSP servers і N errors during load. Run /plugin for details.); /mcp — статус MCP-серверів; /status — чи завантажилися managed-налаштування (Enterprise managed settings у Setting sources).

Маркетплейс: додавання й доступ

Встановлення

Плагін встановлено, але не працює

Хуки

MCP-сервери

Версії, кеш і оновлення

Конфлікти імен

Якщо кілька ввімкнених плагінів мають однакове name у маніфесті, завантажується один — за пріоритетом (від вищого):

1. Плагін, чий id є в managed enabledPlugins (true чи false); --plugin-dir-копія ігнорується: --plugin-dir copy of "x" ignored: plugin is locked by managed settings.
2. Ввімкнений --plugin-dir / --plugin-url / CLAUDE_CODE_PLUGIN_DIRS — мовчки заміщує встановлений маркетплейсний плагін (лише debug-лог: Plugin "x" from --plugin-dir overrides installed version); skills-dir плагін отримує рядок Not loaded у Errors.
3. Встановлений плагін із маркетплейсу.
4. Плагін зі skills-директорії; між двома — копія в ~/.claude/skills/ перемагає проєктну.
5. Плагін, синхронізований з claude.ai (@synced) — програє будь-якому іншому з тим самим ім’ям.

• Щоб --plugin-dir нічого не затінював, запишіть у settings "x@inline": false.
• Два маркетплейси з однаковим name не можна зареєструвати одночасно; якщо два маркетплейси пропонують однакове ім’я плагіна, пишіть plugin@marketplace.
• Ім’я запису в marketplace.json — ключ встановлення (enabledPlugins, папка кешу), а name маніфесту — простір імен і те, що порівнюється при конфліктах. Тримайте їх однаковими.
• Імена скілів — /plugin:skill, агентів — plugin:agent; хуки префікса не мають.

Помилки валідації

Команди запускаються або з shell як claude plugin … (псевдонім claude plugins), або у сесії як /plugin … (псевдоніми /plugins, /marketplace; лише в інтерактивному терміналі — у claude -p відповідь /plugin isn't available in this environment). У shell ці команди вводять без слеша: /plugin там не існує (zsh: no such file or directory: /plugin). Спільне: код виходу 0/1 (validate додає 2); <plugin> — name або name@marketplace; --scope приймає user | project | local (update ще й managed). claude plugin <sub> --help показує повний перелік опцій вашої версії.

Команди claude plugin

Команди claude plugin marketplace

Форми <source> та їх розбір — у розділі «Власний маркетплейс».

Команди /plugin у сесії

Команд без форми в сесії: init, update, details, prune, eval, test. Закриття панелі /plugin з відкладеними змінами саме запускає /reload-plugins.

Панель /plugin

Прапорці сесії та змінні оточення

Агент SDK має еквівалент --plugin-dir — опцію plugins. Адміністратор може заборонити все це ключем disableSideloadFlags.

Неіснуючі написання

Що плагін може зробити

Встановлення також вмикає плагін, якщо його маніфест чи запис не задають defaultEnabled: false. Імена й описи моделе-викликуваних скілів/агентів увімкнених плагінів витрачають контекст на кожному ході (claude plugin details показує витрату).

Довіра й перевірка перед встановленням

1. claude plugin marketplace list — з якого джерела додано маркетплейс.
2. /plugin → деталі плагіна: розділ Will install (команди, агенти, скіли, хуки, MCP/LSP).
3. Прочитати у вихідному коді: hooks/hooks.json (які команди), .mcp.json (команди/URL серверів), усі файли в bin/. Will install показує, що хук існує, але не що він виконує.
4. claude --plugin-dir <клон> plugin details <name> — інвентар компонентів без запуску сесії; після встановлення — claude plugin details <name>.
5. Видалення недовіреного: claude plugin uninstall <plugin> --scope …; дані стираються з останнього scope; файли в кеші лежать ще 14 днів — видаліть ~/.claude/plugins/cache/<marketplace>/<plugin>/ вручну; за потреби видаліть і маркетплейс.

• Рівні маркетплейсів: офіційний (перелік імен у розділі «Власний маркетплейс»), спільнотний (claude-community, claude-plugins-community, healthcare) і третьосторонній (усе інше, зокрема ваш). Офіційні/спільнотні імена приймаються лише для джерел під github.com/anthropics/, тож сторонній маркетплейс не видасть себе за них; перевірка повторюється при кожному завантаженні. Спільнотний каталог фіксує майже всі плагіни на commit SHA — інший коміт Claude Code не встановить.
• Claude Code перед встановленням показує: «Make sure you trust a plugin before installing, updating, or using it …»; організація може додати свій текст через pluginTrustMessage.
• Установка npm-залежностей плагіна ніколи не запускає lifecycle-скрипти; npm-джерело теж встановлюється без install-скриптів.
• Плагіни, закомічені в .claude/skills/ репозиторію (skills-dir, project scope), вантажаться лише після workspace trust; їхні MCP-сервери проходять покроковий approval, MCPB-бандли не вантажаться, монітори — теж.

Обмеження субагентів плагіна

З міркувань безпеки агенти, що постачаються плагіном, ігнорують частину полів frontmatter:

• Хуки й MCP-сервери агента додавайте на рівні плагіна: hooks/hooks.json і .mcp.json (вони діють, поки плагін увімкнений). Інший шлях — скопіювати агента в .claude/agents/, де ці поля працюють.
• Якщо frontmatter агента не розбирається, агент усе одно завантажується, але з усіма ігнорованими полями, під іменем файлу та описом Agent from <plugin> plugin.
• Ім’я агента не може містити : (зарезервовано для plugin-scoped id). Для хуків на агентів плагіна обмежуйте matcher якорями: ^acme-django-vue:code-reviewer$.

Чого плагіни не вміють

• CLAUDE.md у корені плагіна не завантажується як контекст (validate попереджає). Інструкції — у скіл.
• settings.json плагіна (як і ключ settings у маніфесті) діє лише для agent та subagentStatusLine; решта ключів відкидається. Через плагін не можна задати permissions, env чи моделі.
• Компоненти всередині .claude-plugin/ не завантажуються (там лише plugin.json); плагін ≠ ~/.claude/; тека проєкту .claude/plugins/ не сканується — діліться через enabledPlugins чи .claude/skills/.
• Файли за межами теки плагіна не копіюються в кеш; шляхи за межі кореня (та симлінки назовні) відхиляються.
• Змінні ${CLAUDE_PLUGIN_ROOT}/${CLAUDE_PLUGIN_DATA} недоступні в командах, які Claude запускає через Bash-інструмент; у тілі скіла/агента пишіть ${…} — підставиться інлайн. Надійні дані зберігайте в ${CLAUDE_PLUGIN_DATA}: ${CLAUDE_PLUGIN_ROOT} змінюється з кожною версією.
• Ключі commands, agents, outputStyles, workflows, теми та монітори в маніфесті замінюють типові теки; skills — додає; hooks та mcpServers — зливаються.
• Однаковий хук у settings.json і в плагіні виконується двічі (префікса в хуків немає) — після міграції видаляйте оригінали.
• skillOverrides не діє на скіли плагінів — ними керують через /plugin.
• Ключ version, закріплений в маніфесті, блокує оновлення, доки його не змінити. Опція options у userConfig робить плагін непрацездатним у Claude Code до v2.1.271.
• Файли в Git LFS не завантажуються (лише pointer-файли).
• Монітори працюють лише в інтерактивних сесіях; при вимкненні плагіна монітор триває до кінця сесії, а після оновлення потребує перезапуску сесії.
• Встановлення з shell (claude plugin install) ніколи не питає значення userConfig.
• Видалення маркетплейсу деінсталює всі його плагіни й стирає їхні дані.
• Облікових даних для git у marketplace.json немає; окремого поля автооновлення, аудиторії чи deprecation-стану в каталозі — теж.

Де плагіни доступні (surface)

Платформа, середовище й числові обмеження

Чекліст аудиту стороннього плагіна

Докладніше про політики — в розділі «Для команди»; офіційний довідник: Plugin security and trust.

Корисні посилання