Plugin marketplaces

Create and manage plugin marketplaces to distribute Claude Code extensions across teams and communities.

Plugin marketplaces are catalogs of available plugins that make it easy to discover, install, and manage Claude Code extensions. This guide shows you how to use existing marketplaces and create your own for team distribution.

Overview

A marketplace is a JSON file that lists available plugins and describes where to find them. 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 your organization
Flexible sources: Support for git repositories, GitHub repos, local paths, and package managers

Prerequisites

Claude Code installed and running
Basic familiarity with JSON file format
For creating marketplaces: Git repository or local development environment

Add and use marketplaces

Add marketplaces using the /plugin marketplace commands to access plugins from different sources:

Add GitHub marketplaces

/plugin marketplace add owner/repo

Add Git repositories

/plugin marketplace add https://gitlab.com/company/plugins.git

Add local marketplaces for development

/plugin marketplace add ./my-marketplace

/plugin marketplace add ./path/to/marketplace.json

/plugin marketplace add https://url.of/marketplace.json

Install plugins from marketplaces

Once you've added marketplaces, install plugins directly:

/plugin install plugin-name@marketplace-name

/plugin

Verify marketplace installation

After adding a marketplace:

List marketplaces: Run /plugin marketplace list to confirm it's added
Browse plugins: Use /plugin to see available plugins from your marketplace
Test installation: Try installing a plugin to verify the marketplace works correctly

Configure team marketplaces

Set up automatic marketplace installation for team projects by specifying required marketplaces in .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    },
    "project-specific": {
      "source": {
        "source": "git",
        "url": "https://git.company.com/project-plugins.git"
      }
    }
  }
}

When team members trust the repository folder, Claude Code automatically installs these marketplaces and any plugins specified in the enabledPlugins field.

Create your own marketplace

Build and distribute custom plugin collections for your team or community.

Prerequisites for marketplace creation

Git repository (GitHub, GitLab, or other git hosting)
Understanding of JSON file format
One or more plugins to distribute

Create the marketplace file

Create .claude-plugin/marketplace.json in your repository root:

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@company.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Marketplace schema

Required fields

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

Optional metadata

Field	Type	Description
`metadata.description`	string	Brief marketplace description
`metadata.version`	string	Marketplace version
`metadata.pluginRoot`	string	Base path for relative plugin sources

Plugin entries

Plugin entries are based on the *plugin manifest schema* (with all fields made optional) plus marketplace-specific fields (`source`, `category`, `tags`, `strict`), with `name` being required.

Required fields:

Field	Type	Description
`name`	string	Plugin identifier (kebab-case, no spaces)
`source`	string\|object	Where to fetch the plugin from

Optional plugin fields

Standard metadata fields:

Field	Type	Description
`description`	string	Brief plugin description
`version`	string	Plugin version
`author`	object	Plugin author information
`homepage`	string	Plugin homepage or documentation URL
`repository`	string	Source code repository URL
`license`	string	SPDX license identifier (e.g., MIT, Apache-2.0)
`keywords`	array	Tags for plugin discovery and categorization
`category`	string	Plugin category for organization
`tags`	array	Tags for searchability
`strict`	boolean	Require plugin.json in plugin folder (default: true) ¹

Component configuration fields:

Field	Type	Description
`commands`	string\|array	Custom paths to command files or directories
`agents`	string\|array	Custom paths to agent files
`hooks`	string\|object	Custom hooks configuration or path to hooks file
`mcpServers`	string\|object	MCP server configurations or path to MCP config

^{1 - When strict: true (default), the plugin must include a plugin.json manifest file, and marketplace fields supplement those values. When strict: false, the plugin.json is optional. If it's missing, the marketplace entry serves as the complete plugin manifest.}

Plugin sources

Relative paths

For plugins in the same repository:

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

GitHub repositories

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

Git repositories

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

Advanced plugin entries

Plugin entries can override default component locations and provide additional metadata. Note that ${CLAUDE_PLUGIN_ROOT} is an environment variable that resolves to the plugin's installation directory (for details see Environment variables):

{
  "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": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{"type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"}]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

**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.

Host and distribute marketplaces

Choose the best hosting strategy for your plugin distribution needs.

Host on GitHub (recommended)

GitHub provides the easiest distribution method:

Create a repository: Set up a new repository for your marketplace
Add marketplace file: Create .claude-plugin/marketplace.json with your plugin definitions
Share with teams: Team members add with /plugin marketplace add owner/repo

Benefits: Built-in version control, issue tracking, and team collaboration features.

Host on other git services

Any git hosting service works for marketplace distribution, using a URL to an arbitrary git repository.

For example, using GitLab:

/plugin marketplace add https://gitlab.com/company/plugins.git

Use local marketplaces for development

Test your marketplace locally before distribution:

/plugin marketplace add ./my-local-marketplace

/plugin install test-plugin@my-local-marketplace

Manage marketplace operations

List known marketplaces

/plugin marketplace list

Shows all configured marketplaces with their sources and status.

Update marketplace metadata

/plugin marketplace update marketplace-name

Refreshes plugin listings and metadata from the marketplace source.

Remove a marketplace

/plugin marketplace remove marketplace-name

Removes the marketplace from your configuration.

Removing a marketplace will uninstall any plugins you installed from it.

Troubleshooting marketplaces

Common marketplace issues

Marketplace not loading

Symptoms: Can't add marketplace or see plugins from it

Solutions:

Verify the marketplace URL is accessible
Check that .claude-plugin/marketplace.json exists at the specified path
Ensure JSON syntax is valid using claude plugin validate
For private repositories, confirm you have access permissions

Plugin installation failures

Symptoms: Marketplace appears but plugin installation fails