marketplace-builder

Marketplace 构建器

创建 Claude Code marketplace 和插件的完整指南，用于分发命令、Agent、技能、钩子和 MCP 服务。

---

快速参考

Marketplace 与插件的区别

关键概念：两者并不是一回事。

概念	含义	类比
Marketplace	列出插件所在位置的 JSON 目录	图书馆目录
插件	打包的组件集合	书籍
组件	命令、Agent、技能、钩子、MCP 服务	章节

关系：一个 marketplace → 多个插件 → 每个插件包含多个组件

关键要点：Marketplace 不托管插件，只为插件编制索引。插件可以位于任何位置（GitHub、GitLab、私有 git、本地路径）。

---

JSON Schema 快速参考

最简 marketplace.json：

{
  "name": "marketplace-name",
  "owner": {"name": "Owner Name"},
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./path-to-plugin",
      "description": "What this plugin does",
      "version": "1.0.0"
    }
  ]
}

最简 plugin.json（位于 .claude-plugin/ 内）：

{
  "name": "plugin-name",
  "description": "What this plugin does",
  "version": "1.0.0"
}

团队 settings.json（位于 .claude/ 内）：

{
  "extraKnownMarketplaces": {
    "marketplace-name": {
      "source": {"source": "github", "repo": "owner/repo"}
    }
  },
  "enabledPlugins": {
    "plugin-name@marketplace-name": true
  }
}

---

来源类型

类型	语法	最适用场景
GitHub	{"source": "github", "repo": "owner/repo"}	公共插件
Git URL	{"source": "git", "url": "https://..."}	私有/GitLab
目录	{"source": "directory", "path": "./path"}	Monorepo
相对路径	"./path"	目录的简写

---

命令参考

# Add a marketplace
/plugin marketplace add owner/repo
/plugin marketplace add https://gitlab.com/org/repo.git
/plugin marketplace add ./local-marketplace

# List marketplaces
/plugin marketplace list

# Update marketplace catalog
/plugin marketplace update marketplace-name

# Browse and install plugins
/plugin                                    # Interactive browser
/plugin install plugin-name@marketplace    # Direct install

# Manage plugins
/plugin enable plugin@marketplace
/plugin disable plugin@marketplace
/plugin uninstall plugin@marketplace

# Validate structure
claude plugin validate .

---

6 阶段工作流

阶段 1：收集需求

使用 AskUserQuestion 了解用户需求：

1. 你要分发什么？

   • 命令（斜杠命令）
   • Agent（子 Agent）
   • 技能（由模型调用的能力）
   • 钩子（事件处理程序）
   • MCP 服务（外部工具）
   • 以上内容的组合

2. 有多少个插件？

   • 单个插件
   • 多个相关插件
   • 大型插件集合

3. 受众是谁？

   • 个人使用（仅自己）
   • 团队（通过 git 与同事共享）
   • 组织（公司范围）
   • 公共社区

4. 使用什么托管方式？

   • GitHub（公共或私有）
   • GitLab 或其他 git 服务
   • 自托管 git
   • 仅用于本地开发

继续之前，请记录答案。

---

阶段 2：架构决策

根据需求，推荐以下模式之一：

模式 A：基础 Marketplace（单个插件）

适用场景：单个插件、简单分发

my-marketplace/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── commands/
└── agents/

模式 B：Monorepo（多个插件、一个仓库）

适用场景：相关插件、统一版本管理、团队所有权

company-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   ├── formatter/
│   │   ├── .claude-plugin/plugin.json
│   │   └── commands/
│   ├── linter/
│   │   ├── .claude-plugin/plugin.json
│   │   └── commands/
│   └── tester/
│       ├── .claude-plugin/plugin.json
│       └── agents/

模式 C：多仓库（插件位于不同仓库）

适用场景：独立插件、不同所有者、社区集合

# Marketplace repo
my-marketplace/
└── .claude-plugin/
    └── marketplace.json  # Points to other repos

# Plugin repos (separate)
tool-a/
├── .claude-plugin/plugin.json
└── commands/

tool-b/
├── .claude-plugin/plugin.json
└── agents/

模式 D：企业版（私有与公共混合）

适用场景：内部和外部工具混合、严格访问控制

