Создание и распространение marketplace плагинов

Создавайте и размещайте marketplace плагинов для распространения расширений Claude Code по командам и сообществам.

plugin marketplace — это каталог, который позволяет вам распространять плагины другим пользователям. Marketplace обеспечивают централизованное обнаружение, отслеживание версий, автоматические обновления и поддержку нескольких типов источников, включая репозитории Git и локальные пути. Это руководство показывает, как создать собственный marketplace для совместного использования плагинов с вашей командой или сообществом.

Ищете способ установить плагины из существующего marketplace? См. Обнаружение и установка готовых плагинов.

Обзор

Создание и распространение marketplace включает:

1. Создание плагинов: создайте один или несколько плагинов с skills, агентами, hooks, MCP servers или LSP servers. Это руководство предполагает, что у вас уже есть плагины для распространения; см. Создание плагинов для получения подробной информации о том, как их создавать.
2. Создание файла marketplace: определите marketplace.json, который перечисляет ваши плагины и где их найти. См. Создание файла marketplace.
3. Размещение marketplace: отправьте на GitHub, GitLab или другой хост Git. См. Размещение и распространение marketplace.
4. Совместное использование с пользователями: пользователи добавляют ваш marketplace с помощью /plugin marketplace add и устанавливают отдельные плагины. См. Обнаружение и установка плагинов.

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

Пошаговое руководство: создание локального marketplace

Этот пример создает marketplace с одним плагином: skill quality-review для проверки кода. Вы создадите структуру каталогов, добавите skill, создадите манифест плагина и каталог marketplace, затем установите и протестируете его.

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

---
description: Review code for bugs, security, and performance
---

Проверьте выбранный мной код или недавние изменения на предмет:
- Потенциальных ошибок или граничных случаев
- Проблем безопасности
- Проблем производительности
- Улучшений читаемости

Будьте лаконичны и конкретны.

{
"name": "quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}

{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews"
}
]
}

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

/quality-review-plugin:quality-review

Чтобы узнать больше о том, что могут делать плагины, включая hooks, агентов, MCP servers и LSP servers, см. Плагины.

Создание файла marketplace

Создайте .claude-plugin/marketplace.json в корне вашего репозитория. Этот файл определяет имя вашего marketplace, информацию о владельце и список плагинов с их источниками.

Каждая запись плагина требует как минимум name и source, который указывает Claude Code, откуда его получить. См. полную схему ниже для всех доступных полей.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Автоматическое форматирование кода при сохранении",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Инструменты автоматизации развертывания"
    }
  ]
}

Схема marketplace

Обязательные поля

Поля владельца

Дополнительные поля

description и version также принимаются в metadata для обратной совместимости.

Записи плагинов

Каждая запись плагина в массиве plugins описывает плагин и где его найти. Вы можете включить любое поле из схемы манифеста плагина, такие как description, version, author, commands и hooks, плюс эти поля, специфичные для marketplace: source, category, tags, strict, relevance, headers и headersHelper.

Обязательные поля

Дополнительные поля плагина

Поля стандартных метаданных:

Как запись, так и собственный plugin.json плагина могут устанавливать поля отображения displayName, description, author, homepage, repository, license и keywords. В списках плагинов и деталях, до и после установки:

• Для поля, которое вы устанавливаете в записи, пользователи видят значение записи, даже когда plugin.json устанавливает другое.
• Для поля, которое запись оставляет неустановленным, пользователи видят значение plugin.json.

До установки Claude Code может читать plugin.json только для записей с источником относительного пути, чьи файлы плагина находятся внутри самого marketplace. Для записи с любым другим типом источника пользователи видят только собственные поля записи до установки плагина.

Поля конфигурации компонентов:

Поля аутентификации архива:

Устанавливайте их, когда запись имеет источник archive на сервере, требующем учётные данные.

Источники плагинов

Источники плагинов указывают Claude Code, откуда получить каждый отдельный плагин, указанный в вашем marketplace. Они устанавливаются в поле source каждой записи плагина в marketplace.json.

Claude Code копирует каждый установленный плагин в локальный кэш плагинов с версией в ~/.claude/plugins/cache, за исключением command источника в режиме link, который Claude Code использует на месте. Claude Code также устанавливает подходящие зависимости пакетов Node.js плагина в кэшированную копию.

Типы источников на основе Git ниже — это github, url и git-subdir. Когда оба ref и sha установлены на любом из них, sha является эффективным закреплением. Claude Code получает и проверяет закрепленный коммит напрямую.

На большинстве хостов Git, включая GitHub, GitLab и Bitbucket, это означает, что установка успешна даже если ветка или тег, названные ref, были удалены выше по течению, при условии, что коммит все еще доступен из репозитория. Некоторые серверы, такие как AWS CodeCommit, не поддерживают получение коммитов по SHA. На этих серверах ref все еще должен существовать и закрепленный коммит должен быть доступен из него.

Если вы распространяете плагины через Organization settings > Plugins, разрешены только некоторые типы источников. См. Распространение через параметры организации.

Относительные пути

Для плагинов в одном репозитории используйте путь, начинающийся с ./:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

Пути разрешаются относительно корня marketplace, который является каталогом, содержащим .claude-plugin/. В приведенном выше примере ./plugins/my-plugin указывает на <repo>/plugins/my-plugin, даже если marketplace.json находится в <repo>/.claude-plugin/marketplace.json. Не используйте ../ для ссылки на пути вне корня marketplace. На macOS и Linux Claude Code отказывает запись пути с обратной косой чертой где-либо после начального ./, поэтому пишите разделители как / на каждой платформе.

Простое имя — это одно имя каталога без /, например "formatter". Чтобы писать простые имена вместо путей ./, установите metadata.pluginRoot на каталог, в котором они разрешаются. С "pluginRoot": "./plugins", Claude Code разрешает "source": "formatter" на ./plugins/formatter. Требует Claude Code v2.1.239 или позже.

metadata.pluginRoot должен быть относительным путем внутри marketplace. Claude Code игнорирует его для источника, который уже начинается с ./. Источник, содержащий /, например team-a/formatter, не является простым именем и все еще нуждается в префиксе ./, даже когда установлен metadata.pluginRoot.

Репозитории GitHub

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

Вы можете закрепить определенную ветку, тег или коммит:

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

Репозитории Git

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Вы можете закрепить определенную ветку, тег или коммит:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Подкаталоги Git

Используйте git-subdir для указания плагина, который находится в подкаталоге репозитория Git. Claude Code использует разреженный, частичный клон для получения только подкаталога, минимизируя пропускную способность для больших монорепозиториев.

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

Вы можете закрепить определенную ветку, тег или коммит:

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Поле url также принимает сокращение GitHub (owner/repo) или SSH URL (git@github.com:owner/repo.git).

Пакеты npm

Плагины, распространяемые как пакеты npm, устанавливаются с помощью npm install. Это работает с любым пакетом в общедоступном реестре npm или в частном реестре, который размещает ваша команда.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

Чтобы закрепить определенную версию, добавьте поле version:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

Для установки из частного или внутреннего реестра добавьте поле registry:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

ZIP-архивы

