Marketplace reference

Two kinds of source object turn up around marketplaces, and mixing them up causes most of the confusion I see:

• A plugin source sits inside each entry of marketplace.json and says where to fetch that one plugin.
• A marketplace source says where to fetch the marketplace.json file itself. You write one in settings (extraKnownMarketplaces, strictKnownMarketplaces, blockedMarketplaces), or Claude Code builds one when you run claude plugin marketplace add.

This page is the exact reference for both, plus the catalogue file. For a walkthrough see Create a marketplace and Host a marketplace; for allowlist recipes see Manage plugins for your organisation.

The catalogue file

Put it at .claude-plugin/marketplace.json. The folder containing .claude-plugin/ is the marketplace root, and every relative plugin path resolves from there, not from .claude-plugin/. If you store the file elsewhere in a repo, users must declare the marketplace through extraKnownMarketplaces with a path on the source, because claude plugin marketplace add has no option for a custom location.

A user can only have one marketplace registered per name.

Unknown keys at the top level or inside entries are ignored, which means a typo silently does nothing. The validator warns about each one, so run it.

Top-level fields

name, owner and plugins are required.

The last three are explained with examples on Host a marketplace.

Reserved names

Marketplaces may not use these names:

Control or bidirectional formatting characters in a name produce Marketplace name cannot contain control or bidirectional-formatting characters. When a registered marketplace stops loading because of an impersonating name, claude plugin list and /plugin say Claude Code refuses the marketplace name "<name>" and tell you to remove it (v2.1.282 or later). Removing it also uninstalls its plugins and deletes their data.

Plugin entries

Each entry in plugins needs name and source. Besides its own fields, an entry accepts every plugin.json field apart from the directory listing fields. The table lists the entry-specific fields and those whose meaning shifts in an entry:

How an entry and plugin.json combine

• The fetched plugin has no plugin.json: the entry is the manifest regardless of strict, and every manifest field it carries applies, including mcpServers, lspServers, userConfig and channels.
• The plugin has a plugin.json: that file is the manifest. strict decides what happens to the entry's six component fields (commands, agents, skills, hooks, outputStyles, themes). Entry mcpServers, lspServers, userConfig and channels are ignored; declare those in plugin.json.

Hooks on an entry

Write them as an inline object mapping event names to matcher arrays. A file path or array passes validation but never runs, and the plugin reports not yet supported in a marketplace entry. Keep file-based hooks in the plugin's own hooks/hooks.json or plugin.json.

Display fields

displayName, description, author, homepage, repository, license and keywords can be set on either side. If the entry sets one, users see the entry's value; otherwise they see plugin.json's. Before installation Claude Code can only read plugin.json for relative-path entries (the files are already in the marketplace), so for any other source users see only entry fields until they install.

Strict mode

Plugin sources

A plugin source is either a relative path string or an object whose own source key names the type.

Note the overlapping names: url and github are also marketplace source types (where url means a direct link to marketplace.json), git exists only as a marketplace source, npm exists as both, and git-subdir, archive and command exist only as plugin sources.

Shared git fields (github, url, git-subdir):

• ref: branch or tag; defaults to the repo's default branch.
• sha: full 40-character lowercase commit. If both are set, sha is checked out. On GitHub, GitLab, Bitbucket and most hosts that means installs still work after the ref is deleted, provided the commit is reachable. Hosts that cannot fetch by SHA (AWS CodeCommit, for example) still need the ref to exist and contain the commit.

Relative path

Resolves from the marketplace root. .. fails validation, and on macOS and Linux any backslash after the leading ./ is refused, so use forward slashes.

{ "name": "pdf-tools", "source": "./plugins/pdf-tools" }

Relative paths only work when Claude Code has the marketplace's files. That is true for github, git, file and directory marketplace sources. It is not true for url (only marketplace.json is downloaded) and relative paths are rejected outright for settings sources.

Bare names. With "metadata": { "pluginRoot": "./plugins" }, an entry can say "source": "pdf-tools" and resolve to ./plugins/pdf-tools (v2.1.239 or later). pluginRoot must be a relative path inside the marketplace, has no effect on sources already starting ./, and anything containing a / (such as team-a/pdf-tools) is not a bare name and still needs ./.

github

{
  "name": "pdf-tools",
  "source": {
    "source": "github",
    "repo": "cshields/pdf-tools",
    "ref": "release",
    "sha": "4f1c0a9e7b2d3c5e6f8091a2b3c4d5e6f7a8b9c0"
  }
}

url

A full git URL: https://, http://, file:// or git@. No .git suffix is needed, so Azure DevOps and CodeCommit URLs work as copied. No owner/repo shorthand.

{
  "name": "pdf-tools",
  "source": { "source": "url", "url": "https://dev.azure.com/acme/tools/_git/pdf-tools", "ref": "main" }
}

git-subdir

url accepts a full git URL or owner/repo shorthand; path is the plugin's folder. Only that folder is checked out, and over HTTPS or SSH a partial clone is requested, so a plugin in a huge monorepo installs without pulling the whole repo (where the host supports it).

