plugin-marketplace

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Plugin Marketplace

Claude Code插件市场

Guide for creating, validating, and managing plugin marketplaces for Claude Code. Includes schema validation, best practices, and automated tools.

本指南介绍如何为Claude Code创建、验证和管理插件市场，包括Schema验证、最佳实践和自动化工具。

When to Use This Skill

何时使用本技能

Activate this skill when:

Creating or editing
```
.claude-plugin/marketplace.json
```
files
Validating marketplace schema compliance
Setting up plugin repositories with marketplaces
Troubleshooting marketplace configuration issues
Converting plugin structures to marketplace format
Creating plugin entries with advanced features

在以下场景激活本技能：

创建或编辑
```
.claude-plugin/marketplace.json
```
文件
验证市场Schema合规性
搭建带市场功能的插件仓库
排查市场配置问题
将插件结构转换为市场格式
创建包含高级功能的插件条目

Marketplace Schema Overview

市场Schema概述

Required Structure

必需结构

All marketplaces must be located at

.claude-plugin/marketplace.json

in the repository root.

Required Fields:

```
name
```
: Marketplace identifier (kebab-case, lowercase alphanumeric and hyphens only)
```
owner
```
: Object with maintainer details (
```
name
```
required,
```
email
```
optional)
```
plugins
```
: Array of plugin definitions (can be empty)

Optional Metadata:

```
metadata.description
```
: Summary of marketplace purpose
```
metadata.version
```
: Marketplace version tracking (semantic versioning recommended)
```
metadata.pluginRoot
```
: Base directory for relative plugin source paths

所有市场文件必须位于仓库根目录的

.claude-plugin/marketplace.json

路径下。

必填字段：

```
name
```
：市场标识符（仅允许短横线分隔的小写字母数字格式，即kebab-case）
```
owner
```
：维护者信息对象（
```
name
```
为必填项，
```
email
```
为可选）
```
plugins
```
：插件定义数组（可为空）

可选元数据：

```
metadata.description
```
：市场用途概述
```
metadata.version
```
：市场版本跟踪（推荐使用语义化版本）
```
metadata.pluginRoot
```
：插件源相对路径的基础目录

Plugin Entry Schema

插件条目Schema

IMPORTANT: Schema Relationship

Plugin entries use the plugin manifest schema with all fields made optional, plus marketplace-specific fields (

source

strict

category

tags

). This means any field valid in a plugin.json file can also be used in a marketplace entry.

When
```
strict: false
```
, the marketplace entry serves as the complete plugin manifest if no plugin.json exists
When
```
strict: true
```
(default), marketplace fields supplement the plugin's own manifest file

Each plugin entry in the

plugins

array requires:

Mandatory:

```
name
```
: Plugin identifier (kebab-case)
```
source
```
: Location specification (string path or object)

Standard Metadata:

```
description
```
: Brief explanation of plugin functionality
```
version
```
: Semantic version number
```
author
```
: Creator information (object with
```
name
```
, optional
```
email
```
)
```
homepage
```
: Documentation or project URL
```
repository
```
: Source control URL
```
license
```
: SPDX license identifier (e.g., MIT, Apache-2.0)
```
keywords
```
: Array of discovery and categorization tags
```
category
```
: Organizational grouping
```
tags
```
: Additional searchability terms

Component Configuration:

```
commands
```
: Custom paths to command files or directories
```
agents
```
: Custom paths to agent files
```
hooks
```
: Custom hooks configuration or path to hooks file
```
mcpServers
```
: MCP server configurations or path to MCP config
```
skills
```
: Array of skill directory paths

Strict Mode Control:

```
strict
```
: Boolean (default:
```
true
```
)
- ```
true
```
  : Plugin must include plugin.json; marketplace fields supplement it
- ```
false
```
  : Marketplace entry serves as complete manifest (no plugin.json needed)

Dependencies:

```
dependencies
```
: Array of plugin names this plugin depends on (format:
```
"namespace:plugin-name"
```
)

重要：Schema关联

插件条目使用插件清单Schema，所有字段均为可选，同时新增市场专属字段（

source

、

strict

、

category

、

tags

）。这意味着plugin.json中有效的字段，在市场条目中同样适用。

当
```
strict: false
```
时，如果不存在plugin.json，市场条目将作为完整的插件清单
当
```
strict: true
```
（默认值）时，市场字段仅作为插件自身manifest文件的补充

plugins

