marketplace-structure

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

GitHub Repositories with Pinning

Pin to a specific ref or commit SHA for reproducible builds:

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

• ref — Branch, tag, or commit reference (e.g., "v1.0", "main")
• sha — Exact commit SHA for integrity verification

Git URLs

For GitLab, Bitbucket, or self-hosted git:

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

Host Pattern

Match plugins by URL pattern:

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

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
}

Enterprise Features

Managed Marketplace Restrictions

Organizations can restrict which marketplaces users can install from using managed settings:

{
  "strictKnownMarketplaces": true
}

When enabled, users can only install plugins from officially approved marketplaces. Additional marketplaces can be added via extraKnownMarketplaces in managed settings.

Private Repository Authentication

For marketplaces hosted in private repositories, set the appropriate environment variable:

• GitHub: GITHUB_TOKEN
• GitLab: GITLAB_TOKEN
• Bitbucket: BITBUCKET_TOKEN

See references/distribution-patterns.md for configuration details.

Reserved Marketplace Names

Some marketplace names are reserved by Anthropic for official use. Choose distinctive names for custom marketplaces to avoid conflicts.

URL-Based Marketplace Limitations

Marketplaces added via URL (rather than git source) have limited support for relative paths in plugin sources. Relative paths may not resolve correctly — prefer absolute source references or git-based marketplaces.

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.