Справочник Marketplace

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

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

Источник marketplace — это отдельный объект, который указывает, откуда Claude Code загружает сам файл marketplace. Вы пишете его в параметрах, или Claude Code создаёт его при запуске claude plugin marketplace add.

Этот справочник предназначен для разработчиков marketplace, которым нужно точное имя или значение поля, и для администраторов, которым нужно знать, какие значения source действительны в extraKnownMarketplaces, strictKnownMarketplaces и blockedMarketplaces.

Найдите раздел для того, что вы пишете или читаете:

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

Файл marketplace

Сохраняйте файл marketplace в .claude-plugin/marketplace.json в директории вашего marketplace. Если вы храните файл в другом месте репозитория, пользователи должны объявить marketplace в extraKnownMarketplaces с установленным path на его источник, потому что claude plugin marketplace add не имеет для этого опции.

Директория, которая содержит .claude-plugin/, называется корневой директорией marketplace, и каждый относительный источник плагина разрешается из неё, а не из .claude-plugin/.

Каждый пользователь регистрирует один marketplace на name, поэтому пользователь не может иметь два marketplace с одинаковым именем, зарегистрированные одновременно.

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

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

Вы не можете дать вашему 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.

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

Таблица перечисляет каждый ключ, который Claude Code читает из marketplace.json. name, owner и plugins являются обязательными.

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

Каждый объект в массиве plugins верхнего уровня marketplace.json называет плагин и указывает, откуда его загружать. name и source являются обязательными.

Запись также принимает каждое поле plugin.json, такое как description, version, author, commands и hooks. Для того, когда эти поля применяются, см. Как запись объединяется с plugin.json.

Таблица перечисляет собственные поля записи и поля манифеста, чьё значение изменяется в записи.

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

Поля записи применяются по-разному к загруженному плагину, который имеет свой собственный .claude-plugin/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 в записи

Напишите запись hooks как встроенный объект, который сопоставляет имена событий hook с массивами сопоставителей. Если вы напишете путь к файлу или массив вместо этого, claude plugin validate пройдёт. Эти hooks никогда не запускаются, и Claude Code сообщает об ошибке not yet supported in a marketplace entry для плагина. Поместите hooks на основе файлов в собственный hooks/hooks.json плагина или plugin.json.

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

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

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

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

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

strict решает, что происходит, когда загруженный плагин имеет свой собственный plugin.json и запись также объявляет любое из полей компонентов: commands, agents, skills, hooks, outputStyles или themes. При strict: true, по умолчанию, Claude Code добавляет поля компонентов записи к plugin.json, кроме hooks, чьи сопоставители заменяют сопоставители манифеста на событие. При strict: false, запись, которая объявляет любое поле компонента, является конфликтом, и плагин не загружается. Таблица показывает каждую комбинацию strict, plugin.json и полей компонентов записи.

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

source записи плагина указывает, откуда Claude Code загружает этот плагин. Это либо строка относительного пути, либо объект, чей собственный ключ source называет тип, поэтому запись выглядит как "source": { "source": "github", "repo": "your-org/formatter" }.

Таблица перечисляет каждый тип источника плагина и его поля.

Имена url и github также являются типами источника marketplace, где url означает прямую ссылку на файл marketplace.json вместо git-репозитория. git существует только как источник marketplace, и npm существует как оба. git-subdir, archive и command существуют только как источники плагинов.

Используйте относительный путь для плагина в подкаталоге самого репозитория marketplace. Используйте git-subdir для подкаталога какого-то другого репозитория.

Источники github, url и git-subdir совместно используют поля ref и sha:

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

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

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

Путь разрешается от корня marketplace. ./plugins/formatter — это <root>/plugins/formatter, даже хотя файл marketplace находится в <root>/.claude-plugin/.

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

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

Относительный путь разрешается только, когда Claude Code имеет файлы marketplace, поэтому проверьте тип источника marketplace:

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

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

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

metadata.pluginRoot имеет эти ограничения:

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

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

repo принимает owner/repo. ref и sha опциональны.

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

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

url — это полный git URL: https://, http://, file:// или git@. Суффикс .git не требуется, поэтому URL Azure DevOps и AWS CodeCommit работают как написано. Этот тип не принимает сокращение owner/repo.

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

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