Используйте archive для распространения плагина как ZIP-файла, который Claude Code загружает через HTTPS, поэтому установки работают без git или npm на машине пользователя. Разместите файл на любом статическом файловом сервере или хранилище артефактов, например в корзине S3, в универсальном хранилище Artifactory или nginx. Требует Claude Code v2.1.224 или позже. На версиях v2.1.120 через v2.1.223 установка плагина не удается с This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again.; на более старых версиях marketplace, содержащий запись archive, полностью не загружается.

Эта запись устанавливает плагин из ZIP-файла на сервере артефактов:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip"
  }
}

Когда вы создаете ZIP-файл, вы можете заархивировать содержимое плагина напрямую или заархивировать саму папку плагина. Claude Code ищет .claude-plugin/ в верхней части архива, затем внутри одной папки верхнего уровня, поэтому оба макета устанавливаются:

my-plugin.zip          my-plugin.zip
├── .claude-plugin/    └── my-plugin/
│   └── plugin.json        ├── .claude-plugin/
└── commands/              │   └── plugin.json
                           └── commands/

Claude Code не ищет глубже одной папки, поэтому плагин, вложенный дальше, не устанавливается. Claude Code отказывает архивам размером более 256 МиБ.

Чтобы закрепить точный файл, добавьте поле sha256 с дайджестом архива:

