Marketplace Structure

A plugin marketplace is a catalog of available plugins that enables centralized discovery, version management, and distribution. This skill covers creating and maintaining marketplaces for team or community plugin distribution.

Overview

Marketplaces provide:

Centralized discovery - Browse plugins from multiple sources in one place
Version management - Track and update plugin versions automatically
Team distribution - Share required plugins across an organization
Flexible sources - Support for relative paths, GitHub repos, and git URLs

When to Create a Marketplace vs. a Plugin

Create a Plugin	Create a Marketplace
Single-purpose extension	Collection of related plugins
Used directly by end users	Distributes multiple plugins
One team or individual maintains it	Curates plugins from various sources
Installed via `/plugin install`	Added via `/plugin marketplace add`

Directory Structure

Place marketplace.json in the .claude-plugin/ directory at the repository root:

marketplace-repo/
├── .claude-plugin/
│   └── marketplace.json      # Required: Marketplace manifest
├── plugins/                  # Optional: Local plugin directories
│   ├── plugin-one/
│   │   └── .claude-plugin/
│   │       └── plugin.json
│   └── plugin-two/
│       └── .claude-plugin/
│           └── plugin.json
└── README.md                 # Recommended: Marketplace documentation

Marketplace Schema

The marketplace.json manifest defines the marketplace and its available plugins.

Required Fields

Field	Type	Description
`name`	string	Marketplace identifier (kebab-case, no spaces)
`owner`	object	Marketplace maintainer information
`plugins`	array	List of available plugin entries

Owner Object

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

Optional Metadata

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

The pluginRoot field sets the base path for relative plugin sources.

Plugin Entry Format

Each plugin in the plugins array requires:

Field	Type	Description
`name`	string	Plugin identifier (kebab-case, unique within marketplace)
`source`	string or object	Where to fetch the plugin

Optional Plugin Fields

Standard metadata fields:

description - Brief plugin description
version - Plugin version (semver)
author - Author information object
homepage - Documentation URL
repository - Source code URL
license - SPDX license identifier
keywords - Tags for discovery
category - Plugin category
tags - Additional searchability tags

Component configuration fields:

commands - Custom paths to command files or directories
agents - Custom paths to agent files
hooks - Hooks configuration or path to hooks file
mcpServers - MCP server configurations

For complete field reference, see references/schema-reference.md.

Plugin Sources

Relative Paths

For plugins within the same repository:

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

GitHub Repositories

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

Git URLs

For GitLab, Bitbucket, or self-hosted git:

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

Strict vs. Non-Strict Mode

The strict field controls whether plugins must have their own plugin.json:

Mode	Behavior
`strict: true` (default)	Plugin must include `plugin.json`; marketplace entry supplements it
`strict: false`	`plugin.json` optional; marketplace entry serves as complete manifest

Use strict: false when:

Curating external plugins without modifying their source
Providing all metadata in the marketplace entry
Plugin directories contain only commands/agents/skills without manifest

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

Best Practices

Organization

One theme per marketplace - Group related plugins (e.g., "frontend-tools", "security-plugins")
Clear naming - Use descriptive kebab-case names for both marketplace and plugins
Version all entries - Include version for every plugin entry
Document each plugin - Provide description for discoverability

Versioning

Use semantic versioning (X.Y.Z) for marketplace metadata.version
Update marketplace version when adding, removing, or updating plugins
Consider a CHANGELOG.md for tracking changes

Distribution

GitHub hosting - Simplest distribution via /plugin marketplace add owner/repo
Team settings - Configure extraKnownMarketplaces in .claude/settings.json
Local testing - Add with /plugin marketplace add ./path during development

For detailed distribution patterns, see references/distribution-patterns.md.

Validation

Validate marketplace structure before publishing:

# Check JSON syntax
jq . .claude-plugin/marketplace.json

# Verify required fields
jq 'has("name") and has("owner") and has("plugins")' .claude-plugin/marketplace.json

Use the plugin-validator agent with marketplace support for comprehensive validation.

Complete Example

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

Additional Resources

references/schema-reference.md - Complete field reference for marketplace.json
references/distribution-patterns.md - Hosting and team distribution strategies
examples/minimal-marketplace.md - Single plugin marketplace template
examples/team-marketplace.md - Internal company marketplace template
examples/community-marketplace.md - Public multi-plugin marketplace template

Related Skills

plugin-structure - For individual plugin plugin.json details
plugin-validator agent - For validating marketplace structure
/plugin-dev:create-marketplace - Guided marketplace creation workflow

Working Example

This repository (plugin-dev) is itself a marketplace. Examine .claude-plugin/marketplace.json at the repository root for a real-world example of marketplace structure and plugin organization.

marketplace-structure