数组中的每个插件条目需要包含：

必填项：

```
name
```
：插件标识符（kebab-case格式）
```
source
```
：位置说明（字符串路径或对象）

标准元数据：

```
description
```
：插件功能简要说明
```
version
```
：语义化版本号
```
author
```
：创建者信息（包含
```
name
```
的对象，
```
email
```
可选）
```
homepage
```
：文档或项目URL
```
repository
```
：源码仓库URL
```
license
```
：SPDX许可证标识符（如MIT、Apache-2.0）
```
keywords
```
：用于发现和分类的标签数组
```
category
```
：组织分组
```
tags
```
：额外的可搜索术语

组件配置：

```
commands
```
：命令文件或目录的自定义路径
```
agents
```
：Agent文件的自定义路径
```
hooks
```
：钩子配置或钩子文件路径
```
mcpServers
```
：MCP服务器配置或MCP配置文件路径
```
skills
```
：技能目录路径数组

严格模式控制：

```
strict
```
：布尔值（默认：
```
true
```
）
- ```
true
```
  ：插件必须包含plugin.json；市场字段仅作为补充
- ```
false
```
  ：市场条目作为完整清单（无需plugin.json）

依赖项：

```
dependencies
```
：当前插件依赖的其他插件名称数组（格式：
```
"namespace:plugin-name"
```
）

Plugin Source Formats

插件源格式

Relative Path

相对路径

json

"source": "./plugins/my-plugin"

json

"source": "./plugins/my-plugin"

Relative Path with pluginRoot

结合pluginRoot的相对路径

json

// In marketplace metadata
"metadata": {
  "pluginRoot": "./plugins"
}

// In plugin entry
"source": "my-plugin"  // Resolves to ./plugins/my-plugin

json

// 在市场元数据中
"metadata": {
  "pluginRoot": "./plugins"
}

// 在插件条目中
"source": "my-plugin"  // 解析为 ./plugins/my-plugin

GitHub Repository

GitHub仓库

json

"source": {
  "source": "github",
  "repo": "owner/plugin-repo",
  "path": "optional/subdirectory",
  "branch": "main"
}

json

"source": {
  "source": "github",
  "repo": "owner/plugin-repo",
  "path": "optional/subdirectory",
  "branch": "main"
}

Git URL

json

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

json

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

Environment Variables

环境变量

Use

${CLAUDE_PLUGIN_ROOT}

in paths to reference the plugin's installation directory:

json

{
  "skills": [
    "${CLAUDE_PLUGIN_ROOT}/skills/my-skill"
  ],
  "commands": [
    "${CLAUDE_PLUGIN_ROOT}/commands"
  ]
}

This ensures paths work correctly regardless of installation location.

在路径中使用

${CLAUDE_PLUGIN_ROOT}

来引用插件的安装目录：

json

{
  "skills": [
    "${CLAUDE_PLUGIN_ROOT}/skills/my-skill"
  ],
  "commands": [
    "${CLAUDE_PLUGIN_ROOT}/commands"
  ]
}

这样可以确保无论安装位置如何，路径都能正常工作。

Advanced Plugin Entry Features

高级插件条目功能

Inline Plugin Definitions

内联插件定义

Use

strict: false

to define complete plugin manifests inline without requiring plugin.json:

json

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin",
  "strict": false,
  "description": "Complete plugin definition inline",
  "version": "1.0.0",
  "author": {
    "name": "Developer Name"
  },
  "skills": [
    "${CLAUDE_PLUGIN_ROOT}/skills/skill-one",
    "${CLAUDE_PLUGIN_ROOT}/skills/skill-two"
  ]
}

使用

strict: false

可以在市场条目中直接定义完整的插件清单，无需plugin.json：

json

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin",
  "strict": false,
  "description": "内联式完整插件定义",
  "version": "1.0.0",
  "author": {
    "name": "开发者名称"
  },
  "skills": [
    "${CLAUDE_PLUGIN_ROOT}/skills/skill-one",
    "${CLAUDE_PLUGIN_ROOT}/skills/skill-two"
  ]
}

Component Path Override

组件路径覆盖

Customize component locations:

json

{
  "name": "custom-paths",
  "source": "./plugins/custom",
  "strict": false,
  "commands": ["${CLAUDE_PLUGIN_ROOT}/custom-commands"],
  "agents": ["${CLAUDE_PLUGIN_ROOT}/custom-agents"],
  "hooks": {
    "onInstall": "${CLAUDE_PLUGIN_ROOT}/hooks/install.sh"
  },
  "mcpServers": "${CLAUDE_PLUGIN_ROOT}/mcp-config.json"
}

