Create and distribute a plugin marketplace

​

Overview

1. Create plugins: build one or more plugins with skills, agents, hooks, MCP servers, or LSP servers. This guide assumes you already have plugins to distribute; see Create plugins for details on how to create them.
2. Create the marketplace file: define a marketplace.json that lists your plugins and where to find them. See Create the marketplace file.
3. Host the marketplace: push to GitHub, GitLab, or another git host. See Host and distribute marketplaces.
4. Share with users: users add your marketplace with /plugin marketplace add and install individual plugins. See Discover and install plugins.

​

Walkthrough: create a local marketplace

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

---
description: Review code for bugs, security, and performance
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

{
  "name": "quality-review-plugin",
  "description": "Adds a quality-review skill for quick code reviews",
  "version": "1.0.0"
}

{
  "name": "my-plugins",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quality-review skill for quick code reviews"
    }
  ]
}

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

/quality-review-plugin:quality-review

​

Create the marketplace file

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.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

​

Owner fields

​

Optional fields

​

Plugin entries

​

Required fields

​

Optional plugin fields

​

Plugin sources

​

Relative paths

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

​

GitHub repositories

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

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

​

Git repositories

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

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

​

Git subdirectories

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

​

npm packages

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

​

Advanced plugin entries

{
  "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@example.com"
  },
  "homepage": "https://docs.example.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
}

• commands and agents: you can specify multiple directories or individual files. Paths are relative to the plugin root.
• ${CLAUDE_PLUGIN_ROOT}: use this variable in hook commands and MCP server configs to reference files within the plugin’s installation directory. This is necessary because plugins are copied to a cache location when installed.
  • See the substitution table for which config fields substitute it per server type
  • For dependencies or state that should survive plugin updates, use ${CLAUDE_PLUGIN_DATA} instead
• strict: false: since this is set to false, the plugin doesn’t need its own plugin.json. The marketplace entry defines everything. See Strict mode below.

"skills": ["./skills/", "./extra-skills/"]

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

​

Strict mode

• strict: true: the plugin has its own plugin.json and manages its own components. The marketplace entry can add extra skills or hooks on top. This is the default and works for most plugins.
• strict: false: the marketplace operator wants full control. The plugin repo provides raw files, and the marketplace entry defines which of those files are exposed as skills, agents, hooks, etc. Useful when the marketplace restructures or curates a plugin’s components differently than the plugin author intended.

​

Host and distribute marketplaces

​

Host on GitHub (recommended)

1. Create a repository: set up a new repository for your marketplace
2. Add marketplace file: create .claude-plugin/marketplace.json with your plugin definitions
3. Share with teams: users add your marketplace with /plugin marketplace add owner/repo

​

Host on other git services

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

​

Private repositories

• Set CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 to keep the existing clone when the background pull fails, instead of deleting and re-cloning. Your plugins keep working from the last synced state, and manual updates with /plugin marketplace update still pull with your credentials.
• Configure a git credential helper, for example with gh auth setup-git for GitHub, so the re-clone fallback can authenticate without prompting.

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

​

Test locally before distribution

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

​

Require marketplaces for your team

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

​

Pre-populate plugins for containers

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

• Read-only: the seed directory is never written to. Auto-updates are disabled for seed marketplaces since git pull would fail on a read-only filesystem.
• Seed entries take precedence: marketplaces declared in the seed overwrite any matching entries in the user’s configuration on each startup. To opt out of a seed plugin, use /plugin disable rather than removing the marketplace.
• Path resolution: Claude Code locates marketplace content by probing $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ at runtime, not by trusting paths stored inside the seed’s JSON. This means the seed works correctly even when mounted at a different path than where it was built.
• Mutation is blocked: running /plugin marketplace remove or /plugin marketplace update against a seed-managed marketplace fails with guidance to ask your administrator to update the seed image.
• Composes with settings: if extraKnownMarketplaces or enabledPlugins declare a marketplace that already exists in the seed, Claude Code uses the seed copy instead of cloning.

​

Managed marketplace restrictions

​

Common configurations

{
  "strictKnownMarketplaces": []
}

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

​

How restrictions work

• For GitHub sources: repo is required, and ref or path must also match if specified in the allowlist
• For URL sources: the full URL must match exactly
• For hostPattern sources: the marketplace host is matched against the regex pattern
• For pathPattern sources: the marketplace’s filesystem path is matched against the regex pattern

​

Version resolution and release channels

1. version in the plugin’s plugin.json
2. version in the plugin’s marketplace entry
3. The git commit SHA of the plugin’s source

​

Set up release channels

Example

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

Assign channels to user groups

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

​