{
  "name": "pdf-tools",
  "source": { "source": "git-subdir", "url": "acme/platform-monorepo", "path": "claude/pdf-tools" }
}

npm

• package: a name (@acme/pdf-tools), a name with version (@acme/pdf-tools@3.1.0), or an https tarball URL.
• version: version, range or dist-tag, used when package has no version. Defaults to latest.
• registry: registry URL if not the default. Must be https unless it is the user's own default registry.

The package is fetched with the user's npm client; its install scripts never run and its dependencies are not installed during the fetch. If it ships a supported lockfile, dependencies are installed in a separate locked-down step (see How plugins load).

package values that are refused before anything is fetched: git addresses, folder or file: paths, npm: aliases, tarball links on github.com, gist.github.com, gitlab.com, bitbucket.org or git.sr.ht (GitLab registry links under gitlab.com/api/v4/ are allowed), and http tarballs unless on the user's default registry.

{
  "name": "pdf-tools",
  "source": { "source": "npm", "package": "@acme/pdf-tools", "version": "~3.1.0", "registry": "https://npm.acme.internal" }
}

archive

url must be https:// and may not target loopback, link-local or cloud metadata hosts. Size and timeout limits are on Host a marketplace. The plugin can sit at the top of the zip or one folder down. sha256 is 64 hex characters (any case); if set, mismatching downloads are refused.

{
  "name": "pdf-tools",
  "source": {
    "source": "archive",
    "url": "https://releases.acme.dev/pdf-tools/3.1.0.zip",
    "sha256": "0d6e4079e36703ebd37c00722f5891d28b0e2811dc114b129215123adcce3605"
  }
}

command

For when a tool already on the user's machine generates the plugin, such as an IDE rendering a plugin for the currently selected toolchain. The command runs on install and update and again once per session, so users get fresh output without reinstalling.

• command: shell command printing the plugin folder's absolute path on one line and exiting 0. Shown to the user for approval in full. Printable ASCII, at most 500 characters, no run of four or more spaces.
• timeout: 1 to 600 seconds; default 60.
• mode: copy (default) or link.

{
  "name": "pdf-tools",
  "source": { "source": "command", "command": "acme-sdk export-claude-plugin --print-path", "timeout": 90 }
}

The command runs via sh (or cmd.exe on Windows) from the user's home directory, so use absolute paths or commands on PATH. The printed folder must contain the complete plugin when the command exits; the path may change between runs.

It fails if the command exits non-zero, overruns, or prints anything other than one absolute path, and also if the printed folder has no plugin content at its top level (no .claude-plugin/, skills/, commands/, agents/ or hooks/), is the session's start directory or one of its parents, is a UNC path on Windows, or (in copy mode) exceeds 256 MiB or 20,000 entries.

Copy versus link mode:

How users approve the command is covered on Install plugins. Admins can disable these sources with disableCommandPluginSources (see the settings reference).

Marketplace sources

These say where marketplace.json comes from.

Every type and where it is valid

Field details

Policy-only values

hostPattern, pathPattern, skills-dir and the owner/* form of repo are only meaningful in strictKnownMarketplaces and blockedMarketplaces. The two patterns are regular expressions tested before any fetch. skills-dir is not really a source: once any allowlist exists, skills-directory plugins stop loading until you add {"source": "skills-dir"}. owner/* matches every repo under exactly that owner (v2.1.223 or later).

Writing sources in settings

extraKnownMarketplaces maps a name to an object containing source:

{
  "extraKnownMarketplaces": {
    "studio-plugins": {
      "source": {
        "source": "github",
        "repo": "cshields/studio-plugins",
        "sparsePaths": [".claude-plugin", "plugins"]
      }
    }
  }
}

An inline settings marketplace needs no hosted file at all:

{
  "extraKnownMarketplaces": {
    "local-experiments": {
      "source": {
        "source": "settings",
        "name": "local-experiments",
        "plugins": [
          { "name": "pdf-tools", "source": { "source": "github", "repo": "cshields/pdf-tools" } }
        ]
      }
    }
  }
}

The policy lists are arrays of source objects:

{
  "blockedMarketplaces": [
    { "source": "hostPattern", "hostPattern": "(^|\\.)pastebin\\.com$" },
    { "source": "pathPattern", "pathPattern": "^/tmp/" }
  ]
}

Validation messages

claude plugin validate <path> accepts the marketplace root or the catalogue file. Entries are referred to by index, as plugins.1.source or plugins[1].source. Messages prefixed with an index and plugin.json → concern that plugin's own files; those are covered on Plugin troubleshooting. Warnings that mention Claude Desktop flag names that the desktop app would reject. Exit codes and --strict are on the plugin CLI reference.

Errors

Warnings

"Invalid input" on a source

The source object matched no known type. Typical causes: an npm package containing .., a misspelt source type, or a known type missing a required field (a github source with no repo, say).

What validation cannot see

Entry hooks written as a path or array pass validation and only fail at load. Fetch errors for remote sources only appear at install. For load-time failures, claude plugin list shows the error beside the plugin, and Plugin troubleshooting explains each message.

Related

• Create a marketplace
• Host a marketplace
• Plugin manifest reference
• Manage plugins for your organisation