Справочник Marketplace

• Файл marketplace: Поля верхнего уровня и Записи плагинов
• source записи: Источники плагинов
• Объект source в параметрах: Источники marketplace
• Вывод из claude plugin validate <path>: Сообщения валидации, которые сопоставляют каждое сообщение с полем, которое оно называет

​

Файл маркетплейса

​

Зарезервированные имена

• Имена официального marketplace: claude-code-marketplace, claude-code-plugins, claude-plugins-official, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, life-sciences, knowledge-work-plugins, claude-for-legal, claude-for-financial-services, financial-services-plugins, first-party-plugins и claude-tag-plugins. Зарезервированы, если только marketplace не поступает из источника github или git marketplace source под github.com/anthropics/.
• Имена community marketplace: claude-community, claude-plugins-community и healthcare. Зарезервированы по тому же правилу, что и официальные имена.
• Имена директории плагинов: anthropic-plugin-directory и claude-plugin-directory. Зарезервированы по тому же правилу, что и официальные имена.
• Имена, выдающие себя за официальный marketplace: имена такие как official-claude-plugins или claude-plugins-v2, и любое имя, содержащее символ, отличный от ASCII. Ошибка: Marketplace name impersonates an official Anthropic/Claude marketplace. Управляющий символ или символ двунаправленного форматирования в имени также сообщает Marketplace name cannot contain control or bidirectional-formatting characters. Marketplace, уже зарегистрированный под таким именем, перестаёт загружаться, вместе с его плагинами.
• Другое написание зарезервированного имени: имя, которое отличается от зарезервированного имени только конечной точкой, или символом, отличным от подчёркивания, вместо дефиса, поэтому claude.code.plugins считается claude-code-plugins. Добавление marketplace завершается ошибкой is another spelling of "<reserved>", a reserved marketplace name, и marketplace, уже зарегистрированный под одним, перестаёт загружаться. Эта проверка требует Claude Code v2.1.280 или позже.
• Имена, которые Claude Code использует для плагинов, которые не поступают из marketplace: inline для плагинов, загруженных с --plugin-dir, builtin для встроенных плагинов, skills-dir для плагинов, автоматически загруженных из .claude/skills/, и synced для плагинов, синхронизированных с вашего аккаунта claude.ai. claude-plugin-test также зарезервирован. skills-dir также появляется как {"source": "skills-dir"} в strictKnownMarketplaces и blockedMarketplaces, описанные в разделе Source values valid only in policy lists.
• npm, pip, uv, cargo, github и gh: зарезервированы в любом регистре. Эта проверка требует Claude Code v2.1.275 или позже.
• Имена членов, которые есть у каждого объекта JavaScript: constructor, hasOwnProperty, isPrototypeOf, propertyIsEnumerable, toLocaleString, toString и valueOf. claude plugin marketplace add отклоняет маркетплейс, использующий одно из них, с ошибкой Claude Code reserves this name and cannot register a marketplace under it. Эта проверка требует Claude Code v2.1.296 или позже.
• Имена, начинающиеся с claudeai-: зарезервированы для marketplace, размещённых на claude.ai. claude plugin marketplace add отказывает любому другому marketplace, который использует один с Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai.
• Папка загрузки зарегистрированного GitHub marketplace, <owner>-<repo>: Claude Code загружает marketplace, добавленный из источника github, например acme/x-tools, через папку с именем acme-x-tools, каким бы ни было собственное name этого marketplace. Пока этот marketplace зарегистрирован под именем, отличным от acme-x-tools, claude plugin marketplace add отказывает другому marketplace с именем acme-x-tools после его загрузки и сообщает Can't use the marketplace name "acme-x-tools". Эта проверка требует Claude Code v2.1.290 или позже.

​

Поля верхнего уровня

​

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

​

Как запись объединяется с plugin.json

• Нет plugin.json: запись является манифестом независимо от strict. Применяется каждое поле манифеста, которое принимает запись, включая mcpServers, lspServers, userConfig и channels.
• plugin.json присутствует: plugin.json является манифестом. Строгий режим решает, объединяются ли шесть полей компонентов записи, commands, agents, skills, hooks, outputStyles и themes, с ним или отклоняются как конфликт. Поля записи mcpServers, lspServers, userConfig и channels не применяются. Объявите их в plugin.json.

