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

/plugin install

/plugin marketplace add

Directory Structure

Place

marketplace.json

.claude-plugin/

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

Required Fields

name

owner

plugins

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

Plugin Entry Format

Each plugin in the

plugins

name

source

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

plugin.json

strict: true

plugin.json

strict: false

plugin.json

Use

strict: false

• 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

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

.claude-plugin/marketplace.json