Marketplace reference - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. marketplace.json is the file that defines a plugin marketplace. It contains the marketplace’s name, its owner, and one entry per plugin. Each entry’s plugin source says where Claude Code fetches that plugin from.
A marketplace source is a separate object that says where Claude Code fetches the marketplace file itself. You write one in settings, or Claude Code builds one when you run claude plugin marketplace add . This reference is for marketplace maintainers who need an exact field name or value, and for administrators who need to know which source values are valid in extraKnownMarketplaces , strictKnownMarketplaces , and blockedMarketplaces .
These cases are covered on other pages: Building or hosting a marketplace : see Create a marketplace and Host and maintain a marketplace Allowlist and blocklist recipes : see Manage plugins for your organization Find the section for what you’re writing or reading: The marketplace file : Top-level fields and Plugin entries An entry’s source : Plugin sources A source object in settings : Marketplace sources Output from claude plugin validate <path> : Validation messages , which maps each message to the field it names Marketplace file Save the marketplace file at .claude-plugin/marketplace.json in your marketplace’s directory.
If you keep the file somewhere else in the repository, users have to declare the marketplace in extraKnownMarketplaces with path set on its source, because claude plugin marketplace add has no option for it. The directory that contains .claude-plugin/ is called the marketplace root, and every relative plugin source resolves from it, not from .claude-plugin/ . Each user registers one marketplace per name , so a user can’t have two marketplaces with the same name registered at once.
Claude Code ignores an unknown top-level key or plugin-entry key rather than rejecting it, so a typo loads silently. claude plugin validate reports each unknown key as a warning. Reserved names You can’t give your marketplace any of the following names: Official marketplace names : claude-code-marketplace , claude-code-plugins , claude-plugins-official , anthropic-marketplace , anthropic-plugins , agent-skills , anthropic-agent-skills , life-sciences , knowledge-work-plugins , claude-for-legal , claude-for-financial-services , financial-services-plugins , first-party-plugins , and claude-tag-plugins .
Reserved unless the marketplace comes from a github or git marketplace source under github.com/anthropics/ . Community marketplace names : claude-community , claude-plugins-community , and healthcare . Reserved under the same rule as the official names. Plugin directory names : anthropic-plugin-directory and claude-plugin-directory . Reserved under the same rule as the official names. Names that impersonate an official marketplace : names such as official-claude-plugins or claude-plugins-v2 , and any name containing a non-ASCII character.
The error is Marketplace name impersonates an official Anthropic/Claude marketplace . A control or bidirectional-formatting character in a name also reports Marketplace name cannot contain control or bidirectional-formatting characters . A marketplace already registered under such a name stops loading, along with its plugins. Another spelling of a reserved name : a name that differs from a reserved name only by a trailing dot, or by a symbol other than an underscore in place of a hyphen, so claude.code.plugins counts as claude-code-plugins .
Adding the marketplace fails with is another spelling of "<reserved>", a reserved marketplace name , and a marketplace already registered under one stops loading. This check requires Claude Code v2.1.280 or later. Names Claude Code uses for plugins that don’t come from a marketplace : inline for plugins loaded with --plugin-dir , builtin for built-in plugins, skills-dir for plugins auto-loaded from .claude/skills/ , and synced for plugins synced from your claude.ai account. claude-plugin-test is also reserved. skills-dir also appears as {"source": "skills-dir"} in strictKnownMarketplaces and blockedMarketplaces , described under Source values valid only in policy lists .
Member names that every JavaScript object has : constructor , hasOwnProperty , isPrototypeOf , propertyIsEnumerable , toLocaleString , toString , and valueOf . claude plugin marketplace add refuses a marketplace that uses one with Claude Code reserves this name and cannot register a marketplace under it . This check requires Claude Code v2.1.296 or later. Names starting with claudeai- : reserved for marketplaces hosted on claude.ai. claude plugin marketplace add refuses any other marketplace that uses one with Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai .
The download folder of a registered GitHub marketplace, <owner>-<repo> : Claude Code downloads a marketplace added from a github source such as acme/x-tools through a folder named acme-x-tools , whatever that marketplace’s own name is. While that marketplace is registered under a name other than acme-x-tools , claude plugin marketplace add refuses a different marketplace named acme-x-tools after downloading it, and reports Can't use the marketplace name "acme-x-tools" .
This check requires Claude Code v2.1.290 or later. When a registered marketplace stops loading because its name imitates an official one, claude plugin list and /plugin report Claude Code refuses the marketplace name "<name>" . The message tells you to remove the marketplace. Removing it also uninstalls its plugins and deletes their data, options, and secrets. This named refusal message requires Claude Code v2.1.282 or later.
If a settings file declares the marketplace inline, the message tells you to rename its entry before you remove the old name. For the steps, see Claude Code refuses the marketplace name . The message lists them in Claude Code v2.1.292 or later. Top-level fields The table lists every key Claude Code reads from marketplace.json . name , owner , and plugins are required. Field Type Description name string Marketplace identifier: letters, digits, . , _ , and - , starting with a letter or digit, and no .. . claude plugin validate fails any other name, because Claude Code can’t install plugins from a marketplace that uses one .
Users type the name after @ in a plugin id such as my-plugin@my-marketplace when they install a plugin. See Reserved names owner object Maintainer information. name is required; email and url are optional plugins array Plugin entries . Each entry is validated on its own, so one invalid entry doesn’t fail the marketplace $schema string JSON Schema URL for editor autocomplete. Ignored at load time description string Marketplace description shown to users. claude plugin validate warns when it’s missing version string Marketplace manifest version metadata.description , metadata.version string Alternate location for description and version metadata.pluginRoot string Directory that bare plugin source names resolve under.
See Relative path plugin source . Requires Claude Code v2.1.239 or later forceRemoveDeletedPlugins boolean When true , a plugin you remove from plugins is uninstalled on users’ machines. See Host and maintain a marketplace allowCrossMarketplaceDependenciesOn array of strings Marketplace names whose plugins may be installed as dependencies of this marketplace’s plugins. When you install a plugin, only the list in that plugin’s own marketplace applies, for its whole dependency chain.
See Plugin dependencies renames object Map from a former plugin name to its current name, or to null for a plugin you removed. See Host and maintain a marketplace Plugin entries Each object in the
The rest of this page is on the live site.