Размещение и поддержка маркетплейса

​

Host your marketplace

​

Register the marketplace for everyone in a repository

​

Avoid relative-path entries in a URL-hosted marketplace

​

Edit plugins in place on a shared directory

​

Keep plugin files out of Git LFS

​

Share files within a marketplace with symlinks

• В собственном каталоге плагина: символическая ссылка сохраняется как относительная символическая ссылка в кэше, поэтому она продолжает разрешаться скопированной цели во время выполнения.
• В другом месте в том же marketplace: символическая ссылка разыменовывается. Содержимое цели копируется в кэш на его место. Это позволяет каталогу skills/ мета-плагина ссылаться на навыки, определенные другими плагинами в marketplace.
• Вне marketplace: символическая ссылка пропускается в целях безопасности.

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

Distribute through organization settings

• Репозиторий Marketplace: на github.com и gitlab.com он должен быть приватным или внутренним
• Источники плагинов: каждый источник плагина должен быть типа github, url или git-subdir, или относительный путь, который начинается с ./
• Каталог bin/ верхнего уровня: claude.ai отклоняет плагин, который его имеет, и синхронизирует остальную часть marketplace. Сообщение об ошибке начинается с Plugin contains a top-level bin/ directory. Держите исполняемые файлы в другом каталоге, таком как scripts/, и ссылайтесь на них как ${CLAUDE_PLUGIN_ROOT}/scripts/<name> из ваших hooks или конфигов MCP сервера

​

Grant access to a private marketplace

• GitHub owner/repo: Claude Code проверяет ssh -T git@github.com и клонирует по SSH, когда проверка успешна. Если проверка не удается, или сам SSH клон не удается, он клонирует по HTTPS. Пользователи на машинах без ключа GitHub SSH могут установить CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1, чтобы пропустить проверку и клонировать по HTTPS.
• git@host:path.git: SSH.
• https://example.com/repo.git: HTTPS.

• SSH: ключ должен работать без подсказки парольной фразы, например потому что он загружен в ssh-agent. Хост должен уже быть в known_hosts.
• HTTPS: Claude Code оставляет помощника учетных данных git пользователя включенным, но запрещает ему подсказывать. Учетные данные, которые помощник уже хранит, работают; те, которые ему пришлось бы просить, не работают. На GitHub запустите gh auth login, затем gh auth setup-git, чтобы сохранить один.

​

Serve users who have no git-host account

• archive: zip, загруженный по HTTPS. Пользователям не нужны ни git, ни учетная запись, только сетевой доступ к URL. Требует Claude Code v2.1.224 или позже. Закрепите каждый архив с sha256, чтобы Claude Code отказал в измененной загрузке. Чтобы отправить учетные данные с загрузкой, смотрите Authenticate archive downloads.
• Публичный git репозиторий: Claude Code клонирует публичный источник url или git-subdir по HTTPS без учетных данных, когда запись дает URL https://. Для источника github или источника git-subdir, написанного как owner/repo, пользователи без набора ключа GitHub SSH устанавливают CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1.

​

What background auto-update does with credentials

• SSH удаленные: ключ, загруженный в ssh-agent, аутентифицирует проверку.
• HTTPS удаленные с сохраненными учетными данными: помощник, который может предоставить сохраненные учетные данные без подсказки, аутентифицирует проверку. Git Credential Manager, помощник macOS Keychain и git-credential-store работают таким образом, как только они держат учетные данные для хоста.
• HTTPS удаленные с помощником, который нужно подсказать: помощник не может ответить в фоне. Обновление не удается тихо и существующий checkout остается на месте, поэтому плагины пользователя продолжают работать из последнего синхронизированного состояния.

• Checkout актуален: Claude Code оставляет его как есть.
• Проверка находит новые коммиты, или не удается, потому что не может достичь или аутентифицировать удаленное: Claude Code клонирует marketplace снова и заменяет существующий checkout новым клоном. Если этот клон не удается, существующий checkout остается на месте. Повторный клон может истечь по времени на больших репозиториях.

• Сохранить учетные данные: сначала войдите в помощника учетных данных, чтобы он держал учетные данные для хоста. Для GitHub запустите gh auth login, затем gh auth setup-git.
• Держать checkout при сбое: если пользователь установит CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1, Claude Code держит существующий checkout без попытки повторного клона, когда фоновая проверка не может достичь или аутентифицировать удаленное. Плагины продолжают работать из последнего синхронизированного состояния.

​

Roll out to a whole company

• Источники записей, которые не нуждаются в учетной записи git: Serve users who have no git-host account
• Предварительно заполненный каталог плагинов: Seed containers and CI, который также служит пользователям, у которых нет учетной записи git-хоста
• claude.ai organization settings: Distribute through organization settings, где учетные данные git ваших пользователей не задействованы

​

Keep users up to date

​

Turn on auto-update

• Скажите пользователям включить его: каждый пользователь идет в Marketplaces в /plugin, выбирает ваш marketplace и выбирает Enable auto-update.
• Попросите администратора установить его: если администратор установит "autoUpdate": true на записи extraKnownMarketplaces вашего marketplace в управляемых параметрах, оно включено для всех, кто получает эти параметры. Смотрите Set update policy.

​

Release a new version

• Увеличьте version при каждом выпуске: пользователи остаются на своей кэшированной копии, пока строка не изменится. Если вы установите "version": "1.0.0" и отправите новые коммиты без изменения его, пользователи их не получат.
• Опустите version: пользователи отслеживают ваши коммиты вместо этого. Оставьте version вне обоих plugin.json и записи marketplace.

​

Hold users on one version

