Marketplace: публикация, установка и обновление — Claude Code: с нуля до уверенной работы

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

Слово «marketplace» здесь может ввести в заблуждение: это не витрина с оплатой, а обычный JSON-файл в git-репозитории. Именно поэтому механизм одинаково хорошо работает и для публичного плагина, и для внутреннего инструмента команды в приватном репозитории.

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

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

Мы собрали плагин и научились его проверять. Осталась доставка. Разберём формат marketplace.json, типы источников плагинов, команды добавления marketplace и установки плагинов, раздачу через .claude/settings.json для команды и правила версионирования, от которых зависит, увидит ли пользователь ваше обновление.

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

Как устроен файл .claude-plugin/marketplace.json и какие поля в нём обязательны
Какие источники может иметь плагин: локальный путь, GitHub, git-URL, npm, архив
Как добавить marketplace и установить из него плагин
Чем отличаются области установки user, project и local
Как раздать marketplace и плагины всей команде через настройки проекта

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

Marketplace — каталог плагинов, описанный файлом .claude-plugin/marketplace.json.
Корень marketplace — каталог, содержащий папку .claude-plugin/; относительно него разрешаются относительные пути плагинов.
Источник плагина (source) — указание, откуда взять конкретный плагин: относительный путь, GitHub-репозиторий, git-URL, npm-пакет или zip-архив.
extraKnownMarketplaces — ключ настроек, добавляющий marketplace всем участникам проекта.
enabledPlugins — ключ настроек, перечисляющий плагины, включённые по умолчанию.

Как выглядит каталог

Marketplace — это репозиторий с одним обязательным файлом:

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── quality-review-plugin/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── quality-review/
                └── SKILL.md

Сам marketplace.json устроен просто. Обязательных полей верхнего уровня три: name, owner и plugins.

{
  "name": "my-plugins",
  "owner": {
    "name": "Platform Team",
    "email": "platform@example.com"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Скилл быстрого код-ревью",
      "version": "1.0.0"
    }
  ]
}

У каждой записи плагина обязательны два поля: name и source. Имя — публичное, именно оно используется при установке. Оно, кстати, может отличаться от имени в plugin.json самого плагина; в этом случае побеждает имя из записи marketplace — под ним плагин отображается и записывается в настройки.

Относительные пути отсчитываются от корня marketplace — каталога, содержащего .claude-plugin/, а не от самой этой папки. И начинаться они должны с ./.

Откуда берутся плагины

Поле source определяет, где лежит плагин. Вариантов несколько, и выбор зависит от того, как вы храните код.

Относительный путь — плагин лежит в том же репозитории, что и marketplace. Самый простой вариант, он же нужен для приватной раздачи:

{ "name": "deploy-tools", "source": "./plugins/deploy-tools" }

GitHub-репозиторий — плагин в отдельном репозитории:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0"
  }
}

Git-URL для любого хоста (source: "url"), подкаталог монорепозитория (source: "git-subdir" с обязательным полем path), npm-пакет (source: "npm" с полем package) и zip-архив (source: "archive" с полем url и опциональной контрольной суммой sha256).

Про относительные пути есть важная оговорка: они разрешаются относительно локальной копии marketplace. Это работает для git-источников и локальных каталогов. Но если пользователи добавили ваш marketplace прямой ссылкой на файл marketplace.json, локальной копии репозитория нет и относительные пути не разрешатся. Для распространения по URL используйте другой тип источника.

Добавляем marketplace и ставим плагин

Добавление marketplace и установка плагина — два отдельных шага. Первый только регистрирует каталог, ничего не устанавливая.

# Из GitHub по сокращению owner/repo
/plugin marketplace add acme-corp/claude-plugins

# С другого git-хоста, с суффиксом .git
/plugin marketplace add <https://gitlab.com/company/plugins.git>

# Из локального каталога
/plugin marketplace add ./my-marketplace

Затем ставим плагин, указывая имя marketplace через @:

/plugin install quality-review-plugin@my-plugins

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

user — для вас во всех проектах, запись в ~/.claude/settings.json;
project — для всех участников репозитория, запись в .claude/settings.json;
local — только для вас в этом репозитории, запись в .claude/settings.local.json.

Для скриптов есть неинтерактивный вариант из терминала:

