Создание и распространение marketplace плагинов

​

Обзор

1. Создание плагинов: создайте один или несколько плагинов с командами, агентами, 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: Проверка кода на ошибки, безопасность и производительность
disable-model-invocation: true
---

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

Будьте лаконичны и конкретны.

{
  "name": "quality-review-plugin",
  "description": "Добавляет skill /quality-review для быстрой проверки кода",
  "version": "1.0.0"
}

{
  "name": "my-plugins",
  "owner": {
    "name": "Ваше имя"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Добавляет skill /quality-review для быстрой проверки кода"
    }
  ]
}

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

/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 ниже.

​

Strict mode

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

​

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

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

​

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

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

​

Требование 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>/...

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

​

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

​

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

Пример

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

​

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

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

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

​

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

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

​

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

• Marketplace has no plugins defined: добавьте хотя бы один плагин в массив plugins
• No marketplace description provided: добавьте metadata.description, чтобы помочь пользователям понять ваш marketplace
• Plugin name "x" is not kebab-case: имя плагина содержит прописные буквы, пробелы или специальные символы. Переименуйте в строчные буквы, цифры и дефисы только (например, my-plugin). Claude Code принимает другие формы, но синхронизация marketplace Claude.ai их отклоняет.

​

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

• Проверьте, что URL источников плагинов доступны
• Убедитесь, что каталоги плагинов содержат необходимые файлы
• Для источников GitHub убедитесь, что репозитории являются общедоступными или у вас есть доступ
• Протестируйте источники плагинов вручную, клонируя/загружая их

​

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

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

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

​

Операции 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 не работают в автономных средах

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

​

См. также

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