{
  "plugins": [
    {"name": "internal-tool", "source": {"source": "git", "url": "https://git.corp/..."}},
    {"name": "community-tool", "source": {"source": "github", "repo": "public/tool"}}
  ]
}

决策树：

• 单个插件？→ 模式 A
• 多个插件，属于同一团队？→ 模式 B
• 插件来自不同来源？→ 模式 C
• 企业场景，兼有私有与公共插件？→ 模式 D

---

阶段 3：创建插件

为每个插件创建以下结构：

plugin-name/
├── .claude-plugin/
│   └── plugin.json         # Required: plugin manifest
├── commands/               # Optional: slash commands
│   └── my-command.md
├── agents/                 # Optional: subagents
│   └── my-agent.md
├── skills/                 # Optional: skills
│   └── my-skill/
│       └── SKILL.md
├── hooks/                  # Optional: event handlers
│   └── hooks.json
└── .mcp.json              # Optional: MCP servers

编写 plugin.json：

{
  "name": "plugin-name",
  "description": "Clear description of what this plugin provides",
  "version": "1.0.0",
  "author": {
    "name": "Author Name",
    "email": "[email protected]"
  },
  "homepage": "https://docs.example.com",
  "repository": "https://github.com/owner/repo",
  "license": "MIT"
}

命名约定：

• 插件名称：kebab-case（例如，code-formatter）
• 版本：语义化版本 MAJOR.MINOR.PATCH
• 命令：verb-noun.md（例如，format-code.md）
• Agent：role-name.md（例如，code-reviewer.md）

---

阶段 4：创建 Marketplace

创建 .claude-plugin/marketplace.json：

适用于 Monorepo（插件位于同一仓库）：

{
  "name": "company-tools",
  "owner": {
    "name": "Company Name",
    "email": "[email protected]"
  },
  "metadata": {
    "description": "Company development tools",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "formatter",
      "source": "./plugins/formatter",
      "description": "Code formatting tools",
      "version": "1.0.0"
    },
    {
      "name": "linter",
      "source": "./plugins/linter",
      "description": "Code linting tools",
      "version": "1.0.0"
    }
  ]
}

适用于多仓库（插件位于不同仓库）：

{
  "name": "community-collection",
  "owner": {
    "name": "Community",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "tool-a",
      "source": {
        "source": "github",
        "repo": "community/tool-a"
      },
      "description": "Tool A description",
      "version": "2.1.0"
    },
    {
      "name": "tool-b",
      "source": {
        "source": "github",
        "repo": "community/tool-b"
      },
      "description": "Tool B description",
      "version": "1.3.0"
    }
  ]
}

---

阶段 5：设置分发

个人使用

无需额外设置。在本地添加 marketplace：

/plugin marketplace add ./path-to-marketplace

团队分发

添加到项目的 .claude/settings.json：

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "company/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "formatter@team-tools": true,
    "linter@team-tools": true
  }
}

工作方式：

1. 团队成员克隆项目
2. Claude Code 读取 .claude/settings.json
3. 提示信任已配置的 marketplace
4. 提示安装已启用的插件
5. 新团队成员会自动获得正确的设置

面向公开分发

1. 将市场仓库推送到 GitHub