{
  "name": "my-plugin",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/claude-plugins/my-plugin-2.1.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

Если загруженный файл не совпадает с закреплением, Claude Code отказывает установку и сообщает Plugin archive integrity check failed.

Источники архивов принимают эти поля:

Дайджест sha256 также служит версией плагина, когда ни plugin.json, ни запись marketplace не объявляют версию. См. Управление версиями. Если вы объявляете version, эта строка версии является сигналом обновления, поэтому после изменения ZIP-файла и его дайджеста также увеличьте версию, или пользователи сохранят кэшированную копию.

Аутентификация загрузок архивов

Чтобы аутентифицировать загрузку архива, например загрузку из частного реестра, установите HTTP-заголовки, которые Claude Code отправляет с ней. Установите headers на источник url marketplace, который вы зарегистрировали, например запись extraKnownMarketplaces. На Claude Code v2.1.238 или позже вы можете установить его на запись плагина вместо этого, рядом с source.

Если значение, которое вы поместили бы в headers, недолговечно, например токен, который ваш реестр создает по запросу, установите вместо этого команду headersHelper в том же месте. Claude Code запускает команду и отправляет объект JSON, который она печатает, как заголовки этого места. Требует Claude Code v2.1.238 или позже.

Место, которое вы выбираете, определяет, какие загрузки получают заголовки и когда Claude Code запускает команду:

Где оба места устанавливают заголовок с одним и тем же именем, Claude Code отправляет значение записи. В одном месте заголовок, который печатает команда, переопределяет заголовок с одним и тем же именем, указанный в headers.

Добавьте headersHelper к записи плагина

Эта запись устанавливает headersHelper рядом с source. Она также устанавливает "strict": false, что Claude Code требует от записи marketplace.json, которая устанавливает headersHelper. С "strict": false, запись marketplace является полным определением плагина, поэтому пользователь может просмотреть, что содержит плагин, перед принятием команды:

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "commands": "./commands",
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

Чтобы проверить запись, запустите claude plugin install my-plugin@your-marketplace. Claude Code показывает вам команду и URL архива и загружает ZIP-файл после того, как вы примете.

До v2.1.238 Claude Code загружал архив записи без её headers или headersHelper, поэтому установка, которая полагалась на них, не удавалась с HTTP 401 while downloading plugin archive from, за которым следует URL, с кодом состояния реестра вместо 401.

Напишите команду headersHelper

Независимо от того, устанавливаете ли вы headersHelper на источник url marketplace или на запись плагина, напишите команду, чтобы она соответствовала этим требованиям:

• Текст команды: максимум 500 символов печатного ASCII, без прогонов из четырех или более пробелов.
• Вывод: печать одного объекта JSON имен заголовков и строковых значений на stdout, затем выход 0 в течение 10 секунд.
• Shell и рабочий каталог: Claude Code запускает команду через sh или cmd.exe на Windows из каталога конфигурации, ~/.claude или CLAUDE_CONFIG_DIR. Дайте абсолютный путь или команду на PATH, потому что относительный путь разрешается относительно этого каталога, а не проекта пользователя.
• Переменные, которые Claude Code удаляет: из окружения команды, установленной в записи marketplace.json или в .claude/settings.json или .claude/settings.local.json проекта, Claude Code удаляет каждую переменную, имя которой содержит слово, такое как TOKEN, SECRET, KEY или AUTH, включая ANTHROPIC_API_KEY. Claude Code не применяет это удаление к команде, установленной в пользовательских параметрах, файле --settings или управляемых параметрах.
• Переменные, которые Claude Code устанавливает: CLAUDE_CODE_MARKETPLACE_URL и CLAUDE_CODE_MARKETPLACE_NAME для команды источника url, и CLAUDE_CODE_PLUGIN_NAME и CLAUDE_CODE_PLUGIN_ARCHIVE_URL для команды записи. CLAUDE_CODE_MARKETPLACE_NAME не установлена при первой выборке после того, как пользователь добавит marketplace по URL, потому что эта выборка — это то, что предоставляет имя.

Команда, которая создает токен носителя, печатает объект, подобный этому:

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

Когда Claude Code пропускает команду headersHelper или отбрасывает её вывод

Claude Code не запускает команду headersHelper или отбрасывает заголовки, которые пришли из headers или из вывода команды, в этих ситуациях:

• Команда не удается: если команда выходит с ненулевым кодом, работает более 10 секунд или печатает что-либо, кроме объекта JSON строковых значений, Claude Code не выполняет выборку или загрузку, для которой она запустила команду.
• URL marketplace не начинается с https://: Claude Code не запускает команду этого источника url и отправляет только заголовки, указанные в его поле headers.
• Перенаправление покидает происхождение: когда загрузка перенаправляется с происхождения URL архива, Claude Code отбрасывает значения headers и вывод команды как источника url marketplace, так и записи плагина.
• Запись устанавливает заголовок маршрутизации или идентификации: Claude Code отбрасывает имена маршрутизации запросов и идентификации клиента, такие как Host, Cookie и X-Forwarded-* из headers записи и вывода команды, и сохраняет имена аутентификации, такие как Authorization. Claude Code фильтрует каждую запись marketplace.json таким образом, и встроенную запись параметров в зависимости от того, какой файл её объявляет.
• Команда установлена в параметрах каталога --add-dir: Claude Code игнорирует её, на источнике url и на встроенной записи плагина одинаково, и отправляет только headers этого файла.
• Управляемые параметры блокируют команду: установка disableCommandPluginSources на true блокирует команды headersHelper, и allowManagedHooksOnly также блокирует их, если disableCommandPluginSources явно не false. При любом блокировании Claude Code все еще запускает команду для marketplace, который сами управляемые параметры объявляют.

Как пользователи принимают команду headersHelper

Пользователь принимает команду записи плагина каждый раз, когда устанавливает или обновляет этот один плагин отдельно, из собственного представления плагина в /plugin или с claude plugin install или claude plugin update. Claude Code показывает команду и URL архива и запускает команду только после того, как пользователь примет. В неинтерактивной оболочке передайте --yes для принятия.

Claude Code запускает только команду, которую он показал, для URL архива, который он показал. Если команда записи или URL архива изменились между тем, Claude Code отказывает установку или обновление. Изменение только в строке запроса не считается.

Установки и обновления, которые отказывают команде вместо запроса

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

• Установка нескольких плагинов одновременно, из предложения плагина или как зависимость другого плагина: Claude Code отказывает плагину, который имеет команду, и указывает пользователю на собственное представление этого плагина в /plugin. Другие плагины в массовой установке все еще устанавливаются. Плагин, который зависит от отказанного плагина, не устанавливается, пока пользователь не установит отказанный плагин отдельно.
• Фоновое автообновление или запуск сеанса для плагина, архив которого никогда не был загружен: Claude Code перечисляет плагин на вкладке /plugin Errors, чтобы пользователь знал, что нужно установить или обновить его вручную. Автообновление, которое находит запись, по-прежнему объявляет установленную версию, не перечисляет ничего.

Когда запускается команда headersHelper источника marketplace `url`

headersHelper источника url marketplace объявляется в файле параметров, например в записи extraKnownMarketplaces, а не в каталоге, который публикует marketplace, поэтому Claude Code не просит пользователя принять её при каждой установке или обновлении. Файл параметров, который её объявляет, определяет, когда Claude Code её запускает:

В сеансе -p или SDK Claude Code не может показать диалог одобрения безопасности. Он применяет другие доставленные параметры, но выборка marketplace и любая загрузка архива, которая нуждается в команде, не удается, пока пользователь не одобрит в интерактивном сеансе.

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

Источники команд

Используйте command, когда локально установленный инструмент создает каталог плагина, например IDE, который отображает свой плагин для выбранной в данный момент цепочки инструментов. Claude Code запускает команду, когда пользователь устанавливает плагин, и переустанавливает её в фоне один раз за сеанс, поэтому ваши пользователи получают изменённый вывод инструмента без переустановки. Требует Claude Code v2.1.229 или позже. На v2.1.120 через v2.1.228 установка плагина не удается с This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again., и на более старых версиях весь marketplace не загружается.

Эта запись устанавливает плагин из любого каталога, который печатает инструмент:

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

Claude Code запускает команду через оболочку платформы, sh на macOS и Linux или cmd.exe на Windows, из домашнего каталога пользователя. Команда должна печать ровно одну строку на stdout и выход с кодом 0. Эта строка — абсолютный путь каталога, который содержит полный плагин к моменту выхода команды, и путь может изменяться между запусками.

Claude Code останавливает команду, которая работает дольше, чем timeout секунд, и установка или обновление не удается. Claude Code также отказывает печатанному пути в этих случаях, и установка или обновление не удается таким же образом:

• Каталог не имеет содержимого плагина на его верхнем уровне, например каталога .claude-plugin/ или каталога skills/, commands/, agents/ или hooks/
• Каталог — это тот, в котором был запущен Claude Code, или один из его родителей
• На Windows путь — это путь UNC

Источники команд принимают эти поля:

Режим копирования и режим link

С "mode": "copy" по умолчанию Claude Code копирует печатанный каталог в кэш плагинов с версией и выводит версию плагина из хеша содержимого каталога. Ваш инструмент может удалить или переписать каталог после выхода команды, и переустановка, которая создает идентичное содержимое, считается актуальной. Claude Code отказывает установку каталога размером более 256 МиБ или содержащего более 20 000 записей.

Установите "mode": "link" для больших каталогов плагинов, которые не должны копироваться, например для отображаемого экспорта SDK. Claude Code заполняет запись кэша плагина ссылкой на каждую запись верхнего уровня печатанного каталога и использует файлы на месте, поэтому ничего не копируется, содержимое файлов не хешируется, и ограничения размера не применяются. Установка не удается, если запись верхнего уровня — это символическая ссылка, которая указывает вне печатанного каталога. Claude Code также пропускает установку зависимостей пакета Node.js для плагина в режиме link, поэтому печатайте каталог, который уже содержит любые node_modules, которые нужны плагину.

Сохраняйте печатанный каталог на месте столько, сколько плагин остается установленным, потому что Claude Code загружает плагин через эти ссылки при каждом запуске. Claude Code выводит версию плагина из реального пути печатанного каталога и его записей верхнего уровня, а не файлов внутри, поэтому печатайте другой путь для сигнала нового содержимого. В сеансе, запущенном в печатанном каталоге или где-либо ниже, Claude Code вообще не загружает плагин.

Claude Code не поддерживает режим link на Windows и отказывает установку плагина в режиме link там. Объявите "mode": "copy" вместо этого.

Как пользователи принимают команду

Claude Code запускает вашу команду на машине пользователя, поэтому она привязывает каждый запуск к явному принятию пользователем:

• Когда пользователи устанавливают плагин из его экрана деталей в /plugin или устанавливают или обновляют его с claude plugin install или claude plugin update в интерактивном терминале, Claude Code сначала показывает им точную строку команды и записывает принятую команду для этой установки. claude plugin update, который может продолжаться при принятии той же команды, не показывает ничего. В неинтерактивной оболочке, например в скрипте подготовки, передайте --yes в claude plugin install или claude plugin update для принятия команды, которую она печатает.
• Каждый другой путь запускает только команду, которую пользователь уже принял. Это включает обновления, запущенные из /plugin, и фоновые запуски, описанные в Когда Claude Code переустанавливает команду. Когда ничего не было принято, Claude Code отказывает запустить команду и говорит пользователю, как её просмотреть. Claude Code никогда не устанавливает плагин с источником команды как зависимость другого плагина, поэтому пользователи устанавливают его сами в первую очередь.
• Если вы измените command записи или переключите её mode, пользователи сохраняют версию, которую они уже имеют, и Claude Code останавливает переустановку команды. В интерактивных сеансах вкладка /plugin Errors показывает новую команду, пока пользователь не просмотрит и не примет её, запустив claude plugin update <plugin>@<marketplace>.

Администраторы могут блокировать источники команд во всей организации с помощью управляемого параметра disableCommandPluginSources. Если организация устанавливает allowManagedHooksOnly, Claude Code блокирует источники команд по умолчанию.

Когда Claude Code переустанавливает команду

Печатанный каталог отражает состояние инструмента на момент запуска команды, поэтому Claude Code запускает команду снова в эти моменты:

• Каждый раз, когда пользователь устанавливает или обновляет плагин
• Один раз за сеанс для каждого включённого плагина с источником команды, в фоне, вскоре после запуска сеанса. Этот запуск не проходит через автообновление marketplace, поэтому не зависит от параметра автообновления marketplace
• При запуске или на /reload-plugins, когда установленная версия включённого плагина отсутствует в кэше плагинов

Claude Code пропускает два фоновых запуска, когда пользователь устанавливает CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC. Явные установки и обновления все еще запускают команду с этой переменной установленной.

Когда хешированный вывод команды изменился, Claude Code устанавливает результат как новую версию и перезагружает его в работающем интерактивном сеансе, переключая те же компоненты, которые переключает /reload-plugins. Пользователь видит уведомление, что плагин был перезагружен. Если переустановка на месте аннулирует кэш подсказок сеанса, Claude Code вместо этого предлагает пользователю запустить /reload-plugins, который предупреждает о стоимости кэша и применяется при переустановке с --force.

Расширенные записи плагинов

Этот пример показывает запись плагина, использующую множество дополнительных полей, включая пользовательские пути для команд, агентов, hooks и MCP servers:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Инструменты автоматизации корпоративного рабочего процесса",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

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

• commands и agents: вы можете указать несколько каталогов или отдельные файлы. Пути относительны к корню плагина и должны оставаться внутри него.
  • Claude Code отказывает путь, который разрешается вне каталога плагина, например ./../shared.md, с ошибкой path escapes plugin directory, и все еще загружает плагин без этого компонента
• ${CLAUDE_PLUGIN_ROOT}: используйте эту переменную в командах hooks и конфигурациях MCP server для ссылки на файлы в каталоге установки плагина.
  • См. таблицу подстановки для того, какие поля конфигурации подставляют её для каждого типа сервера
  • Для зависимостей или состояния, которое должно сохраняться при обновлениях плагина, используйте ${CLAUDE_PLUGIN_DATA} вместо этого
• strict: false: поскольку это установлено на false, плагину не нужен собственный plugin.json. Запись marketplace определяет все. См. Strict mode ниже.

По умолчанию skills плагина загружаются из каталога skills/ в его source. Пути, указанные в поле skills, добавляются к этому сканированию:

"skills": ["./skills/", "./extra-skills/"]

Когда несколько записей плагинов совместно используют один каталог skills/ в корне marketplace (source: "./"), вместо этого указывайте конкретные подкаталоги, чтобы каждая запись загружала только свои собственные skills:

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

С источником в корне marketplace указанные пути являются полным набором для этой записи, и другие каталоги в общем каталоге skills/ не загружаются. Указание самого ./skills/ или корня плагина сохраняет полное сканирование. Если ни один из указанных путей не существует, вместо этого запускается сканирование по умолчанию.

Strict mode

Поле strict контролирует, является ли plugin.json авторитетом для определений компонентов (skills, агенты, hooks, MCP servers, стили вывода).

Когда использовать каждый режим:

• strict: true: плагин имеет собственный plugin.json и управляет своими компонентами. Запись marketplace может добавить дополнительные skills или hooks сверху. Это значение по умолчанию и работает для большинства плагинов.
• strict: false: оператор marketplace хочет полный контроль. Репозиторий плагина предоставляет необработанные файлы, и запись marketplace определяет, какие из этих файлов открыты как skills, агенты, hooks и т. д. Полезно, когда оператор marketplace переструктурирует или курирует компоненты плагина иначе, чем предполагал автор плагина.

Размещение и распространение marketplace

Размещение на GitHub (рекомендуется)

GitHub обеспечивает рекомендуемый способ размещения и распространения marketplace:

1. Создание репозитория: установите новый репозиторий для вашего marketplace
2. Добавление файла marketplace: создайте .claude-plugin/marketplace.json с определениями ваших плагинов
3. Совместное использование с командами: пользователи добавляют ваш marketplace с помощью /plugin marketplace add owner/repo

Преимущества: встроенное управление версиями, отслеживание проблем и функции совместной работы команды.

Размещение на других сервисах Git

Любой сервис хостинга Git работает, например GitLab, Bitbucket и самостоятельно размещаемые серверы. Пользователи добавляют с полным URL репозитория:

/plugin marketplace add https://gitlab.com/company/plugins.git

Частные репозитории

Claude Code поддерживает установку плагинов из частных репозиториев. Если вы распространяете ваш marketplace через Organization settings > Plugins вместо этого, ваши учетные данные Git не задействованы: организационная синхронизация читает репозиторий marketplace через Claude GitHub App или GitHub Enterprise App вашей организации, и источник плагина, который она не может аутентифицировать, должен быть общедоступным. См. Распространение через параметры организации для полных правил.

Команды, которые вы запускаете

Когда вы запускаете /plugin marketplace add, /plugin install, /plugin update или /plugin marketplace update, Claude Code использует ваши существующие помощники учетных данных Git, поэтому доступ HTTPS через gh auth login, macOS Keychain или git-credential-store работает так же, как в вашем терминале. Доступ SSH работает, пока хост уже находится в вашем файле known_hosts и ключ загружен в ssh-agent, так как Claude Code подавляет интерактивные подсказки SSH для отпечатка хоста и пароля ключа. Сокращение GitHub owner/repo по умолчанию клонирует через SSH; установите CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1, чтобы вместо этого клонировать их через HTTPS.

Фоновые автоматические обновления

По умолчанию фоновое обновление отключает помощников учетных данных Git для своего git pull, поэтому pull не может аутентифицироваться в частных репозиториях через HTTPS, даже если помощник настроен. Удаленные SSH не затронуты: ключ, загруженный в ssh-agent, аутентифицирует фоновые pull так же, как команды, которые вы запускаете. Когда фоновый pull не удается, Claude Code возвращается к повторному клонированию marketplace с нуля. Повторное клонирование использует ваши сохраненные учетные данные Git, но оно может истечь на больших репозиториях, поэтому автоматические обновления частного marketplace могут периодически не удаваться.

Два параметра делают частные marketplace предсказуемыми:

• Установите CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1, чтобы сохранить существующий клон при неудаче фонового pull, вместо удаления и повторного клонирования. Ваши плагины продолжают работать из последнего синхронизированного состояния, и ручные обновления с /plugin marketplace update по-прежнему pull с вашими учетными данными.
• Настройте помощника учетных данных Git, например с помощью gh auth setup-git для GitHub, чтобы fallback повторного клонирования мог аутентифицироваться без подсказок.

Установка токена поставщика, такого как GITHUB_TOKEN, в вашей среде не включает фоновую аутентификацию сама по себе. Токены вступают в силу только через настроенного помощника учетных данных, например помощника CLI gh, который читает GH_TOKEN и GITHUB_TOKEN.

Чтобы сам фоновый pull аутентифицировался через HTTPS, настройте глобальное переписывание URL Git. Переписывание встраивает токен в удаленный URL, поэтому оно вступает в силу, несмотря на то, что фоновый pull отключает помощников учетных данных, и успешный pull пропускает fallback повторного клонирования. Следующий пример переписывает URL репозитория marketplace, чтобы включить токен доступа:

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

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

Каждый поставщик ожидает другое имя пользователя в переписанном URL, и то же самое ограничение пути применяется к каждому поставщику. Для самостоятельно размещаемых серверов замените имя хоста на имя хоста вашего сервера:

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

Распространение через параметры организации

Если вы распространяете плагины через Organization settings > Plugins в плане Team или Enterprise, применяются эти правила источника:

• Репозиторий marketplace должен быть частным или внутренним. Организационная синхронизация читает его через Claude GitHub App или GitHub Enterprise App вашей организации.
• Каждый источник плагина должен быть типа github, url или git-subdir, или относительный путь, который начинается с ./. Если вы перечисляете плагин по простому имени под metadata.pluginRoot, организационная синхронизация отклоняет его как неподдерживаемый источник, поэтому напишите путь полностью, например ./plugins/deploy-tools.
• Источник плагина может быть частным в двух случаях:
  • Источник github.com, который совместно использует владельца репозитория marketplace
  • Источник на GitHub Enterprise хосте вашей организации с установленным GHE App на репозитории
• Организационная синхронизация получает каждый другой источник без учетных данных, поэтому репозитории github.com под другим владельцем и репозитории на других хостах, такие как GitLab или Bitbucket, должны быть общедоступными.

См. Manage plugins for your organization для рабочего процесса администратора.

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

Например, эта запись плагина marketplace.json ссылается на плагин, который вы зафиксировали в plugins/deploy-tools в репозитории marketplace:

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

Держите исполняемые файлы вне каталога bin верхнего уровня

Не включайте каталог bin/ верхнего уровня в любой плагин, который вы распространяете через параметры организации. claude.ai отклоняет плагин, который имеет его, независимо от того, поступает ли плагин через синхронизацию marketplace или прямую загрузку:

• Синхронизация marketplace: организационная синхронизация отклоняет этот плагин и синхронизирует остальную часть marketplace. Сообщение об ошибке начинается с Plugin contains a top-level bin/ directory.
• Прямая загрузка: если вы загружаете плагин в Organization settings > Plugins вместо этого, claude.ai отклоняет загрузку с тем же сообщением.

Держите исполняемые файлы в другом каталоге, например scripts/, и ссылайтесь на них как ${CLAUDE_PLUGIN_ROOT}/scripts/<name> из ваших skills, hooks или MCP server configs.

Требование marketplace для вашей команды

Вы можете настроить ваш репозиторий так, чтобы Claude Code добавлял ваш marketplace для членов команды один раз, когда они доверяют папке проекта, без отдельного запроса. Добавьте ваш marketplace в .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
  }
}