自定义组件位置：

json

{
  "name": "custom-paths",
  "source": "./plugins/custom",
  "strict": false,
  "commands": ["${CLAUDE_PLUGIN_ROOT}/custom-commands"],
  "agents": ["${CLAUDE_PLUGIN_ROOT}/custom-agents"],
  "hooks": {
    "onInstall": "${CLAUDE_PLUGIN_ROOT}/hooks/install.sh"
  },
  "mcpServers": "${CLAUDE_PLUGIN_ROOT}/mcp-config.json"
}

Metadata Supplementation

元数据补充

With

strict: true

, marketplace entries can add metadata not in plugin.json:

json

{
  "name": "existing-plugin",
  "source": "./plugins/existing",
  "strict": true,
  "category": "development",
  "keywords": ["added", "from", "marketplace"],
  "homepage": "https://docs.example.com"
}

当

strict: true

时，市场条目可以添加plugin.json中没有的元数据：

json

{
  "name": "existing-plugin",
  "source": "./plugins/existing",
  "strict": true,
  "category": "development",
  "keywords": ["added", "from", "marketplace"],
  "homepage": "https://docs.example.com"
}

Validation Workflow

验证工作流

1. Schema Validation

1. Schema验证

Use the provided Nushell script to validate marketplace.json:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace.nu .claude-plugin/marketplace.json

This validates:

JSON syntax
Required fields presence
Kebab-case naming
Field type correctness
Source path accessibility (for relative paths)

使用提供的Nushell脚本验证marketplace.json：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace.nu .claude-plugin/marketplace.json

该脚本会验证：

JSON语法
必填字段是否存在
命名是否符合kebab-case格式
字段类型是否正确
源路径是否可访问（针对相对路径）

2. Plugin Entry Validation

2. 插件条目验证

Validate individual plugin entries:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin-entry.nu .claude-plugin/marketplace.json "plugin-name"

Checks:

Required fields (name, source)
Strict mode consistency
Dependency references
Path validity
Component configuration

验证单个插件条目：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-plugin-entry.nu .claude-plugin/marketplace.json "plugin-name"

检查内容：

必填字段（name、source）
严格模式一致性
依赖引用
路径有效性
组件配置

3. Dependency Graph Validation

3. 依赖图验证

Check for circular dependencies and missing dependencies:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-dependencies.nu .claude-plugin/marketplace.json

检查是否存在循环依赖和缺失的依赖：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-dependencies.nu .claude-plugin/marketplace.json

Best Practices

最佳实践

Naming Conventions

命名规范

Marketplace name: Use your GitHub username or organization (e.g.,
```
vinnie357
```
)
Plugin names: Use descriptive kebab-case (e.g.,
```
elixir-phoenix
```
,
```
rust-tools
```
,
```
core-skills
```
)
Categories: Standardize on common categories:
```
development
```
,
```
language
```
,
```
tools
```
,
```
frontend
```
,
```
backend
```
,
```
meta
```

市场名称：使用你的GitHub用户名或组织名（例如：
```
vinnie357
```
）
插件名称：使用描述性的kebab-case格式（例如：
```
elixir-phoenix
```
、
```
rust-tools
```
、
```
core-skills
```
）
分类：使用标准分类：
```
development
```
、
```
language
```
、
```
tools
```
、
```
frontend
```
、
```
backend
```
、
```
meta
```

Versioning Strategy

版本策略

Use semantic versioning for both marketplace and plugins
Bump marketplace version when adding/removing plugins
Bump plugin versions when updating skills or configuration
Document breaking changes in plugin descriptions

市场和插件均使用语义化版本
添加/移除插件时升级市场版本
更新技能或配置时升级插件版本
在插件描述中记录破坏性变更

Dependency Management

依赖管理

Always declare
```
dependencies
```
for plugins that require other plugins
Keep dependency chains shallow (avoid deep nesting)
Consider creating a meta-plugin (like
```
all-skills
```
) that bundles related plugins
Use namespace prefixes for dependencies (e.g.,
```
all-skills:core
```
)

对于依赖其他插件的插件，务必声明
```
dependencies
```
保持依赖链简洁（避免深层嵌套）
考虑创建元插件（如
```
all-skills
```
）来捆绑相关插件
依赖使用命名空间前缀（例如：
```
all-skills:core
```
）