​

Хуки в записи

​

Поля отображения

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

​

Строгий режим

​

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

• ref: ветка или тег. По умолчанию ветка репозитория по умолчанию.
• sha: полный 40-символьный SHA коммита в нижнем регистре. Когда вы устанавливаете оба ref и sha, Claude Code проверяет sha. На большинстве git-хостов, включая GitHub, GitLab и Bitbucket, это означает, что установка успешна, даже если ветка или тег, названные ref, были удалены выше по течению, пока коммит всё ещё достижим из репозитория. Некоторые серверы, такие как AWS CodeCommit, не поддерживают загрузку коммитов по SHA. На этих серверах ref всё ещё должен существовать и закреплённый коммит должен быть достижим из него.

​

Источник плагина с относительным путём

{ "name": "formatter", "source": "./plugins/formatter" }

• github, git, file и directory: Claude Code имеет файлы marketplace.
• url: Claude Code загружает только marketplace.json, поэтому относительные пути не могут разрешаться. Дайте каждому плагину источник объекта вместо этого, такой как github или git-subdir.
• settings: относительные пути отклоняются сразу.

​

Подмодули Git в репозитории маркетплейса

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

• Каталог компонентов: каталог в корне, содержащий компоненты плагина, такой как skills/, hooks/ или bin/
• Путь в конфигурации плагина: путь в записи плагина в маркетплейсе, в его plugin.json или в файле конфигурации, таком как .mcp.json или hooks/hooks.json
• Символическая ссылка: ссылка, закоммиченная в репозиторий
• Текст в файлах плагина: путь подмодуля, такой как vendor/tool, записанный в файле конфигурации или в файле внутри каталога компонентов

• SKILL.md в корне: в этом случае весь репозиторий является каталогом одного скилла
• Файл, который Claude Code не может прочитать: файл маркетплейса, один из файлов конфигурации плагина или .gitmodules

​

Имена без префикса под pluginRoot

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

​

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

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

​

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

{
  "name": "formatter",
  "source": {
    "source": "url",
    "url": "https://gitlab.example.com/your-group/formatter.git",
    "ref": "main"
  }
}

​

Источник плагина git-subdir

{
  "name": "formatter",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/your-org/monorepo.git",
    "path": "tools/formatter"
  }
}

​

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

• package: имя пакета в реестре, такое как @your-org/formatter, имя с добавленной версией, такое как @your-org/formatter@2.0.0, или ссылка https на tarball-файл пакета
• version: версия, диапазон semver или dist-tag, используемые, когда package — это имя пакета без добавленной версии. Опустите его, чтобы загрузить latest
• registry: URL реестра для пакета, который не находится в реестре по умолчанию

• Git-адрес, путь к папке или file:, или псевдоним npm:: используйте источник github, url или git-subdir для git-репозитория, относительный путь для папки в маркетплейсе и собственное имя пакета для псевдонима
• Ссылка на tarball на github.com, gist.github.com, gitlab.com, bitbucket.org или git.sr.ht: отклоняется, даже если ссылка — это загрузка релиза GitHub, если только это не ссылка на npm-реестр GitLab под gitlab.com/api/v4/
• Ссылка на tarball через http: отклоняется, если только она не указывает на собственный npm-реестр по умолчанию устанавливающего пользователя

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

​

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

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

​

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

• command: команда оболочки, которая выводит абсолютный путь каталога плагина как одну строку и выходит 0. Claude Code показывает пользователям всю строку для проверки перед её запуском. Напишите её как печатаемый ASCII, максимум 500 символов, без прогона из четырёх или более пробелов.
• timeout: целое число секунд от 1 до 600. По умолчанию 60.
• mode: copy, по умолчанию, или link. См. Режим копирования и режим ссылки.

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

​

Что должна делать команда

• Оболочка и рабочий каталог: Claude Code запускает команду через sh или через cmd.exe на Windows из домашнего каталога пользователя. Дайте абсолютный путь или команду на PATH.
• Вывод: выведите ровно одну строку на stdout, абсолютный путь каталога плагина, и выйдите 0 в течение timeout секунд.
• Содержимое каталога: каталог содержит полный плагин к моменту выхода команды. Путь может отличаться от одного запуска к другому.