• ref и sha на записи плагина: ref называет ветку или тег и sha называет коммит для источника github, url или git-subdir. Смотрите Plugin sources.
• #<ref> на команде добавления: пользователи, которые добавляют your-org/your-marketplace#stable, получают эту ветку или тег каталога. Для двух линий выпуска одновременно, смотрите Run release channels.
• <plugin>--v<version> теги: диапазон версий зависимости разрешается против этих тегов. Смотрите Release a plugin that others depend on.

​

Change the command of a command source

• Нет больше фоновых запусков: однократный запуск в сеансе команды останавливается для этого пользователя, поэтому новый вывод инструмента не достигает их.
• Запись на вкладке /plugin Errors: запись показывает новую команду и команду claude plugin update для запуска.

​

Run release channels

{
  "name": "stable-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "stable" } }
  ]
}

{
  "name": "latest-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "latest" } }
  ]
}

​

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

​

Миграция пользователей с помощью карты переименований

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

• Переименованная запись: плагин загружается под своим новым именем. claude plugin list и детали плагина в /plugin показывают Renamed to "code-formatter" in the "your-marketplace" marketplace один раз, и Claude Code переписывает старый ключ на новый в enabledPlugins и pluginConfigs в пользовательских, проектных и локальных областях настроек.
• Запись null: старый ключ удаляется из этих областей и пользователь видит Removed from the "your-marketplace" marketplace.
• Включено в управляемые настройки: плагин всё ещё загружается под своим новым именем, но Claude Code не может переписать управляемые настройки, поэтому уведомление повторяется до тех пор, пока администратор не обновит enabledPlugins там.

​

Удаление удалённых плагинов с машин пользователей

1. Сравнивает то, что пользователи установили из вашего marketplace, с записями и картой renames, и рассматривает любой плагин, который ни указан в списке, ни переименован, как удалённый.
2. Удаляет каждый удалённый плагин из пользовательской, проектной и локальной областей. Плагины, которые установили только управляемые настройки, остаются на месте.
3. Перечисляет каждый удалённый плагин под заголовком Flagged в /plugin со статусом Removed from marketplace.

​

Authenticate archive downloads

• Источник url marketplace: источник url, из которого вы зарегистрировали marketplace, такой как запись extraKnownMarketplaces.
• Запись плагина: на Claude Code v2.1.238 или позже, вы можете установить его на записи marketplace.json плагина вместо этого, рядом с source.

​

Add a headersHelper to a plugin entry

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

​

Write the headersHelper command

• Текст команды: максимум 500 символов печатного ASCII, без запуска четырех или более пробелов.
• Вывод: выведите один объект JSON имен заголовков и строковых значений на stdout, затем выйдите 0 в течение 10 секунд.
• Оболочка и рабочий каталог: Claude Code запускает команду через sh, или через cmd.exe на Windows. Рабочий каталог — это каталог конфигурации, который является ~/.claude или CLAUDE_CONFIG_DIR. Дайте абсолютный путь или команду на PATH, потому что относительный путь разрешается против этого каталога, а не проекта пользователя.
• Переменные, которые Claude Code удаляет: когда команда установлена в записи marketplace.json, или в проектном .claude/settings.json или .claude/settings.local.json, Claude Code удаляет из окружения каждую переменную, чье имя выглядит как учетные данные, по тому же правилу, которое оно применяет к MCP headersHelper. ANTHROPIC_API_KEY и MY_REGISTRY_TOKEN оба удаляются, поэтому имейте команду, читающую свои учетные данные из файла или хранилища учетных данных. Это удаление не применяется к команде, установленной в пользовательских параметрах, файле --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"}

​

When Claude Code skips a headersHelper command or drops its output

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

​

How users accept a headersHelper command

​

Installs and updates that refuse a command instead of asking

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

​

When a marketplace url source’s command runs

​

Depend on and recommend other plugins

• Диапазоны версий: зависимость может нести диапазон semver.
• Кросс-marketplace зависимости: зависимость от другого marketplace устанавливается только когда ваш marketplace перечисляет этот marketplace в allowCrossMarketplaceDependenciesOn.

​

Work around what a marketplace can’t do

• Ограничить то, что еще устанавливают пользователи: список разрешений marketplace — это управляемый параметр, strictKnownMarketplaces. Смотрите Restrict what users can install.
• Установить или включить плагин без того, чтобы пользователь просил: ни одно поле записи не устанавливает плагин. Управляемый enabledPlugins делает это для флота; смотрите Pre-install and require plugins.
• Показать разные записи разным пользователям: записи не несут поле аудитории, и каждый пользователь, который добавляет marketplace, видит весь каталог. Разместите отдельные marketplaces для отдельных аудиторий.
• Отметить плагин устаревшим: нет состояния устаревания. Вариант — удалить запись, сопоставить ее имя с null в renames и опционально установить forceRemoveDeletedPlugins.
• Включить auto-update для ваших пользователей: каждый пользователь включает его в Marketplaces в /plugin, или администратор устанавливает autoUpdate в управляемых параметрах. Смотрите Turn on auto-update.
• Нести git учетные данные: ни одно поле marketplace не держит git токен. Доступ к marketplace или плагину, размещенному на git, следует настройке git пользователя, согласно Grant access to a private marketplace. Для источников archive, запись может установить headers или headersHelper вместо этого.

​

Next steps

• Marketplace reference: поля marketplace.json, типы источников и сообщения валидации
• Manage plugins for your organization: требуйте, ограничивайте или заполняйте ваш marketplace на машинах вашей организации
• Plugin dependencies: отмечайте выпуски, чтобы плагины, которые зависят от вашего, могли разрешать версии
• Troubleshoot plugins: ошибки, которые видят ваши пользователи при добавлении или обновлении из вашего marketplace