Strict Mode Decision

严格模式选择

Use
strict: false
when:

Creating simple, self-contained plugins
All configuration is in marketplace.json
You want centralized management
Plugin is unlikely to be distributed independently

Use
strict: true
when:

Plugin has complex configuration
Plugin may be distributed separately
Plugin has its own versioning lifecycle
You want to supplement existing plugin.json with marketplace metadata

使用
strict: false
的场景：

创建简单、独立的插件
所有配置都在marketplace.json中
希望集中管理
插件不太可能独立分发

使用
strict: true
的场景：

插件配置复杂
插件可能单独分发
插件有自己的版本生命周期
希望用市场元数据补充现有的plugin.json

Source Path Organization

源路径组织

json

{
  "metadata": {
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "core",
      "source": "core"  // Resolves to ./plugins/core
    },
    {
      "name": "external",
      "source": {
        "source": "github",
        "repo": "org/repo"
      }
    }
  ]
}

json

{
  "metadata": {
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "core",
      "source": "core"  // 解析为 ./plugins/core
    },
    {
      "name": "external",
      "source": {
        "source": "github",
        "repo": "org/repo"
      }
    }
  ]
}

Common Validation Errors

常见验证错误

Error: Invalid kebab-case name

错误：无效的kebab-case名称

json

// ❌ Invalid
"name": "myPlugin"
"name": "my_plugin"
"name": "My-Plugin"

// ✅ Valid
"name": "my-plugin"
"name": "core-skills"

json

// ❌ 无效
"name": "myPlugin"
"name": "my_plugin"
"name": "My-Plugin"

// ✅ 有效
"name": "my-plugin"
"name": "core-skills"

Error: Missing required owner field

错误：缺少必填的owner字段

json

// ❌ Invalid
{
  "name": "marketplace"
}

// ✅ Valid
{
  "name": "marketplace",
  "owner": {
    "name": "Developer Name"
  }
}

json

// ❌ 无效
{
  "name": "marketplace"
}

// ✅ 有效
{
  "name": "marketplace",
  "owner": {
    "name": "开发者名称"
  }
}

Error: Invalid source path

错误：无效的源路径

json

// ❌ Invalid (path doesn't exist)
"source": "./plugins/nonexistent"

// ✅ Valid (path exists)
"source": "./plugins/core"

json

// ❌ 无效（路径不存在）
"source": "./plugins/nonexistent"

// ✅ 有效（路径存在）
"source": "./plugins/core"

Error: Circular dependencies

错误：循环依赖

json

// ❌ Invalid
{
  "plugins": [
    {
      "name": "plugin-a",
      "dependencies": ["namespace:plugin-b"]
    },
    {
      "name": "plugin-b",
      "dependencies": ["namespace:plugin-a"]
    }
  ]
}

json

// ❌ 无效
{
  "plugins": [
    {
      "name": "plugin-a",
      "dependencies": ["namespace:plugin-b"]
    },
    {
      "name": "plugin-b",
      "dependencies": ["namespace:plugin-a"]
    }
  ]
}

Creating a New Marketplace

创建新市场

Step 1: Initialize Structure

步骤1：初始化结构

bash

mkdir -p .claude-plugin

bash

mkdir -p .claude-plugin

Step 2: Create Marketplace File

步骤2：创建市场文件

Use the validation script to generate a template:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/init-marketplace.nu

This creates

.claude-plugin/marketplace.json

with required fields.

使用验证脚本生成模板：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/init-marketplace.nu

该命令会创建包含必填字段的

.claude-plugin/marketplace.json

文件。

Step 3: Add Plugin Entries

步骤3：添加插件条目

For each plugin, decide on strict mode and add entry:

json

{
  "name": "marketplace-name",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "metadata": {
    "description": "Your marketplace description",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "plugin-name",
      "strict": false,
      "description": "Plugin description",
      "version": "1.0.0",
      "author": {
        "name": "Your Name"
      },
      "license": "MIT",
      "category": "development",
      "skills": [
        "${CLAUDE_PLUGIN_ROOT}/skills/skill-one"
      ]
    }
  ]
}

为每个插件选择严格模式并添加条目：

json