Для полных параметров конфигурации см. Plugin settings.

Предварительное заполнение плагинов для контейнеров

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

Чтобы наслоить несколько каталогов seed, разделите пути с : на Unix или ; на Windows. Claude Code ищет каждый каталог по порядку и использует первый seed, содержащий данный marketplace или кэш плагина.

Каталог seed отражает структуру ~/.claude/plugins:

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

Чтобы построить каталог seed, запустите Claude Code один раз во время сборки образа, установите нужные вам плагины, затем скопируйте полученный каталог ~/.claude/plugins в ваш образ и укажите CLAUDE_CODE_PLUGIN_SEED_DIR на него.

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

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

Затем установите CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed в среде выполнения вашего контейнера, чтобы Claude Code читал из seed при запуске.

При запуске Claude Code регистрирует marketplace, найденные в known_marketplaces.json seed, в основную конфигурацию и использует кэши плагинов, найденные под cache/, на месте без повторного клонирования. Это работает как в интерактивном режиме, так и в неинтерактивном режиме с флагом -p.

Детали поведения:

• Только для чтения: каталог seed никогда не записывается. Автоматические обновления отключены для seed marketplace, так как git pull не удастся на файловой системе только для чтения.
• Записи seed имеют приоритет: marketplace, объявленные в seed, перезаписывают любые совпадающие записи в конфигурации пользователя при каждом запуске. Чтобы отказаться от seed плагина, используйте /plugin disable вместо удаления marketplace.
• Разрешение пути: Claude Code находит содержимое marketplace, проверяя $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ во время выполнения, а не доверяя путям, хранящимся внутри JSON seed. Это означает, что seed работает правильно, даже если он смонтирован по другому пути, чем где он был построен.
• Мутация заблокирована: запуск /plugin marketplace remove или /plugin marketplace update против seed-управляемого marketplace не удается с указанием попросить вашего администратора обновить образ seed.
• Компонуется с параметрами: если extraKnownMarketplaces или enabledPlugins объявляют marketplace, который уже существует в seed, Claude Code использует копию seed вместо клонирования.