2. 在 README 中记录安装方法：

   ## Installation
   
   Add the marketplace:
   ```bash
   /plugin marketplace add owner/repo
   

   安装插件：

   /plugin install formatter@owner-tools
   

For Enterprise

1. Set up private git access (SSH keys or tokens)
2. Create internal marketplace with git URL sources
3. Configure .claude/settings.json in project templates
4. Document for IT/security review

---

Phase 6: Validation and Testing

Step 1: Validate JSON Syntax

# Validate marketplace structure
claude plugin validate .

# Manual JSON validation
python3 -c "import json; json.load(open('.claude-plugin/marketplace.json'))"
python3 -c "import json; json.load(open('.claude-plugin/plugin.json'))"

步骤 2：测试添加市场

# Add marketplace locally
/plugin marketplace add ./path-to-marketplace

# Verify it appears
/plugin marketplace list

步骤 3：测试安装插件

# Browse available plugins
/plugin

# Install a plugin
/plugin install plugin-name@marketplace-name

# Verify components work
/help  # Check commands appear

步骤 4：测试团队工作流（如适用）

1. 将包含 settings.json 的项目克隆到新位置
2. 在出现提示时信任文件夹
3. 验证市场和插件是否安装正确

步骤 5：验证所有组件

• 命令：运行 /command-name 进行测试
• Agent：检查 /agents 或尝试通过 Task 调用
• 技能：使用触发词激活
• 钩子：触发事件进行测试
• MCP 服务：检查 MCP 工具是否可用

---

架构模式

单体仓库模式

结构：

company-plugins/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   ├── plugin-a/
│   ├── plugin-b/
│   └── plugin-c/
└── README.md

优点：

• 只需管理一个仓库
• 统一版本管理
• 便于跨插件更改
• CI/CD 更简单

缺点：

• 所有插件共享访问控制
• 仓库体积更大
• 更新只能全部进行或全部不进行

适用于：团队工具、相关插件、统一所有权

---

多仓库模式

结构：

# Marketplace repo
tools-marketplace/
└── .claude-plugin/marketplace.json

# Separate plugin repos
plugin-a/   # github.com/org/plugin-a
plugin-b/   # github.com/org/plugin-b
plugin-c/   # github.com/org/plugin-c

优点：

• 独立版本管理
• 单独的访问控制
• 分散式所有权
• 仓库体积更小

缺点：

• 需要管理更多仓库
• 需要协调版本
• CI/CD 更复杂

适用于：社区集合、所有权混合、独立插件

---

混合模式

结构：

{
  "plugins": [
    {"name": "core", "source": "./plugins/core"},
    {"name": "community", "source": {"source": "github", "repo": "community/tool"}},
    {"name": "internal", "source": {"source": "git", "url": "https://git.corp/..."}}
  ]
}

优点：

• 可灵活混用不同来源
• 可包含社区插件
• 支持私有和公开内容

缺点：

• 维护起来更复杂
• 信任级别不一
• 更新周期各异

适用于：企业、成熟生态系统、渐进式迁移

---

常见陷阱

1. 混淆市场和插件

错误：认为 marketplace.json 就是插件 正确：marketplace.json 指向插件

marketplace.json 是目录。实际的插件代码位于单独的目录或仓库中。

2. 来源类型错误

错误：对私有仓库使用 GitHub 简写

{"source": "github", "repo": "private-org/private-repo"}  // May fail

正确：对私有仓库使用 git URL

{"source": "git", "url": "[email protected]:private-org/private-repo.git"}

3. 缺少必填字段

marketplace.json 必填项：

• name
• owner.name
• plugins 数组

plugin.json 必填项：

• name
• description
• version

4. 路径错误

错误：使用相对于错误目录的路径

{"source": "../plugins/tool"}  // Relative to what?

正确：路径相对于 marketplace.json 所在位置

{"source": "./plugins/tool"}  // Relative to .claude-plugin/

5. 版本不匹配

保持以下版本一致：

• plugin.json 中的版本
• marketplace.json 插件条目中的版本

更新插件时，请同时更新这两个文件。

6. 忘记验证

发布前务必运行：

claude plugin validate .

7. 误解信任模型

用户必须明确信任市场。你无法强制为团队成员安装插件。settings.json 只会预先配置，用户仍需批准。

---

何时使用此技能

以下情况使用 marketplace-builder：

• 创建新市场
• 发布插件以供分发
• 设置团队范围的插件配置
• 将本地插件转换为可分发的包
• 排查市场或插件问题

以下情况不要使用：

• 创建单个命令（使用 slash-command-builder）
• 创建单个 Agent（使用 agent-builder）
• 创建单个技能（使用 skill-builder）
• 仅使用现有插件（直接使用 /plugin 命令）

---

文件参考

模板

• templates/basic-marketplace.md - 单个插件的简单设置
• templates/plugin-structure.md - 完整的插件创建指南
• templates/multi-plugin.md - 单体仓库模式
• templates/multi-repo.md - 分布式插件模式
• templates/enterprise-marketplace.md - 包含团队配置的企业方案

示例

• examples/development-tools.md - 6 个开发工具插件
• examples/team-workflows.md - 6 个团队工作流插件
• examples/specialized-domains.md - 6 个特定领域插件

参考资料

• reference/syntax-guide.md - 完整的 JSON 架构
• reference/best-practices.md - 设计原则
• reference/troubleshooting.md - 常见问题和调试