Create a marketplace

A plugin marketplace is a directory or repository with a .claude-plugin/marketplace.json file that lists your plugins and where to fetch each one. You push the directory to a git host, and anyone with access registers it in Claude Code with one command and installs your plugins from it. Create your own marketplace when you want a group you choose, such as your team or your organization, to install your plugins and keep receiving your updates from a catalog you control. The repository can be private, it can list as many plugins as you like, and an administrator can require it on every machine.

These cases are covered on other pages:

Sharing one plugin with a few people: send them the plugin’s directory or a .zip of it. See Share a plugin without a marketplace.
Offering a plugin to everyone: submit it to Anthropic’s community marketplace. See Submit to the community marketplace.
Using a plugin yourself: load it with --plugin-dir or save it in your skills directory. See Develop without a marketplace.

Start with Create a marketplace to build one on your own machine and install a plugin from it, then add more plugin entries.

The following steps create a marketplace on your machine, add a plugin to it, register it in Claude Code, and install the plugin from it. That is the whole loop, and it’s the same loop your users go through once you host the marketplace somewhere they can reach. Run every command in your shell, from the directory where you want my-marketplace/ created. You need a plugin to list. The example uses my-first-plugin from Create your first plugin, a plugin with one skill that you run as /my-first-plugin:hello; build it first if you don’t have a plugin yet. To use a plugin of your own instead, substitute its directory and its name wherever the steps say my-first-plugin. For what a plugin directory can contain, see the plugin directory explorer.

Set up the marketplace directory

A marketplace is a directory with a .claude-plugin/marketplace.json file, plus the plugins it lists. Create the marketplace directory and its .claude-plugin/ folder, then copy your plugin in under plugins/:

mkdir -p my-marketplace/.claude-plugin my-marketplace/plugins
cp -r my-first-plugin my-marketplace/plugins/

Check that the plugin is valid where it now sits, so that any later error is about the marketplace and not the plugin:

claude plugin validate ./my-marketplace/plugins/my-first-plugin

The last line of the output reads ✔ Validation passed.

Create the marketplace file

Save marketplace.json at my-marketplace/.claude-plugin/marketplace.json. The file requires a name, an owner, and a plugins array.Each object in plugins is a plugin entry and needs a name and a source. Write the entry’s source as a path from the marketplace root. The root is my-marketplace/, the directory that contains .claude-plugin/.

my-marketplace/.claude-plugin/marketplace.json

{
  "name": "my-marketplace",
  "description": "Plugins for my team",
  "owner": {
    "name": "Your Name"
  },
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./plugins/my-first-plugin",
      "description": "A greeting plugin to learn the basics"
    }
  ]
}

Validate the marketplace

Run claude plugin validate on the marketplace directory to check the JSON syntax, the required fields, and each plugin entry in its .claude-plugin/marketplace.json.

claude plugin validate ./my-marketplace

For the file as written in step 2, the last line of the output reads ✔ Validation passed.

Add the marketplace and install the plugin

claude plugin marketplace add ./my-marketplace

The command prints ✔ Successfully added marketplace: my-marketplace (declared in user settings), which means the marketplace is recorded in your user settings file.Install the plugin. The install id is the entry’s name, an @, and the marketplace name.

claude plugin install my-first-plugin@my-marketplace

The command prints ✔ Successfully installed plugin: my-first-plugin@my-marketplace (scope: user).Inside a session, /plugin marketplace add ./my-marketplace registers the marketplace the same way. /plugin install my-first-plugin@my-marketplace opens the plugin’s details in the /plugin panel, where you install it. For that flow, see Install and manage plugins.

Confirm the plugin loaded

List installed plugins.

claude plugin list

The output lists my-first-plugin@my-marketplace with Status: ✔ enabled.To see what the plugin loaded, show its details.

claude plugin details my-first-plugin

The Component inventory section reads Skills (1) hello.To run the skill, start a session and enter /my-first-plugin:hello. Claude greets you. The command has the plugin’s name as a prefix, as every plugin skill’s name does.

Add plugin entries

Every plugin you distribute is one object in the plugins array of marketplace.json. To add a second plugin, add a second object. These fields cover most entries:

name: the identifier people type before @ when they install. It can’t contain spaces.
source: where Claude Code fetches the plugin from. Write a relative path string for a plugin inside the marketplace directory, as in the walkthrough, or a source object for a plugin outside it. See Choose a plugin source.
description: the line people see next to the plugin when they browse your marketplace in /plugin.

For the full field list, see Plugin entries. An entry can also set any plugin.json field. For when an entry’s plugin.json fields apply to a plugin that has its own plugin.json, see Entry and plugin.json.

Rules for plugin entries

Most failed installs from a new marketplace come from a relative path written from the wrong directory, or from an entry name that differs from the name in the plugin’s plugin.json.

Write relative paths from the marketplace root

