marketplace-structure

用途

Marketplace Structure 技能用于创建和维护插件市场（plugin marketplace）。插件市场是一个可用插件的目录，支持集中发现、版本管理和分发。该技能适用于团队或社区分发插件的场景。

主要能力

集中发现：在一个位置浏览来自多个来源的插件。
版本管理：自动跟踪和更新插件版本。
团队分发：在组织内共享所需插件。
灵活来源：支持相对路径、GitHub 仓库和 Git URL。

使用方式

目录结构

将 marketplace.json 放在仓库根目录的 .claude-plugin/ 目录下：

marketplace-repo/
├── .claude-plugin/
│   └── marketplace.json      # 必需：市场清单
├── plugins/                  # 可选：本地插件目录
│   ├── plugin-one/
│   │   └── .claude-plugin/
│   │       └── plugin.json
│   └── plugin-two/
│       └── .claude-plugin/
│           └── plugin.json
└── README.md                 # 推荐：市场文档

市场 Schema

marketplace.json 清单定义市场及其可用插件。

必需字段：

字段	类型	描述
name	string	市场标识符（kebab-case，无空格）
owner	object	市场维护者信息
plugins	array	可用插件条目列表

Owner 对象示例：

{
  "owner": {
    "name": "Team Name",
    "email": "team@example.com",
    "url": "https://github.com/team"
  }
}

可选元数据：

{
  "metadata": {
    "description": "Brief marketplace description",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  }
}

pluginRoot 字段设置相对插件来源的基础路径。

插件条目格式

plugins 数组中的每个插件需要：

字段	类型	描述
name	string	插件标识符（kebab-case，市场内唯一）
source	string 或 object	从何处获取插件

可选插件字段：

标准元数据字段：description、version、author、homepage、repository、license、keywords、category、tags。

组件配置字段：commands、agents、hooks、mcpServers。

插件来源

相对路径（同一仓库内）：

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

GitHub 仓库：

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

带固定的 GitHub 仓库（用于可重现构建）：

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v1.2.0",
    "sha": "abc123def456..."
  }
}

ref 为分支、标签或提交引用；sha 为用于完整性验证的精确提交 SHA。

Git URL（GitLab、Bitbucket 或自托管 git）：

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main"
  }
}

主机模式（按 URL 模式匹配插件）：

{
  "name": "internal-plugin",
  "source": {
    "hostPattern": "https://git.company.com/*"
  }
}

严格与非严格模式

strict 字段控制插件是否必须有自己的 plugin.json：

模式	行为
strict: true（默认）	插件必须包含 plugin.json；市场条目补充它
strict: false	plugin.json 可选；市场条目作为完整清单

使用 strict: false 的场景：

在不修改外部插件源代码的情况下策展外部插件。
在市场条目中提供所有元数据。
插件目录仅包含 commands/agents/skills 而没有清单。

{
  "name": "external-plugin",
  "source": {
    "source": "github",
    "repo": "external/plugin"
  },
  "description": "Complete metadata here",
  "version": "2.0.0",
  "strict": false
}

企业功能

受管市场限制：组织可以使用受管设置限制用户可以从哪些市场安装：

{
  "strictKnownMarketplaces": true
}

启用后，用户只能从官方批准的市场安装插件。可以通过受管设置中的 extraKnownMarketplaces 添加额外市场。

私有仓库认证：对于托管在私有仓库中的市场，设置相应的环境变量：

GitHub：GITHUB_TOKEN
GitLab：GITLAB_TOKEN
Bitbucket：BITBUCKET_TOKEN

保留市场名称

某些市场名称由 Anthropic 保留供官方使用。为自定义市场选择独特的名称以避免冲突。

基于 URL 的市场限制

通过 URL（而非 git 来源）添加的市场对插件来源中的相对路径支持有限。相对路径可能无法正确解析——优先使用绝对来源引用或基于 git 的市场。

适用场景

团队内部插件分发。
社区插件集合。
需要集中管理多个插件版本和来源的场景。

限制

基于 URL 的市场对相对路径支持有限。
某些市场名称被保留。
私有仓库需要配置认证令牌。

最佳实践

组织：

每个市场一个主题——分组相关插件（例如 "frontend-tools"、"security-plugins"）。
清晰命名——为市场和插件使用描述性的 kebab-case 名称。
为所有条目设置版本——为每个插件条目包含 version。
记录每个插件——提供 description 以便发现。

版本管理：

为市场 metadata.version 使用语义化版本（X.Y.Z）。
添加、删除或更新插件时更新市场版本。
考虑使用 CHANGELOG.md 跟踪变更。

分发：

GitHub 托管——通过 /plugin marketplace add owner/repo 最简单分发。
团队设置——在 .claude/settings.json 中配置 extraKnownMarketplaces。
本地测试——开发期间使用 /plugin marketplace add ./path 添加。

验证

发布前验证市场结构：

# 检查 JSON 语法
jq . .claude-plugin/marketplace.json

# 验证必需字段
jq 'has("name") and has("owner") and has("plugins")' .claude-plugin/marketplace.json

使用支持市场验证的 plugin-validator agent 进行全面验证。

完整示例

{
  "name": "team-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@company.com",
    "url": "https://github.com/company"
  },
  "metadata": {
    "description": "Internal development tools for the engineering team",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0"
    },
    {
      "name": "security-scanner",
      "source": {
        "source": "github",
        "repo": "company/security-plugin"
      },
      "description": "Security vulnerability detection",
      "version": "1.5.0",
      "category": "security"
    }
  ]
}

附加资源

references/schema-reference.md - marketplace.json 的完整字段参考
references/distribution-patterns.md - 托管和团队分发策略
examples/minimal-marketplace.md - 单插件市场模板
examples/team-marketplace.md - 内部公司市场模板
examples/community-marketplace.md - 公共多插件市场模板

工作示例

本仓库（plugin-dev）本身就是一个市场。检查仓库根目录的 .claude-plugin/marketplace.json 以获取市场结构和插件组织的真实示例。

技能介绍

用途