Справочник Marketplace

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

​

Файл marketplace

​

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

• Имена официального 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.
• Другое написание зарезервированного имени: имя, которое отличается от зарезервированного имени только конечной точкой, или символом, отличным от подчёркивания, вместо дефиса, поэтому claude.code.plugins считается claude-code-plugins. claude plugin validate принимает такое имя; добавление 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 или позже.
• Имена, начинающиеся с 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.

​

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

​

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

​

Как запись объединяется с 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.

​

Hooks в записи

​

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

• Для поля, которое вы устанавливаете в записи, пользователи видят значение записи, даже когда 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: относительные пути отклоняются сразу.

​

Имена без префикса под 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
• version: версия или диапазон
• registry: URL реестра для пакета, который не находится в реестре по умолчанию

{
  "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, плагины каталога skills перестают загружаться, пока вы не добавите {"source": "skills-dir"} в этот список.
• 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$" }
  ]
}

​

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

​

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

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

​

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

​

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

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