The marketplace root is the directory that contains .claude-plugin/. In the walkthrough, that’s my-marketplace/, so the entry’s source is "./plugins/my-first-plugin". The path doesn’t start inside .claude-plugin/, so don’t use .. to leave it. A path with .. and a path to a missing directory fail at different commands:

A path with ..: claude plugin validate reports the entry as invalid. The message begins Path contains "..": ./../plugins/my-first-plugin.
A path to a directory that doesn’t exist: claude plugin validate passes. claude plugin install fails with Source path does not exist: <path>, and <path> is the absolute location Claude Code checked.

Keep the entry name and the manifest name the same

A marketplace plugin has an entry name in marketplace.json and a name in its own plugin.json, called the manifest name. Each name appears in different places:

Entry name: the install id, <entry-name>@<marketplace>. It’s what people type to install, what claude plugin list shows, and the key Claude Code writes under enabledPlugins in their settings file.
Manifest name: the prefix on the plugin’s skills, and the name claude plugin details takes.

When the two names differ and someone installs by the manifest name, Claude Code reports Plugin "<manifest-name>" not found in marketplace "<marketplace>". Keep the two names the same. For more on how Claude Code uses the two names, see Plugin loading reference.

Choose a plugin source

Each plugin entry in marketplace.json has a source that tells Claude Code where to fetch that one plugin. Pick the source by where the plugin’s files are stored. The table lists the sources most marketplace owners use.

Source	Use it when	Minimal `source` value
Relative path	The plugin’s files are inside the marketplace directory itself	`"./plugins/my-first-plugin"`
`github`	The plugin is a GitHub repository of its own	`{ "source": "github", "repo": "your-org/my-first-plugin" }`
`git-subdir`	The plugin is a subdirectory of some other repository, such as a monorepo	`{ "source": "git-subdir", "url": "your-org/monorepo", "path": "tools/my-first-plugin" }`

In a git-subdir source, url takes a git URL or an owner/repo GitHub shorthand. A plugin can also come from one of these source types:

url: a git repository by URL, on any host
archive: a zip file downloaded over HTTPS
npm: an npm package
command: a directory produced by running a command on the machine where the plugin is installed

For the fields of every source type, and for pinning a git-based source to a ref or sha, see Plugin sources.

Validate and test

As you add plugins, run claude plugin validate ./my-marketplace in your shell after every edit, and install from the marketplace on your own machine before you share it. Validation and installation catch different problems.

Problems that validation reports

claude plugin validate reads only files inside the marketplace directory. It reports:

JSON syntax errors, as json: Invalid JSON syntax: <reason>
Missing required fields, such as owner: Invalid input
A marketplace name with spaces, non-ASCII characters, or a form that imitates an official Anthropic marketplace, such as claude-official
A relative source that contains ..
Unknown fields at the top level or in a plugin entry, as warnings
Problems in the plugin.json of each relative-path plugin, as plugins[N] plugin.json → <field>: <message>

For every message validate can print, see Validation messages. For its flags and exit codes, see plugin validate.

Problems that surface when you add or install

Problems that claude plugin validate doesn’t report appear when you add the marketplace or install from it:

When you add the marketplace: the exact official marketplace names, such as claude-plugins-official, pass validation. When you add a marketplace with one of those names, Claude Code refuses it with a message that starts The name '<name>' is reserved for official Anthropic marketplaces.
When you install a plugin:
- Claude Code first fetches a github, git-subdir, or other remote source when you install the plugin, so a wrong repo or path appears then.
- A relative source whose directory doesn’t exist also fails at install, with Source path does not exist: <path>.

Test an edit to a plugin

In the walkthrough, you added my-marketplace from a local directory with a relative-path source. With that setup, Claude Code reads the plugin’s files directly from my-marketplace/plugins/. Your edits take effect at the next session start or when you run /reload-plugins in a session, with no change to the plugin’s version. People who install from your hosted marketplace get a copy in the plugin cache instead. For how they receive a new version, see Keep users up to date.

Remove the marketplace to start over

To remove everything and start over, run claude plugin marketplace remove my-marketplace in your shell. The command removes the marketplace and uninstalls its plugins.

Host your marketplace

Once you can install a plugin from the marketplace on your own machine, as in Create a marketplace, push the marketplace directory to a git host. Your teammates then run claude plugin marketplace add <owner>/<repo> in their shell for a GitHub repository, or the same command with the repository URL. They then install a plugin by name as in the walkthrough. For private-repository access, updates, versioning, and renaming or removing entries, see Host and maintain a marketplace.

Next steps

Host and maintain a marketplace: pick a host, keep users up to date, and rename or remove plugins safely
Marketplace reference: marketplace.json fields and source types
Manage plugins for your organization: require your marketplace and its plugins on every machine
Suggest plugins by relevance: have Claude Code suggest a plugin from your marketplace when a session matches

Plugins

Use plugins

Create plugins

Run a marketplace

Manage plugins for your organization

Troubleshooting

Reference

Create a marketplace