claude plugin install formatter@company-tools --scope project

По умолчанию он ставит в область user. У всех этих команд есть терминальные аналоги: claude plugin marketplace add, list, remove, update.

Одно предупреждение стоит запомнить заранее: удаление marketplace из последней области удаляет и все установленные из него плагины. Если вам нужно просто обновить каталог, используйте update, а не связку remove + add.

Раздача команде: без ручных шагов

Самый практичный сценарий — сделать так, чтобы новый разработчик получил все нужные плагины при клонировании репозитория. Для этого в .claude/settings.json проекта добавляются два ключа:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

Marketplace добавится автоматически, как только участник доверит папку проекта, — отдельного запроса не будет. Плагин из внешнего источника при этом не установится сам: Claude Code сообщит, что плагин не установлен, и покажет команду claude plugin install, которую нужно выполнить.

Приватный репозиторий тоже подходит: команды, которые запускаете вы сами (/plugin marketplace add, /plugin install, /plugin update), используют ваши обычные git-креденшелы — gh auth login, связку ключей macOS, git-credential-store.

Обновления: почему они не доходят

Обновление marketplace — это просто git push в его репозиторий. Пользователи подтягивают изменения командой:

/plugin marketplace update company-tools

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

Из этого следуют два правила.

Первое: если вы задали version, вы обязаны поднимать её при каждом релизе. Новые коммиты без изменения версии до пользователей не доедут — они останутся на кэшированной копии.

Второе, менее очевидное: не задавайте version одновременно в plugin.json и в записи marketplace. Claude Code всегда берёт значение из plugin.json, причём молча, без предупреждения. Вы поднимете версию в каталоге, а обновление не уедет.

Для активно разрабатываемого плагина на git-источнике проще вообще не задавать version — тогда версией служит хеш коммита, и каждый push автоматически становится обновлением.

Автообновление marketplace включается отдельно, через панель /plugin на вкладке Marketplaces. У официальных маркетплейсов Anthropic оно включено по умолчанию, у сторонних и локальных — выключено.

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

Задать version и в plugin.json, и в записи marketplace. Claude Code молча берёт значение из plugin.json. Вы поднимете версию в каталоге, а пользователи останутся на старой копии.
Удалять marketplace, чтобы «обновить» его. Удаление из последней области деинсталлирует все установленные из него плагины. Для обновления есть /plugin marketplace update.
Использовать относительные пути в marketplace, раздаваемом прямой ссылкой на JSON. Без локальной копии репозитория такой путь не разрешится. Для URL-раздачи возьмите другой тип источника.
Ожидать, что enabledPlugins в настройках проекта сам установит внешний плагин. Плагин из внешнего источника нужно установить командой; Claude Code покажет какой именно.

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

Marketplace — это платная витрина? — Нет, это JSON-файл в git-репозитории. Никакой оплаты в механизме нет.
Можно ли держать marketplace в приватном репозитории? — Да. Команды, которые вы запускаете сами, используют ваши обычные git-креденшелы.
Чем project отличается от local при установке? — project пишет в .claude/settings.json, попадает в коммит и достаётся всей команде. local пишет в .claude/settings.local.json и остаётся только у вас.
Что если имя плагина в plugin.json и в записи marketplace отличается? — Побеждает имя из записи marketplace: именно оно используется в enabledPlugins, при установке и в интерфейсе.
Как переименовать плагин, не сломав установки? — Через поле renames верхнего уровня в marketplace.json: сопоставьте старое имя новому, и ключи в настройках пользователей перепишутся автоматически.

Итоги

Отличная работа — ваш плагин теперь может дойти до других людей. Вы разобрались в устройстве marketplace.json, знаете типы источников и когда какой уместен, умеете добавлять каталог и ставить плагины с выбором области, а главное — умеете раздать всё это команде через настройки проекта, чтобы новый разработчик получал готовое окружение при клонировании.

Отдельно ценно понимание версий: правило «версия из plugin.json побеждает молча» стоит того, чтобы его запомнить — оно объясняет большинство историй про «я выложил, а у них старое». Осталась последняя тема главы, и она про другую сторону медали: плагин, который вы ставите себе, выполняет код на вашей машине с вашими правами. На следующем уроке разберём, как оценивать безопасность сторонних плагинов.