​

Вывод, который приводит к отказу установки или обновления

• Нет содержимого плагина: выведённый каталог не имеет содержимого плагина на его верхнем уровне, такого как каталог .claude-plugin/ или каталог skills/, commands/, agents/ или hooks/.
• Собственный каталог сеанса: выведённый каталог — это тот, в котором был запущен Claude Code, или один из его родителей.
• Сетевой путь: на Windows выведённый путь — это путь UNC.
• Слишком большой для копирования: в режиме копирования каталог больше 256 МиБ или имеет более 20 000 записей.

​

Режим копирования и режим ссылки

• copy: Claude Code копирует каталог в кэш плагина и выводит версию плагина из хэша скопированных файлов. Ваш инструмент может удалить или переписать каталог после выхода команды. Повторный запуск, который производит идентичные файлы, считается актуальным.
• link: Claude Code заполняет запись кэша плагина ссылкой на каждую запись верхнего уровня выведённого каталога и загружает файлы на месте. Ничего не копируется, содержимое файлов не хэшируется, и ограничения размера не применяются. Используйте его для каталога, слишком большого для копирования, такого как экспорт отображённого SDK.

• Держите каталог на месте: Claude Code загружает плагин через ссылки при каждом запуске, поэтому выведённый каталог должен оставаться там, где он находится, пока плагин остаётся установленным.
• Выведите другой путь, чтобы сигнализировать о новом содержимом: версия поступает из реального пути выведённого каталога и его записей верхнего уровня, а не из файлов внутри них.
• Держите символические ссылки верхнего уровня внутри каталога: установка не удаётся, если запись верхнего уровня — это символическая ссылка, которая указывает вне выведённого каталога.
• Включите node_modules: Claude Code пропускает установку зависимостей пакетов Node.js для плагина в режиме ссылки, поэтому выведите каталог, который уже содержит пакеты, которые нужны плагину.
• Сеансы, запущенные внутри каталога: сеанс, запущенный в выведённом каталоге или где-либо ниже, не загружает плагин.
• Не на Windows: Claude Code отказывает в установке плагина в режиме ссылки на Windows. Объявите "mode": "copy" там.

​

Источники Marketplace

• claude plugin marketplace add: Claude Code создаёт источник из строки, которую вы передаёте.
• extraKnownMarketplaces: вы пишете источник сами как объект source.
• strictKnownMarketplaces и blockedMarketplaces: администраторы пишут источники в этих двух списках политик. strictKnownMarketplaces — это список разрешений, а blockedMarketplaces — это список запретов.

​

Поля по типам

​

Значения источников, действительные только в списках политик

• hostPattern и pathPattern: регулярные выражения, которые Claude Code тестирует против источника перед загрузкой из него.
• skills-dir: не источник. Если вы задаёте strictKnownMarketplaces без записи {"source": "skills-dir"}, плагины каталога skills перестают загружаться. Если вы блокируете любой тип кастомизации с помощью strictPluginOnlyCustomization, они перестают загружаться независимо от того, присутствует ли эта запись.
• owner/*: как значение repo из github, совпадает с каждым репозиторием ровно под этим владельцем GitHub. Требует Claude Code v2.1.223 или позже.

​

Объекты источников в параметрах

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/your-org/your-marketplace.git",
        "ref": "main"
      }
    }
  }
}

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "your-org/*" },
    { "source": "hostPattern", "hostPattern": "^git\\.example\\.com$" }
  ]
}

​

Сообщения валидации

​

Неверный ввод на источнике

• npm package, содержащий ..
• Тип source, который не является одним из источников плагинов
• Известный тип с отсутствующим обязательным полем или неправильного типа, такой как github без repo

​

Сбои, которые валидация не ловит

​

Следующие шаги

• Создание marketplace: создайте marketplace из этих полей и установите его локально
• Размещение и поддержка marketplace: где поместить файл и как пользователи получают изменения
• Справочник манифеста плагина: поля plugin.json, которые запись может переопределить
• Управление плагинами для вашей организации: рецепты списков разрешений и запретов, которые используют эти значения источников