What Are Claude Code Plugins and Marketplaces? How to Use, Build, and Publish Them

For Claude Code, a bundle of skills, subagents, hooks, and MCP configuration is a plugin. A catalog listing plugin names and where to fetch them is a marketplace. Together, they let you reuse procedures across your projects or share a common set of extensions with a team.

This article takes you from installing an existing plugin to creating a greeting skill and distributing it through a catalog. Keep three distinctions in mind: (1) the plugin itself and its distribution catalog sit at different levels; (2) registering a catalog and installing a plugin are separate operations; (3) a successful validation command does not guarantee correct behavior or safety. The steps follow the official creation guide.

1. What are Claude Code plugins?

A plugin packages Claude Code extensions into a directory you can share and reuse. You do not need every component: a plugin can contain just one skill.

For procedures you use alone, the project’s .claude/skills/ directory may be enough. Plugins help when you want to distribute the same bundle to several places and manage its updates. Extensions such as LSP support and monitoring also exist, but have environment and distribution-route requirements. A small skill is easier to start with and verify.

2. Plugin structure

The following is the standard layout for an individual plugin. If you provide a manifest, it goes at .claude-plugin/plugin.json; skills/, agents/, and hooks/ belong at the plugin’s own root. The distribution catalog, marketplace.json, is separate. The later example puts it at the marketplace’s .claude-plugin/marketplace.json.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # metadata for this plugin
├── skills/
│   └── code-review/SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/hooks.json
├── .mcp.json
└── README.md

Here is an example plugin.json. You can omit the manifest entirely if you use only the standard directory layout. When you do provide one, name is required; description and version are optional.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin for learning the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

The name also becomes the skill namespace: in this example, invoke /my-first-plugin:hello. For distribution cached through Git, the plugin.json version takes precedence, followed by the plugin’s version in the catalog. If neither exists, the resolved source commit SHA is used. Leaving an explicit version unchanged means code changes alone do not make the plugin eligible for an update. Loading directly from a local directory and command sources follow different rules. See the version-management documentation for details.

3. Using /plugin and marketplaces

Start with /plugin. It opens a tabbed manager with Discover, Installed, Marketplaces, and Errors. These are the basic commands:

# Add a marketplace (distribution catalog)
/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace add ./my-marketplace              # local path
/plugin marketplace add https://example.com/marketplace.json

# Choose a scope in the interactive UI, install, and check the enabled state
/plugin install plugin-name@marketplace-name
/plugin enable  plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

# Installed through marketplaces (filter with --enabled / --disabled)
/plugin list
/plugin list --enabled

# Reload changes when needed and check the result
/reload-plugins

Adding a catalog alone does not install plugins. Install them individually after registration. The interactive /plugin install command lets you choose a scope in the detail view. The shell command claude plugin install defaults to user scope; specify --scope to change it.

After installation, check whether the result shows active, pending reload, or a loading error. Reloading can be deferred because of its effect on the prompt cache. In sessions without a terminal, plugin MCP changes may not take effect until the next session. /plugin list covers marketplace installations only; it does not list everything supplied through sync or skills directories. Check the installation and reload conditions, and if MCP will not connect, see troubleshooting MCP connection errors.

4. What is a marketplace?

A marketplace is a catalog with a .claude-plugin/marketplace.json listing plugins and their sources, supplied through a Git repository, local path, or hosted file. There are official and community catalogs.

If a catalog is missing, check registration; if an individual plugin is missing, check its name and source. With an internal catalog, it is also important that users can access both the repository and the plugin itself. When you distribute a JSON file by URL, plugin content at relative paths is not fetched from that URL.

5. Build and publish your own

This example creates one greeting skill. Start with the following layout. The outer .claude-plugin directory is for the catalog; the inner one is for the individual plugin. Run commands from the parent directory containing my-marketplace.

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── my-first-plugin/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── hello/
                └── SKILL.md

(1) Save the JSON from the previous section in the inner my-marketplace/plugins/my-first-plugin/.claude-plugin/plugin.json. (2) Save the following in my-marketplace/plugins/my-first-plugin/skills/hello/SKILL.md. This example uses disable-model-invocation: true so that the skill is used only when explicitly invoked.

---
name: hello
description: Give a short greeting using a name
disable-model-invocation: true
---
Greet the user briefly.
If arguments are provided, include that name in the greeting.
Arguments: $ARGUMENTS

