gh-hyperskill-claude-code-marketplace-plugins-plugin-development/skills/plugin-authoring/schemas/marketplace-schema.md

Marketplace Schema

The marketplace.json file defines a collection of plugins that users can install.

Location

.claude-plugin/marketplace.json (at marketplace root)

Structure

{
  "name": "marketplace-name",
  "owner": {
    "name": "Your Organization",
    "email": "team@your-org.com"
  },
  "metadata": {
    "description": "Marketplace description",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "description": "What the plugin does",
      "version": "1.0.0",
      "author": {
        "name": "Author Name"
      },
      "source": "./plugins/plugin-name",
      "category": "utilities",
      "tags": ["tag1", "tag2"],
      "keywords": ["keyword1", "keyword2"]
    }
  ]
}

Required Fields

Marketplace Level

• name: kebab-case string, unique marketplace identifier
• owner: Object with name (required) and optional email
• plugins: Array of plugin entries

Plugin Entry

• name: Plugin name (must match plugin.json)
• source: Relative path to plugin directory OR git URL

Optional Fields

Marketplace Level

• metadata: Object with:
  • description: Brief marketplace description
  • version: Marketplace version
  • pluginRoot: Base path for relative plugin sources (allows resolving relative plugin paths)

Plugin Entry

Standard metadata fields:

• description: Brief description
• version: SemVer version
• author: String or object with name, email, url
• category: Category string (e.g., "utilities", "productivity")
• tags: Array of tags for filtering
• keywords: Array of keywords for search
• homepage: Plugin homepage URL
• repository: Plugin repository URL
• license: License identifier (e.g., "MIT")
• strict: Boolean (default: true) - Require plugin.json in plugin folder

Component configuration fields:

• commands: String or array - Custom paths to command files or directories
• agents: String or array - Custom paths to agent files
• hooks: String or object - Custom hooks configuration or path to hooks file
• mcpServers: String or object - MCP server configurations or path to MCP config

Source Types

Local Path (Development)

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

Git Repository

Simple string format:

{
  "source": "https://github.com/user/repo"
}

Object format for advanced configuration:

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

Git URL Source

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

Git with Subdirectory

{
  "source": "https://github.com/user/repo/tree/main/plugins/my-plugin"
}

Examples

Local Dev Marketplace

{
  "name": "dev-marketplace",
  "owner": {
    "name": "Developer",
    "email": "dev@localhost"
  },
  "metadata": {
    "description": "Local development marketplace",
    "version": "0.1.0"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "description": "Plugin in development",
      "source": "../my-plugin"
    }
  ]
}

Team Marketplace

{
  "name": "acme-tools",
  "owner": {
    "name": "ACME Corp",
    "email": "tools@acme.com"
  },
  "metadata": {
    "description": "ACME internal tools for Claude Code",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "code-review",
      "description": "ACME code review standards",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      },
      "source": "./plugins/code-review",
      "category": "development",
      "tags": ["code-review", "standards"],
      "keywords": ["review", "quality", "standards"]
    },
    {
      "name": "deploy-tools",
      "description": "Deployment automation",
      "version": "1.5.0",
      "author": {
        "name": "DevOps Team"
      },
      "source": "./plugins/deploy-tools",
      "category": "devops",
      "tags": ["deployment", "automation"],
      "keywords": ["deploy", "ci", "cd"]
    }
  ]
}

Advanced Plugin Entry

Plugin entries can override default component locations and provide inline configuration:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@company.com"
  },
  "homepage": "https://docs.company.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": "./config/hooks.json",
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

**Schema relationship**: Plugin entries are based on 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. **Environment variables**: Use `${CLAUDE_PLUGIN_ROOT}` in hooks and mcpServers configurations. This variable resolves to the plugin's installation directory and ensures paths work correctly regardless of where the plugin is installed.

Usage

Add Marketplace (Local)

/plugin marketplace add /path/to/marketplace

Add Marketplace (GitHub)

/plugin marketplace add your-org/your-repo

Install Plugin from Marketplace

/plugin install plugin-name@marketplace-name

Team Auto-Install

In project .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/marketplace-repo"
      }
    }
  },
  "enabledPlugins": {
    "plugin-name@team-tools": true
  }
}

Testing Workflow

1. Create dev marketplace:

   mkdir -p dev-marketplace/.claude-plugin
   # Create marketplace.json pointing to ../your-plugin
   

2. Add to Claude Code:

   /plugin marketplace add ./dev-marketplace
   

3. Install plugin:

   /plugin install your-plugin@dev-marketplace
   

4. After changes, reinstall:

   /plugin uninstall your-plugin@dev-marketplace
   /plugin install your-plugin@dev-marketplace
   

Best Practices

• Use kebab-case for marketplace and plugin names
• Keep descriptions concise (< 100 chars)
• Add meaningful tags for discoverability
• Version consistently using SemVer
• Test locally before publishing to GitHub
• Document plugins in their README files

Common Mistakes

❌ Plugin name mismatch

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

// plugin.json (in other-plugin/)
{ "name": "other-plugin" }  // Names don't match!

✅ Names must match

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

// plugin.json
{ "name": "my-plugin" }  // Matches!

❌ Absolute source paths

{
  "source": "/Users/you/plugins/my-plugin"
}

✅ Relative source paths

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

Validation

Use /plugin-development:validate to check marketplace structure.