{
  "name": "marketplace-name",
  "owner": {
    "name": "你的名称",
    "email": "you@example.com"
  },
  "metadata": {
    "description": "你的市场描述",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "plugin-name",
      "strict": false,
      "description": "插件描述",
      "version": "1.0.0",
      "author": {
        "name": "你的名称"
      },
      "license": "MIT",
      "category": "development",
      "skills": [
        "${CLAUDE_PLUGIN_ROOT}/skills/skill-one"
      ]
    }
  ]
}

Step 4: Validate

步骤4：验证

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace.nu .claude-plugin/marketplace.json

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace.nu .claude-plugin/marketplace.json

Step 5: Test Installation

步骤5：测试安装

bash

claude-code install ./

bash

claude-code install ./

Migrating Existing Plugins

迁移现有插件

From Individual Plugins to Marketplace

从独立插件到市场

Identify plugins: List all plugin.json files
Decide on strict mode: Choose per plugin based on complexity
Create marketplace.json: Add all plugins with appropriate configuration
Test each plugin: Verify installation works correctly
Document dependencies: Add dependency arrays where needed

识别插件：列出所有plugin.json文件
选择严格模式：根据插件复杂度为每个插件选择合适的模式
创建marketplace.json：添加所有插件并配置相应参数
测试每个插件：验证安装是否正常
记录依赖：在需要的地方添加依赖数组

Migration Script

迁移脚本

Use the provided script to analyze existing structure:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/analyze-plugins.nu .

This scans for plugin.json files and suggests marketplace.json structure.

使用提供的脚本分析现有结构：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/analyze-plugins.nu .

该脚本会扫描plugin.json文件并建议marketplace.json的结构。

Troubleshooting

故障排查

Plugin Not Found After Installation

安装后找不到插件

Verify
```
source
```
path is correct
Check
```
pluginRoot
```
in metadata if using relative paths
Ensure plugin directory exists at specified location

验证
```
source
```
路径是否正确
如果使用相对路径，检查元数据中的
```
pluginRoot
```
确保插件目录存在于指定位置

Skills Not Loading

技能无法加载

Verify skill paths use
```
${CLAUDE_PLUGIN_ROOT}
```
if needed
Check that skill directories contain SKILL.md files
Validate skill paths in plugin entry or plugin.json

验证技能路径是否根据需要使用了
```
${CLAUDE_PLUGIN_ROOT}
```
检查技能目录是否包含SKILL.md文件
验证插件条目或plugin.json中的技能路径

Dependency Resolution Fails

依赖解析失败

Ensure dependency names match exactly (including namespace)
Check that all dependencies are listed in marketplace
Verify no circular dependencies exist

确保依赖名称完全匹配（包括命名空间）
检查所有依赖是否都在市场中列出
验证是否存在循环依赖

Validation Errors

验证错误

Run validation script with verbose mode:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace.nu .claude-plugin/marketplace.json --verbose

使用详细模式运行验证脚本：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/validate-marketplace.nu .claude-plugin/marketplace.json --verbose

References

参考资料

For detailed schema specifications and examples, see:

```
references/schema-specification.md
```
: Complete JSON schema
```
references/examples.md
```
: Real-world marketplace examples
```
references/migration-guide.md
```
: Step-by-step migration instructions

如需详细的Schema规范和示例，请查看：

```
references/schema-specification.md
```
：完整的JSON Schema
```
references/examples.md
```
：真实的市场示例
```
references/migration-guide.md
```
：分步迁移指南

Script Usage

脚本使用

All validation and utility scripts are located in

scripts/

```
validate-marketplace.nu
```
: Full marketplace validation
```
validate-plugin-entry.nu
```
: Individual plugin entry validation
```
validate-dependencies.nu
```
: Dependency graph validation
```
init-marketplace.nu
```
: Generate marketplace template
```
analyze-plugins.nu
```
: Analyze existing plugin structure
```
format-marketplace.nu
```
: Format and sort marketplace.json

Execute scripts with:

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/[script-name].nu [args]

所有验证和实用脚本都位于

scripts/

目录下：

```
validate-marketplace.nu
```
：完整的市场验证
```
validate-plugin-entry.nu
```
：单个插件条目验证
```
validate-dependencies.nu
```
：依赖图验证
```
init-marketplace.nu
```
：生成市场模板
```
analyze-plugins.nu
```
：分析现有插件结构
```
format-marketplace.nu
```
：格式化并排序marketplace.json

执行脚本的命令格式：

bash

nu ${CLAUDE_PLUGIN_ROOT}/scripts/[脚本名称].nu [参数]