Pin dependency versions

​

Rename or remove a plugin

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

• If the entry points to a new name, Claude Code loads the plugin under its new name and shows a one-line notice such as Renamed to "code-formatter" in the "acme-tools" marketplace. It then rewrites the old key to the new key in the user, project, and local settings scopes for both enabledPlugins and pluginConfigs, so the notice appears once.
• For a null entry, Claude Code drops the old key and the notice reports that the plugin was removed from the marketplace.
• If the renamed plugin uses a remote source such as github or npm, Claude Code reports plugin-cache-miss after the rename and the user must run /plugin install once to fetch it under the new name.

​

Validation and testing

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

Manage marketplaces from the CLI

​

Plugin marketplace add

claude plugin marketplace add <source> [options]

• <source>: GitHub owner/repo shorthand, git URL, remote URL to a marketplace.json file, or local directory path. To pin to a branch or tag, append @ref to the GitHub shorthand or #ref to a git URL

claude plugin marketplace add acme-corp/claude-plugins

claude plugin marketplace add acme-corp/claude-plugins@v2.0

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

claude plugin marketplace add https://example.com/marketplace.json

claude plugin marketplace add ./my-marketplace

claude plugin marketplace add acme-corp/claude-plugins --scope project

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

​

Plugin marketplace list

claude plugin marketplace list [options]

​

Plugin marketplace remove

claude plugin marketplace remove <name> [options]

• <name>: marketplace name to remove, as shown by claude plugin marketplace list. This is the name from marketplace.json, not the source you passed to add

​

Plugin marketplace update

claude plugin marketplace update [name]

• [name]: marketplace name to update, as shown by claude plugin marketplace list. Updates all marketplaces if omitted

​

Troubleshooting

​

Marketplace not loading

• 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 or /plugin validate. To check skill, agent, and command frontmatter, run the command against each plugin directory
• For private repositories, confirm you have access permissions

​

Marketplace validation errors

• includes plugins whose source is .
• runs when marketplace.json is outside a .claude-plugin directory, resolving sources against the file’s own directory
• reports each entry’s problems even when another part of the file has schema errors

• Marketplace has no plugins defined: add at least one plugin to the plugins array
• No marketplace description provided: add a top-level description to help users understand your marketplace
• Plugin name "x" is not kebab-case: the plugin name contains uppercase letters, spaces, or special characters. Rename to lowercase letters, digits, and hyphens only (for example, my-plugin). Claude Code accepts other forms, but the claude.ai marketplace sync rejects them.

​

Plugin installation failures

• Verify plugin source URLs are accessible
• Check that plugin directories contain required files
• For GitHub sources, ensure repositories are public or you have access
• Test plugin sources manually by cloning/downloading
• If the source pins both ref and sha, a deleted upstream branch or tag doesn’t block installation on most git hosts, including GitHub, GitLab, and Bitbucket. On servers that don’t support fetching commits by SHA, such as AWS CodeCommit, the ref must still exist and the pinned commit must be reachable from it. If the install still fails, confirm the pinned commit still exists in the repository

​

Private repository authentication fails

• Verify you’re authenticated with your git provider (for example, run gh auth status for GitHub)
• Check that your credential helper is configured correctly: git config --global credential.helper
• Try cloning the repository manually to verify your credentials work

• By default, background refreshes disable git credential helpers for the pull, so the pull can’t authenticate over HTTPS. SSH remotes with a key loaded in ssh-agent still authenticate. A failed pull triggers a re-clone from scratch, which uses your stored credentials but may time out on large repositories
• Set CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 to keep the existing clone when the background pull fails
• Configure a git credential helper, for example gh auth setup-git, so the re-clone fallback can authenticate
• If the re-clone times out on a large repository, increase the limit with CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
• Configure a git URL rewrite scoped to the marketplace repository so the background pull authenticates directly
• Or update private marketplaces manually with /plugin marketplace update <name>, which uses your credentials

​

Marketplace updates fail in offline environments

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

​

Git operations time out

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutes

​

Plugins with relative paths fail in URL-based marketplaces

• Use external sources: Change plugin entries to use GitHub, npm, or git URL sources instead of relative paths:
  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  
• Use a Git-based marketplace: Host your marketplace in a Git repository and add it with the git URL. Git-based marketplaces clone the entire repository, making relative paths work correctly.

​

Files not found after installation

​

See also

• Discover and install prebuilt plugins - Installing plugins from existing marketplaces
• Plugins - Creating your own plugins
• Plugins reference - Complete technical specifications and schemas
• Plugin settings - Plugin configuration options
• strictKnownMarketplaces reference - Managed marketplace restrictions