url принимает полный git URL или сокращение GitHub owner/repo. path — это подкаталог, который содержит плагин, и Claude Code загружает только этот подкаталог.

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

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

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

• package: имя пакета или имя с областью видимости, такое как @your-org/formatter
• version: версия или диапазон
• registry: URL реестра для пакета, который не находится в реестре по умолчанию

Claude Code загружает пакет с вашим npm-клиентом. Скрипты установки пакета, такие как preinstall или postinstall, никогда не запускаются, и его зависимости не устанавливаются во время загрузки. Если пакет имеет поддерживаемый файл блокировки рядом с его package.json, Claude Code устанавливает эти зависимости пакетов Node.js в отдельном шаге, также с отключёнными скриптами.

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

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

url должен использовать https:// и не может указывать на хост обратной связи, локальной связи или облачных метаданных.

Корень плагина может быть в верхней части zip или на один каталог ниже.

sha256 — это дайджест архива как 64 шестнадцатеричных символа, прописные или строчные. Когда вы его устанавливаете, Claude Code отказывает в загрузке, которая не совпадает.

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

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

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

Источник 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
  }
}

Для того, как пользователи принимают команду, см. Установка из вашей оболочки. Для того, что пользователи видят после того, как вы её измените, см. Изменение команды источника command. Администраторы отключают источники command с disableCommandPluginSources.

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

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

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

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

Установка или обновление не удаётся, когда команда выходит с ненулевым кодом, работает дольше timeout или выводит что-либо, кроме одного абсолютного пути. Это также не удаётся, когда выведённый каталог является одним из этих:

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

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

mode решает, копирует ли Claude Code выведённый каталог или использует его на месте:

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

Плагин в режиме ссылки имеет эти требования:

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

Источники Marketplace

Источник marketplace указывает, откуда Claude Code загружает marketplace.json. CLI создаёт один для вас при добавлении marketplace, и вы пишете один сами в параметрах:

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

Имена типов url, git и github означают что-то другое в источнике marketplace, чем в источнике плагина:

Таблица перечисляет каждый тип источника marketplace с его полями, вводом claude plugin marketplace add, который его производит, и что он делает в каждом из трёх ключей параметров.

Поля по типам

Таблица перечисляет каждое поле источника marketplace, которое имеет значение по умолчанию, ограничение или значение, специфичное для его типа.

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

hostPattern, pathPattern, skills-dir и форма owner/* из repo действительны только в двух списках политик, strictKnownMarketplaces и blockedMarketplaces:

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

Для порядка совпадения, точной семантики ref и рецептов см. Управление плагинами для вашей организации.

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

Значение extraKnownMarketplaces — это карта от имени marketplace к объекту с source. Эта запись регистрирует marketplace из git-репозитория в его ветке main:

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

strictKnownMarketplaces и blockedMarketplaces — это массивы объектов источников. Этот список разрешений допускает одного владельца GitHub и один внутренний хост:

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

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

claude plugin validate <path> принимает корень marketplace или сам файл marketplace. Он выводит ошибки и предупреждения. Для кодов выхода и --strict см. plugin validate.

Сообщение называет запись плагина по её индексу, написанному как plugins.1.source или plugins[1].source.

Сообщение с префиксом индекса записи и plugin.json →, такое как plugins[2] plugin.json →, касается собственных файлов этого плагина. claude plugin validate сообщает об ошибках перечисляет эти сообщения с их исправлениями.

Предупреждения, которые упоминают имена флагов Claude Desktop, флаги, которые Claude Code принимает, но Claude Desktop отклоняет, потому что правила имён Claude Desktop более строгие.

Таблица сопоставляет сообщения уровня marketplace с полем, которое каждое касается.

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

Invalid input на source означает, что объект не совпадал с типом источника. Проверьте эти причины:

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

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

claude plugin validate не сообщает о каждом сбое. Запись hooks, написанная как путь к файлу или массив, проходит валидацию, и ошибка появляется только при загрузке плагина, как описывает Hooks в записи. Ошибки загрузки source также появляются только после установки, а не при валидации.

claude plugin list показывает плагин, который не загрузился, с его ошибкой, и Устранение неполадок плагинов охватывает строки загрузки.

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

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