Ограничения управляемого marketplace

Для организаций, требующих строгого контроля над источниками плагинов, администраторы могут ограничить, какие marketplace плагинов пользователи могут добавлять, используя параметр strictKnownMarketplaces в управляемых параметрах. Чтобы также отклонить флаги CLI, которые загружают плагины, агентов и MCP серверы для одного запуска, объедините его с disableSideloadFlags. Чтобы разрешить список, какие marketplace плагинов могут появляться как предложения контекстной установки, установите pluginSuggestionMarketplaces.

strictKnownMarketplaces совпадает с marketplace, из которого поступает плагин, а не с записями внутри него, поэтому пользователи все еще могут установить плагин с источником command из разрешенного marketplace. Чтобы также заблокировать источники команд, установите disableCommandPluginSources.

Когда strictKnownMarketplaces настроен в управляемых параметрах, поведение ограничения зависит от значения:

Общие конфигурации

Отключение всех добавлений marketplace, включая официальный marketplace Anthropic:

{
  "strictKnownMarketplaces": []
}

Разрешение только официального marketplace Anthropic. Сопоставление для записи одного репозитория является точным, поэтому эта запись не охватывает варианты ref или path одного и того же репозитория:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "anthropics/claude-plugins-official"
    }
  ]
}

С этой записью Claude Code сохраняет уже зарегистрированный официальный marketplace доступным и, на свежей машине, регистрирует marketplace автоматически при первом запуске Claude Code в интерактивном режиме.

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

• Неинтерактивные среды, которые запускаются перед первым интерактивным запуском машины.
• Машины, где Claude Code уже запускался в интерактивном режиме под политикой, которая заблокировала marketplace, например блокировка пустого массива. Claude Code записывает заблокированную попытку и не повторяет попытку после изменения политики.

На этих машинах добавьте marketplace в extraKnownMarketplaces в том же managed-settings.json, чтобы Claude Code регистрировал его автоматически, или запустите claude plugin marketplace add anthropics/claude-plugins-official.

Разрешение только определенных marketplace:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