(3) Write the catalog in the outer my-marketplace/.claude-plugin/marketplace.json. Relative source paths are resolved against the marketplace root, not the directory containing marketplace.json.

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "description": "A practice catalog for distributing a greeting skill",
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./plugins/my-first-plugin",
      "description": "A skill that gives a short greeting using a name"
    }
  ]
}

(4) Validate the catalog and the plugin separately. The former checks the catalog schema and plugin.json for local entries, but does not read each skill or hook file. The latter also covers files in the individual plugin’s standard directories. Neither check guarantees correct execution or safety.

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

# Load the individual plugin into this session for testing
claude --plugin-dir ./my-marketplace/plugins/my-first-plugin

In the interactive session that opens, run /my-first-plugin:hello Alex and check for a short greeting that includes Alex. A functional check means examining the output and looking for unwanted side effects, not just confirming the command is visible. If it does not load, check the names in both JSON files, the source path, and the location and frontmatter of SKILL.md.

(5) To test the catalog route too, end the previous test session and start Claude Code without --plugin-dir. The following commands register entries in your configuration, so try them in a practice project and choose the installation scope.

/plugin marketplace add ./my-marketplace
/plugin install my-first-plugin@my-plugins
/my-first-plugin:hello Alex

(6) To distribute it, publish the contents of my-marketplace as the root of a Git repository that users can fetch. Commit the plugins directory as well as the catalog. Users add the actual owner/repo and install the same my-first-plugin@my-plugins. This relative-path layout works for registration through Git or a local directory; it cannot be used unchanged with a standalone marketplace.json URL. See creating, distributing, and validating catalogs for details.

You do not need to apply for an official catalog listing to distribute through your own Git repository. If you also want a community listing, individual authors can use the Console submission form. The form on claude.ai has Team/Enterprise organization and administrative-permission requirements. Submitting to community is separate from being listed in Anthropic’s curated official catalog.

6. Installation scopes and safety

Installation scopes are user (all your projects), project (shared project settings), and local (only you in this project). Distinguish choosing a scope interactively from the shell CLI’s user default. Managed settings are controlled by administrators and restrict users’ configuration changes.

Teams can share sources and enabled state through extraKnownMarketplaces and enabledPlugins in .claude/settings.json. However, writing shared settings is different from completing installation on every member’s computer. Each member must install plugins from external sources. After trusting the project, check catalog registration, access permissions, and installation results in each environment.

Summary

A plugin is a unit for distributing extensions; a marketplace is its catalog. Users register a catalog → install individual plugins → check enabled state and behavior. Authors prepare the plugin and catalog → validate both → invoke the feature → distribute through an accessible repository. Checking scopes, access permissions, and the version used for updates makes the setup easier to reproduce elsewhere.

Automatic registration of the official catalog has conditions, and reviewed listings do not come with an unconditional guarantee of behavior. Start with one feature you need, verify the result, and then expand. Related mechanisms are covered in Claude Code hooks, Claude Agent Skills, MCP, and Claude Code Artifacts.

FAQ

Q. How is a plugin different from a skill?
A. A skill is a procedure to carry out; a plugin is a distribution unit that bundles it with hooks, MCP configuration, and other components. Invoke a plugin skill explicitly with /plugin-name:skill-name. Whether automatic selection is available depends on its description and settings.

Q. I cannot find the official marketplace.
A. The official claude-plugins-official is registered automatically on the first interactive launch, but prior non-interactive use, network restrictions, or managed policies may prevent this. In an environment where it is permitted, try /plugin marketplace add anthropics/claude-plugins-official. Registration alone does not install individual plugins.

Q. Can anyone distribute a plugin they build?
A. One route is to place the plugin and catalog in your own accessible Git repository. Applying for a community listing is separate; individual authors can use the Console submission form. The claude.ai submission route has organization and permission requirements. Also check that the catalog’s source points to the plugin’s actual location.

Q. Why is my plugin not updating after a code change?
A. For distribution cached through Git, the version in plugin.json has highest priority. Changing only the catalog version while leaving that fixed will not update the plugin. If neither provides a version, the resolved Git commit SHA is used, but update operations and the source ref also matter. Loading in place from a local directory, archive sources, and command sources have different rules.

Q. Is a plugin safe if validate succeeds?
A. No. Validating structure and configuration is separate from testing actual behavior and safety. Validating only the catalog does not inspect skill bodies and similar files. Validate the individual plugin and test its features and side effects. Community listing review is also no substitute for checking the publisher and bundled code.