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

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

​

Создание файла marketplace

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

​

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

​

Поля владельца

​

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

​

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

​

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

​

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

​

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

​

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

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

​

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

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

​

Пакеты npm

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

​

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

{
  "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/", "./extra-skills/"]

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

​

Strict mode

• strict: true: плагин имеет собственный plugin.json и управляет своими компонентами. Запись marketplace может добавить дополнительные skills или hooks сверху. Это значение по умолчанию и работает для большинства плагинов.
• strict: false: оператор marketplace хочет полный контроль. Репозиторий плагина предоставляет необработанные файлы, и запись marketplace определяет, какие из этих файлов открыты как skills, агенты, hooks и т. д. Полезно, когда оператор marketplace переструктурирует или курирует компоненты плагина иначе, чем предполагал автор плагина.

​

Размещение и распространение marketplace

​

Размещение на GitHub (рекомендуется)

1. Создание репозитория: установите новый репозиторий для вашего marketplace
2. Добавление файла marketplace: создайте .claude-plugin/marketplace.json с определениями ваших плагинов
3. Совместное использование с командами: пользователи добавляют ваш marketplace с помощью /plugin marketplace add owner/repo

​

Размещение на других сервисах Git

/plugin marketplace add https://gitlab.com/company/plugins.git

​

Частные репозитории

• Установите CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1, чтобы сохранить существующий клон при неудаче фонового pull, вместо удаления и повторного клонирования. Ваши плагины продолжают работать из последнего синхронизированного состояния, и ручные обновления с /plugin marketplace update по-прежнему pull с вашими учетными данными.
• Настройте помощника учетных данных Git, например с помощью gh auth setup-git для GitHub, чтобы fallback повторного клонирования мог аутентифицироваться без подсказок.

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

​

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

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

​

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

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

​

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

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

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

• Только для чтения: каталог 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

​

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

{
  "strictKnownMarketplaces": []
}

{
  "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"
    }
  ]
}

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

​

Как работают ограничения

• Для источников GitHub: repo обязателен, и ref или path также должны совпадать, если указаны в списке разрешений
• Для источников URL: полный URL должен совпадать точно
• Для источников hostPattern: хост marketplace сопоставляется с шаблоном регулярного выражения
• Для источников pathPattern: путь файловой системы marketplace сопоставляется с шаблоном регулярного выражения

​

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

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

​

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

{
  "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"
      }
    }
  ]
}

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

​

Закрепление версий зависимостей плагинов

​

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

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

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

​

Валидация и тестирование

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

Управление marketplace из CLI

​

Plugin marketplace add

claude plugin marketplace add <source> [options]

• <source>: Сокращение GitHub owner/repo, URL Git, удаленный URL к файлу marketplace.json или путь локального каталога. Чтобы закрепить на ветке или теге, добавьте @ref к сокращению GitHub или #ref к URL Git

claude plugin marketplace add acme-corp/claude-plugins

claude plugin marketplace add acme-corp/claude-plugins@v2.0

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

claude plugin marketplace add https://example.com/marketplace.json

claude plugin marketplace add ./my-marketplace

claude plugin marketplace add acme-corp/claude-plugins --scope project

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

​

Plugin marketplace list

claude plugin marketplace list [options]

​

Plugin marketplace remove

claude plugin marketplace remove <name> [options]

• <name>: имя marketplace для удаления, как показано в claude plugin marketplace list. Это name из marketplace.json, а не источник, который вы передали в add

​

Plugin marketplace update

claude plugin marketplace update [name]

• [name]: имя marketplace для обновления, как показано в claude plugin marketplace list. Обновляет все marketplace, если опущено

​

Устранение неполадок

​

Marketplace не загружается

• Проверьте, что URL marketplace доступен
• Убедитесь, что .claude-plugin/marketplace.json существует по указанному пути
• Убедитесь, что синтаксис JSON действителен, используя claude plugin validate или /plugin validate. Чтобы проверить frontmatter skill, agent и command, запустите команду для каждого каталога плагина
• Для частных репозиториев подтвердите, что у вас есть разрешения доступа

​

Ошибки валидации marketplace

• включает плагины, чей source является .
• запускается, когда marketplace.json находится вне каталога .claude-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 их отклоняет.

​

Ошибки установки плагина

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

​

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

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

• По умолчанию фоновые обновления отключают помощники учетных данных Git для pull, поэтому pull не может аутентифицироваться через HTTPS. SSH удаленные хосты с загруженным ключом в ssh-agent все еще аутентифицируются. Неудачный pull запускает повторное клонирование с нуля, которое использует ваши сохраненные учетные данные, но может истечь по времени на больших репозиториях
• Установите CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1, чтобы сохранить существующий клон при сбое фонового pull
• Настройте помощник учетных данных Git, например gh auth setup-git, чтобы резервное повторное клонирование могло аутентифицироваться
• Если повторное клонирование истекает по времени на большом репозитории, увеличьте лимит с помощью CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
• Настройте переписывание URL Git, ограниченное репозиторием marketplace, чтобы фоновый pull аутентифицировался напрямую
• Или обновляйте частные marketplace вручную с помощью /plugin marketplace update <name>, которая использует ваши учетные данные

​

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

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

​

Операции Git истекают по времени

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 минут

​

Плагины с относительными путями не работают в marketplace на основе URL

• Используйте внешние источники: Измените записи плагинов, чтобы использовать источники GitHub, npm или URL Git вместо относительных путей:
  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  
• Используйте marketplace на основе Git: Разместите ваш marketplace в репозитории Git и добавьте его с URL Git. Marketplace на основе Git клонируют весь репозиторий, что делает относительные пути рабочими.

​

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

​

См. также

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