Разрешение каждого репозитория marketplace под организацией GitHub с записью owner-wildcard. Owner wildcards требуют Claude Code v2.1.223 или позже.

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/*"
    }
  ]
}

Разрешение всех marketplace с внутреннего сервера Git с использованием сопоставления шаблонов регулярных выражений на хосте. Это рекомендуемый подход для GitHub Enterprise Server или самостоятельно размещаемых экземпляров GitLab:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

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

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

Используйте ".*" как pathPattern для разрешения любого пути файловой системы при одновременном контроле сетевых источников с помощью hostPattern.

Как работают ограничения

Ограничения проверяются перед любой сетевой или файловой операцией. Проверка выполняется при добавлении marketplace и при установке, обновлении, обновлении и автоматическом обновлении плагина. Если marketplace был добавлен до настройки политики и его источник больше не совпадает со списком разрешений, Claude Code отказывает в установке или обновлении плагинов из него. То же самое применяется к blockedMarketplaces.

Чтобы заблокировать каждый репозиторий marketplace под владельцем GitHub, используйте форму owner-wildcard в записи blockedMarketplaces: { "source": "github", "repo": "untrusted-org/*" }. Требуется Claude Code v2.1.223 или позже. Для правил сопоставления, которые отличаются между списком блокировки и списком разрешений, см. Owner wildcards.

Когда пользователь добавляет URL репозитория https://, который Claude Code клонирует, а не получает, например простой URL репозитория github.com или gitlab.com, Claude Code также проверяет его против записей url в blockedMarketplaces. Claude Code блокирует добавление, если запись называет тот же URL. В этом сравнении Claude Code игнорирует суффикс .git и любой ref, который пользователь добавляет после #. Требуется Claude Code v2.1.232 или позже. До v2.1.232 Claude Code совпадал с записью url только против URL, который он получал как размещенный файл marketplace.json.

Список разрешений использует точное сопоставление для большинства типов источников, кроме записей owner-wildcard github. Чтобы marketplace был разрешен, все указанные поля должны совпадать:

• Для источников GitHub: repo обязателен, либо называя один репозиторий, либо используя форму owner-wildcard owner/* для охвата каждого репозитория под этим владельцем. Для того, как записи wildcard совпадают, включая правила регистра, см. Owner wildcards. Для записей одного репозитория ref должен совпадать точно или отсутствовать в обоих источниках marketplace и записи списка разрешений, и то же правило применяется к path
• Для источников URL: полный URL должен совпадать точно
• Для источников hostPattern: хост marketplace сопоставляется с шаблоном регулярного выражения
• Для источников pathPattern: путь файловой системы marketplace сопоставляется с шаблоном регулярного выражения

Точное сопоставление списка разрешений рассматривает URL, которые отличаются только конечной косой чертой, суффиксом .git или схемой ssh:// и https:// как разные значения. Если marketplace вашей организации можно клонировать более чем одной формой URL, предпочтите запись hostPattern буквальному URL, чтобы формы https://, ssh:// и user@host:path все совпадали.

Поскольку strictKnownMarketplaces установлен в управляемых параметрах, отдельные пользователи и конфигурации проекта не могут переопределить эти ограничения.

Для полных деталей конфигурации, включая все поддерживаемые типы источников и сравнение с extraKnownMarketplaces, см. справку strictKnownMarketplaces.

Разрешение версий и каналы выпуска

Версии плагинов определяют пути кэша и обнаружение обновлений: если разрешенная версия совпадает с тем, что уже есть у пользователя, /plugin update и автоматическое обновление пропускают плагин. Для источников на основе Git, если вы опустите version, Claude Code использует разрешенный SHA коммита источника, поэтому пользователи получают обновление всякий раз, когда этот коммит изменяется; это самая простая установка для внутренних или активно разрабатываемых плагинов. См. Version management для полного порядка разрешения, включая источники archive.

Установка каналов выпуска

Для поддержки каналов выпуска "stable" и "latest" для ваших плагинов вы можете установить два marketplace, которые указывают на разные refs или SHAs одного репозитория. Затем вы можете дать каждой группе пользователей свой собственный marketplace через управляемые параметры одним из двух способов:

• Развертывание отдельных endpoint-managed settings, таких как файл управляемых параметров или профиль MDM, для устройств каждой группы. Как Claude Code объединяет управляемые источники говорит, применяется ли файл или профиль для каждой группы на устройстве, которое также имеет источник на уровне организации.
• Определение одной Claude apps gateway policy для каждой группы. Шлюз применяет первую политику, чье правило соответствия подходит пользователю, поэтому упорядочьте политики так, чтобы каждый пользователь достигал политики своей группы. Политика группы extraKnownMarketplaces заменяет карту политики catch-all, а не объединяется с ней, поэтому перечислите каждый marketplace, который группе нужен в политике группы, а не только ее marketplace канала.

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

Пример

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

Назначение каналов группам пользователей

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

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

Группа ранних доступов получает вместо этого latest-tools:

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

Закрепление версий зависимостей плагинов

Плагин может ограничить свои зависимости диапазоном semver, чтобы обновления зависимости не нарушили зависимый плагин. См. Ограничение версий зависимостей плагинов для соглашения о тегах Git {plugin-name}--v{version}, синтаксиса диапазона и того, как несколько ограничений на одну и ту же зависимость объединяются.

Переименование или удаление плагина

name плагина является его стабильным идентификатором. Пользователи ссылаются на него в enabledPlugins, pluginConfigs и командах /plugin install, поэтому изменение его нарушает каждую существующую установку. Чтобы изменить метку, отображаемую в пользовательском интерфейсе, без нарушения установок, установите displayName и оставьте name неизменным.

Если вы должны изменить name плагина или удалить плагин из массива plugins, добавьте запись renames верхнего уровня, чтобы существующие пользователи мигрировали вместо того, чтобы видеть ошибку plugin-not-found. Автоматическая миграция требует Claude Code v2.1.193 или позже. Сопоставьте каждое бывшее имя с его текущим именем или с null, если плагин больше не существует. Следующий пример переименовывает formatter в code-formatter и записывает, что legacy-linter был удален:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

Когда пользователь запускает Claude Code со старым именем все еще в своих параметрах, Claude Code следует карте renames:

• Если запись указывает на новое имя, Claude Code загружает плагин под его новым именем и показывает однострочное уведомление, такое как Renamed to "code-formatter" in the "acme-tools" marketplace. Затем он переписывает старый ключ на новый ключ в областях параметров пользователя, проекта и локальных параметров для обоих enabledPlugins и pluginConfigs, поэтому уведомление появляется один раз.
• Для записи null Claude Code удаляет старый ключ и уведомление сообщает, что плагин был удален из marketplace.
• Если переименованный плагин использует удаленный источник, такой как github или npm, Claude Code сообщает plugin-cache-miss после переименования и пользователь должен запустить /plugin install один раз, чтобы получить его под новым именем.

Рассматривайте renames как историю только для добавления: сохраняйте старые записи на месте даже после того, как вы ожидаете, что каждый пользователь мигрировал. Claude Code следует цепочкам, поэтому если вы позже переименуете code-formatter в formatter-pro, добавьте вторую запись вместо редактирования первой. Пользователь, который все еще имеет оригинальный formatter включенным, затем разрешается через обе записи в formatter-pro.

Запустите claude plugin validate . после редактирования карты; он отклоняет любую запись, цепочка которой образует цикл или не заканчивается на null или имя, указанное в plugins.

Более ранние версии Claude Code игнорируют поле renames и сообщают plugin-not-found для старого имени.

Валидация и тестирование

Протестируйте ваш marketplace перед совместным использованием. Валидация проверяет структуру файлов; чтобы протестировать, изменяет ли плагин поведение Claude на реалистичных запросах, запустите его набор eval с помощью claude plugin eval перед публикацией новой версии.

Из вашего каталога marketplace проверьте синтаксис JSON:

claude plugin validate .

Или из Claude Code:

/plugin validate .

Добавьте marketplace для тестирования:

/plugin marketplace add ./path/to/marketplace

Установите тестовый плагин, чтобы проверить, что все работает:

/plugin install test-plugin@marketplace-name

Для полного диапазона рабочих процессов тестирования плагинов см. Тестирование ваших плагинов локально. Для технического устранения неполадок см. Справка плагинов.

Управление marketplace из CLI

Claude Code предоставляет неинтерактивные подкоманды claude plugin marketplace для написания скриптов и автоматизации. Они эквивалентны командам /plugin marketplace, доступным в интерактивном сеансе.

Plugin marketplace add

Добавьте marketplace из репозитория GitHub, URL Git, удаленного URL или локального пути.

claude plugin marketplace add <source> [options]

Аргументы:

• <source>: Сокращение GitHub owner/repo, URL Git, удаленный URL к файлу marketplace.json или путь локального каталога. Чтобы закрепить на ветке или теге, добавьте @ref к сокращению GitHub или #ref к URL Git

URL должен включать свою схему. Начиная с Claude Code v2.1.196, хост, введенный без схемы, такой как gitlab.example.com/team/plugins, отклоняется как недействительное сокращение owner/repo, и ошибка указывает вам добавить https:// или использовать ./ для локального пути. Более ранние версии неправильно интерпретировали его как путь репозитория GitHub и не удаются при клонировании с ошибкой GitHub not-found.

Параметры:

Добавьте marketplace из GitHub, используя сокращение owner/repo:

claude plugin marketplace add acme-corp/claude-plugins

Закрепите на определенной ветке или теге с помощью @ref:

claude plugin marketplace add acme-corp/claude-plugins@v2.0

Добавьте из URL Git на хосте, отличном от GitHub:

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

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

claude plugin marketplace add https://example.com/marketplace.json

Добавьте из локального каталога для тестирования:

claude plugin marketplace add ./my-marketplace

Объявите marketplace в области проекта, чтобы он был общим с вашей командой через .claude/settings.json:

claude plugin marketplace add acme-corp/claude-plugins --scope project

Для монорепозитория ограничьте checkout каталогами, содержащими содержимое плагина:

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

Plugin marketplace list

Перечислите все настроенные marketplace.

claude plugin marketplace list [options]

Параметры:

С помощью --json каждая запись включает name, source, поле installLocation с локальным путем кэша, где хранится marketplace, и поля, специфичные для источника: repo для источников GitHub, url для источников Git и URL, а также path для локальных источников. Источники GitHub и Git также включают поле ref, когда marketplace был добавлен с закрепленной веткой или тегом.

Plugin marketplace remove

Удалите настроенный marketplace. Также принимается псевдоним rm.

claude plugin marketplace remove <name> [options]

Аргументы:

• <name>: имя marketplace для удаления, как показано в claude plugin marketplace list. Это name из marketplace.json, а не источник, который вы передали в add

Параметры:

Plugin marketplace update

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

claude plugin marketplace update [name]

Аргументы:

• [name]: имя marketplace для обновления, как показано в claude plugin marketplace list. Обновляет все marketplace, если опущено

Оба remove и update не удаются при запуске против seed-управляемого marketplace, который доступен только для чтения. При обновлении всех marketplace записи, управляемые seed, пропускаются, и другие marketplace все еще обновляются. Чтобы изменить плагины, предоставленные seed, попросите вашего администратора обновить образ seed. См. Предварительное заполнение плагинов для контейнеров.

Устранение неполадок

Marketplace не загружается

Симптомы: Не удается добавить marketplace или увидеть плагины из него

Решения:

• Проверьте, что URL marketplace доступен
• Убедитесь, что .claude-plugin/marketplace.json существует по указанному пути
• Убедитесь, что синтаксис JSON действителен, используя claude plugin validate . или /plugin validate . из каталога marketplace. Чтобы проверить frontmatter skill, agent и command, см. Валидация плагина или каталога без манифеста
• Для частных репозиториев подтвердите, что у вас есть разрешения доступа

Ошибки валидации marketplace

Запустите claude plugin validate . или /plugin validate . из каталога вашего marketplace, чтобы проверить наличие проблем. Когда валидатор указывает на каталог marketplace, он проверяет marketplace.json на ошибки схемы, дублирующиеся имена плагинов и обход пути источника. Для каждой записи, чей source является локальным путем, он также валидирует собственный plugin.json этого плагина и предупреждает, когда version записи не совпадает с версией в plugin.json. Проблемы, найденные в plugin.json плагина, имеют префикс с индексом записи в форме plugins[2] plugin.json →.

Начиная с Claude Code v2.1.196, проверка для каждой записи также:

• включает плагины, чей source является .
• запускается, когда marketplace.json находится вне каталога .claude-plugin, разрешая источники относительно собственного каталога файла
• сообщает о проблемах каждой записи даже когда другая часть файла имеет ошибки схемы

Более ранние версии пропускают плагины в корне marketplace и спускаются только из .claude-plugin/marketplace.json.

Из каталога marketplace Claude Code не открывает файлы skill, agent, command или hook плагинов. Чтобы найти ошибки в этих файлах, см. Валидация плагина или каталога без манифеста. В таблице ниже перечислены наиболее распространенные ошибки из каталога marketplace с причиной и решением для каждой:

Предупреждения (не блокирующие):

• Marketplace has no plugins defined: добавьте хотя бы один плагин в массив plugins
• No marketplace description provided: добавьте описание верхнего уровня description, чтобы помочь пользователям понять ваш marketplace
• Plugin name "x" is not kebab-case: переименуйте в строчные буквы, цифры и дефисы только (например, my-plugin). Claude Code принимает другие формы, но синхронизация marketplace claude.ai их отклоняет.
• Marketplace name "x" is reserved in Claude Desktop: marketplace назван org, org-provisioned или unknown, в любом регистре. Claude Code принимает эти имена, но синхронизация управляемого marketplace Claude Desktop отклоняет весь marketplace. Переименуйте marketplace. До v2.1.221 claude plugin validate не запускал эту проверку.
• Marketplace name "x" is not accepted by Claude Desktop или Plugin name "x" is not accepted by Claude Desktop: Claude Desktop принимает имена длиной до 128 символов, состоящие из букв, цифр, ., _ и -, начинающиеся с буквы или цифры. Claude Code принимает другие формы, но синхронизация управляемого marketplace Claude Desktop отклоняет marketplace, чье имя не проходит проверку, и молча удаляет запись плагина, чье имя не проходит. Переименуйте marketplace или плагин. До v2.1.221 claude plugin validate не запускал эти проверки.

Валидация плагина или каталога без манифеста

Чтобы найти файлы skill, agent и command, чей frontmatter не парсится, запустите claude plugin validate и назовите каталог, который их содержит. Claude Code не смотрит вне каталога, который вы назвали. Каждый запуск, кроме одного, для плагина, который имеет plugin.json, требует Claude Code v2.1.233 или позже.

Выберите каталог для назначения

Claude Code проверяет разные файлы в зависимости от того, какой каталог вы назовете. Найдите то, что вы хотите проверить в первом столбце, и запустите команду из этой строки:

Проверка плагина, чей skill является его корневым `SKILL.md`

Когда вы запускаете claude plugin validate для каталога плагина, Claude Code не проверяет SKILL.md в корне плагина. Когда плагин находится в каталоге с именем skills, запустите команду дважды:

• Назовите этот каталог skills, чтобы проверить корневой SKILL.md плагина.
• Назовите каталог плагина, чтобы проверить остальное.

Когда плагин находится под другим именем, такое как plugins/, запуск каталога skills недоступен, и ни один запуск не проверяет его корневой SKILL.md.

Проверка файлов за символическими ссылками

Когда вы запускаете claude plugin validate, Claude Code не следует символическим ссылкам внутри каталога, который вы назвали. То, что он делает, зависит от того, где находится ссылка:

• Связанный каталог skills, agents или commands под корнем плагина или .claude: Claude Code предупреждает, что ничего в нем не было прочитано.
• Связанная запись внутри каталога skills, agents или commands: Claude Code пропускает ее и предупреждает, для каждого каталога, сколько записей оно пропустило, которые сессия загрузит.
• Каталог skills, agents или commands, который вы назвали, сам является символической ссылкой, или его родительский каталог .claude является: Claude Code сообщает об ошибке и ничего в нем не проверяет. Назовите реальный каталог вместо этого.

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

• Плагин, чей каталог skills ссылается на каталог skills соседнего плагина: назовите каталог соседнего плагина.
• Связанная запись skill в ~/.claude/skills или .claude/skills: Claude Code следует записи в сессии. Чтобы проверить ее, назовите каталог с именем skills, который содержит реальную папку.

Прочитайте результаты валидации

Чистый запуск заканчивается с Validation passed.

No manifest found in directory означает, что Claude Code не нашел plugin.json или marketplace.json там, и нет файла skill, agent или command в каталогах, которые он проверяет под ним. Назовите каталог skills, agents или commands, который содержит ваши файлы, вместо этого.

Две из ошибок, которые Claude Code сообщает из этих запусков, с исправлением для каждой:

• YAML frontmatter failed to parse: ...: исправьте YAML в блоке frontmatter файла skill, agent или command. До тех пор, пока вы это не сделаете, сессия не читает поля frontmatter из файла
• Invalid JSON syntax: ... на hooks/hooks.json: исправьте синтаксис JSON. До тех пор, пока вы это не сделаете, сессия загружает плагин без hooks в этом файле. Claude Code сообщает эту ошибку только в запуске плагина

В запуске плагина Claude Code также предупреждает о CLAUDE.md в корне плагина. Для путей, которые вы установили через поля пути компонента в plugin.json, Claude Code проверяет, что каждый путь существует, но не читает файлы там.

Ошибки установки плагина

Симптомы: Marketplace появляется, но установка плагина не удается

Решения:

• Проверьте, что URL источников плагинов доступны
• Убедитесь, что каталоги плагинов содержат необходимые файлы
• Для источников GitHub убедитесь, что репозитории являются общедоступными или у вас есть доступ
• Протестируйте источники плагинов вручную, клонируя/загружая их
• Если источник закрепляет как ref, так и sha, удаленная ветвь или тег не блокируют установку на большинстве хостов git, включая GitHub, GitLab и Bitbucket. На серверах, которые не поддерживают получение коммитов по SHA, таких как AWS CodeCommit, ref все еще должен существовать и закрепленный коммит должен быть достижим из него. Если установка все еще не удается, подтвердите, что закрепленный коммит все еще существует в репозитории

Ошибка аутентификации частного репозитория

Симптомы: Ошибки аутентификации при установке плагинов из частных репозиториев

Решения:

Для ручной установки и обновлений:

• Проверьте, что вы аутентифицированы у вашего поставщика Git (например, запустите gh auth status для GitHub)
• Проверьте, что ваш помощник учетных данных настроен: git config --global credential.helper
• Запустите git ls-remote <marketplace-url>, чтобы проверить, может ли git аутентифицироваться самостоятельно. Если git запрашивает имя пользователя или пароль, сначала сохраните учетные данные: для GitHub через HTTPS запустите gh auth setup-git, а для SSH удаленных хостов загрузите ваш ключ в ssh-agent

Для фоновых автоматических обновлений:

• По умолчанию фоновые обновления отключают помощники учетных данных Git для pull, поэтому pull не может аутентифицироваться через HTTPS. SSH удаленные хосты с загруженным ключом в ssh-agent все еще аутентифицируются. Неудачный pull запускает повторное клонирование с нуля, которое использует ваши сохраненные учетные данные, но может истечь по времени на больших репозиториях
• Установите CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1, чтобы сохранить существующий клон при сбое фонового pull
• Настройте помощник учетных данных Git, например gh auth setup-git, чтобы резервное повторное клонирование могло аутентифицироваться
• Если повторное клонирование истекает по времени на большом репозитории, увеличьте лимит с помощью CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
• Настройте переписывание URL Git, ограниченное репозиторием marketplace, чтобы фоновый pull аутентифицировался напрямую
• Или обновляйте частные marketplace вручную с помощью /plugin marketplace update <name>, которая использует ваши учетные данные

Обновления marketplace не работают в автономных средах

Симптомы: Marketplace git pull не удается в фоне, и Claude Code многократно пытается повторно клонировать, что не может успешно завершиться.

Причина: По умолчанию, когда git pull не удается, Claude Code пытается повторно клонировать с нуля. В автономных или изолированных средах повторное клонирование не удается так же, и восстановление предыдущего кэша после этого является наилучшим усилием. Обновление запускается в фоне после запуска, поэтому оно не задерживает запуск, но каждая сессия повторяет неудачные попытки и каждая операция Git может ждать 120-секундного таймаута.

Решение: Установите CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1, чтобы пропустить попытку повторного клонирования и продолжить использование существующего кэша при сбое pull:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Для полностью автономных развертываний, где репозиторий никогда не будет доступен, используйте CLAUDE_CODE_PLUGIN_SEED_DIR для предварительного заполнения каталога плагинов во время сборки вместо этого.

Операции Git истекают по времени

Симптомы: Установка плагина или обновление marketplace не удается с ошибкой истечения времени, например "Git clone timed out after 120s" или "Git pull timed out after 120s".

Причина: Claude Code использует 120-секундный таймаут для всех операций Git, включая клонирование репозиториев плагинов и извлечение обновлений marketplace. Большие репозитории или медленные сетевые соединения могут превысить этот лимит.

Решение: Увеличьте таймаут, используя переменную окружения CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS. Значение указывается в миллисекундах:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 минут

Плагины с относительными путями не работают в marketplace на основе URL

Симптомы: Добавлен marketplace через URL, такой как https://example.com/marketplace.json, но плагины с источниками относительных путей, такие как "./plugins/my-plugin", не устанавливаются с ошибкой its marketplace entry path does not stay inside the marketplace directory. Уже установленные плагины не загружаются с ошибкой Plugin source path refused. Обе сообщения имеют запись справки об ошибке.

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

Решения:

• Используйте внешние источники: измените записи плагинов на любой источник плагина, кроме относительного пути:

  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  

• Используйте marketplace на основе Git: Разместите ваш marketplace в репозитории Git и добавьте его с URL Git. Marketplace на основе Git клонируют весь репозиторий, что делает относительные пути рабочими.

Файлы не найдены после установки

Симптомы: Плагин устанавливается, но ссылки на файлы не работают, особенно файлы вне каталога плагина

Причина: Плагины копируются в каталог кэша, а не используются на месте, кроме command источника в режиме link. Пути, которые ссылаются на файлы вне скопированного каталога плагина (такие как ../shared-utils), не будут работать, потому что эти файлы не копируются.

Решения: См. Кэширование плагинов и разрешение файлов для обходных путей, включая символические ссылки и переструктурирование каталогов.

Для дополнительных инструментов отладки и распространенных проблем см. Инструменты отладки и разработки.

См. также

• Обнаружение и установка готовых плагинов - Установка плагинов из существующих marketplace
• Плагины - Создание собственных плагинов
• Справка плагинов - Полные технические спецификации и схемы
• Параметры плагинов - Параметры конфигурации плагинов
• Справка strictKnownMarketplaces - Ограничения управляемого marketplace