Создание и распространение 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"
}

{
"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.

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

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

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

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

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

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

После того как плагин клонирован или скопирован на локальную машину, он копируется в локальный кэш плагинов с версией в ~/.claude/plugins/cache.

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

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

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

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

{
  "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.

Репозитории 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"
  }
}

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

Этот пример показывает запись плагина, использующую множество дополнительных полей, включая пользовательские пути для команд, агентов, 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_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 поддерживает установку плагинов из частных репозиториев. Для ручной установки и обновлений Claude Code использует ваши существующие помощники учетных данных Git, поэтому доступ HTTPS через gh auth login, macOS Keychain или git-credential-store работает так же, как в вашем терминале. Доступ SSH работает, пока хост уже находится в вашем файле known_hosts и ключ загружен в ssh-agent, так как Claude Code подавляет интерактивные подсказки SSH для отпечатка хоста и пароля ключа.

Фоновые автоматические обновления запускаются при запуске без помощников учетных данных, так как интерактивные подсказки блокировали бы запуск Claude Code. Чтобы включить автоматические обновления для частных marketplace, установите соответствующий токен аутентификации в вашей среде:

Установите токен в конфигурацию вашей оболочки (например, .bashrc, .zshrc) или передайте его при запуске Claude Code:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Тестирование локально перед распространением

Протестируйте ваш marketplace локально перед совместным использованием:

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

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

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

Вы можете настроить ваш репозиторий так, чтобы члены команды автоматически получали предложение установить ваш 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
  }
}

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

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

Для образов контейнеров и сред 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.

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

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

Отключение всех добавлений marketplace:

{
  "strictKnownMarketplaces": []
}

Разрешение только определенных 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 с внутреннего сервера 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: repo обязателен, и ref или path также должны совпадать, если указаны в списке разрешений
• Для источников URL: полный URL должен совпадать точно
• Для источников hostPattern: хост marketplace сопоставляется с шаблоном регулярного выражения
• Для источников pathPattern: путь файловой системы marketplace сопоставляется с шаблоном регулярного выражения

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

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

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

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

Версии плагинов определяют пути кэша и обнаружение обновлений: если разрешенная версия совпадает с тем, что уже есть у пользователя, /plugin update и автоматическое обновление пропускают плагин.

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

1. version в plugin.json плагина
2. version в записи marketplace плагина
3. SHA коммита Git источника плагина

Для типов источников на основе Git github, url, git-subdir и относительных путей внутри marketplace, размещенного на Git, вы можете полностью опустить version и каждый новый коммит будет рассматриваться как новая версия. Это самая простая установка для внутренних или активно разрабатываемых плагинов.

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

Для поддержки каналов выпуска "stable" и "latest" для ваших плагинов вы можете установить два marketplace, которые указывают на разные refs или SHAs одного репозитория. Затем вы можете назначить два 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 перед совместным использованием.

Проверьте синтаксис JSON вашего marketplace:

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 и поля, специфичные для источника: 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 из их источников, чтобы получить новые плагины и изменения версий.

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. Чтобы проверить 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.

Чтобы валидировать plugin.json отдельного плагина и его файлы skill, agent, command и hook, запустите команду для самого каталога плагина, например claude plugin validate ./plugins/my-plugin. Распространенные ошибки:

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

• 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 появляется, но установка плагина не удается

Решения:

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

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

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

Решения:

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

• Проверьте, что вы аутентифицированы у вашего поставщика Git (например, запустите gh auth status для GitHub)
• Проверьте, что ваш помощник учетных данных настроен правильно: git config --global credential.helper
• Попробуйте клонировать репозиторий вручную, чтобы проверить, что ваши учетные данные работают

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

• Установите соответствующий токен в вашей среде: echo $GITHUB_TOKEN
• Проверьте, что токен имеет необходимые разрешения (доступ на чтение к репозиторию)
• Для GitHub убедитесь, что токен имеет область repo для частных репозиториев
• Для GitLab убедитесь, что токен имеет как минимум область read_repository
• Проверьте, что токен не истек

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

Симптомы: Marketplace git pull не удается и Claude Code удаляет существующий кэш, что делает плагины недоступными.

Причина: По умолчанию, когда git pull не удается, Claude Code удаляет устаревший клон и пытается повторно клонировать. В автономных или изолированных средах повторное клонирование не удается так же, оставляя каталог marketplace пустым.

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

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

С этой переменной установленной, Claude Code сохраняет устаревший клон marketplace при сбое git pull и продолжает использовать последнее известное хорошее состояние. Для полностью автономных развертываний, где репозиторий никогда не будет доступен, используйте 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", не устанавливаются с ошибками "path not found".

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

Решения:

• Используйте внешние источники: Измените записи плагинов, чтобы использовать источники GitHub, npm или URL Git вместо относительных путей:

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

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

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

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

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

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

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

См. также

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