Claude Code Plugin Marketplaces: Add, Update, Trust

Run this on a fresh machine and there's a decent chance it fails:

/plugin install skill-creator@claude-plugins-official

Claude Code answers that the plugin isn't found in any marketplace. Nothing is broken. The half after the @ points at a catalog your install has either never heard of, or heard of once and hasn't re-checked since.

A marketplace isn't a website you browse. It's a git repository containing a .claude-plugin/marketplace.json that lists plugins and where their code lives. You register the catalog on your machine once, and after that plugin names resolve against it. The official one is anthropics/claude-plugins-official, where skill-creator sits under /tree/main/plugins/skill-creator.

What a plugin can ship

Anthropic's plugin reference is blunt about the contents. A plugin is a self-contained directory whose components can include skills, agents, hooks, MCP servers, LSP servers, and background monitors.

Hooks run commands on your machine in response to events. MCP servers are processes that start automatically when the plugin is enabled. Monitors run unsandboxed at the same trust level as hooks. A skill is markdown that Claude reads. A plugin can be markdown plus a running process plus a command that fires every time you save a file.

Most plugins are boring and useful and ship one skill. That's fine. But the format permits more, so "it's just a skill" is a shaky default assumption about anything you install from a catalog. If the distinction between these layers is still fuzzy, skills vs MCP servers vs plugins untangles it properly.

Marketplace plugin vs personal skill vs project skill

The update column is what separates these three in practice. A personal skill changes when you change it. A project skill changes through code review. A marketplace plugin changes when a stranger pushes a commit and your machine pulls it, possibly in the background, possibly while you're doing something else. Which is an argument for caring who runs the catalog.

Install a plugin from a marketplace, step by step

1. Add the catalog.

/plugin marketplace add anthropics/claude-plugins-official

The source argument takes GitHub owner/repo shorthand, a full git URL like https://gitlab.com/company/plugins.git, a remote URL pointing at a marketplace.json, or a local directory path such as ./my-marketplace. Append @ref to the GitHub shorthand or #ref to a git URL to pin a branch or tag. A bare hostname without a scheme gets rejected, so gitlab.example.com/team/plugins won't work; type the https://.

2. Look at what the plugin ships before you install it.

/plugin details skill-creator@claude-plugins-official

It prints the plugin's component inventory: skills, agents, hooks, MCP servers, LSP servers, plus a projected token cost per session. A formatting helper that ships three hooks and an MCP server is telling you something about itself.

3. Install.

/plugin install skill-creator@claude-plugins-official

4. If it says the plugin doesn't exist, refresh the catalog.

The docs name this failure directly: if Claude Code reports the plugin is not found in any marketplace, your marketplace is either missing or outdated.

/plugin marketplace update claude-plugins-official

That refreshes a catalog you already added but which predates the plugin you're asking for. If you never added the catalog at all, run the step 1 command first. Then retry the install.

5. Reload so the current session sees it.

/reload-plugins

Installing a plugin doesn't retroactively hand its skills to the session you're sitting in. /reload-plugins does that. It also matters after a mid-session update, since hooks, MCP servers and LSP servers keep using the old version's path until you reload. Monitors need a full restart.

One more failure mode worth knowing: a plugin can specify "version" in its plugin.json, and Claude Code uses that value as the cache key for updates. If an author pushes new commits without bumping the version, /plugin update reports you're already at the latest version. You'd be right to find that annoying. It's also the reason a plugin that looks stale sometimes isn't, and vice versa.

What you accept when you trust a catalog

Adding a third-party marketplace is a standing grant, not a one-time download. You're saying that whatever this repo lists, now and in future commits, may run components on your machine.

So run this before you say yes:

/plugin details <name>

It prints the plugin's component inventory grouped as Skills, Agents, Hooks, MCP servers and LSP servers, alongside a projected token cost per session. The docs' own example output shows a plugin declaring two skills, zero agents, one hook, zero MCP servers. A "formatting helper" that ships three hooks and an MCP server is telling you something about itself.

The same command exists non-interactively as claude plugin details <name>, so you can inspect a plugin from a script.

The token cost figure is a second reason to look. Every plugin's skill descriptions load into every session whether or not anything fires. Install eight plugins because they looked interesting and you've quietly taxed every conversation you have.

The workspace trust dialog

Project-scope plugins get a stricter path, and the reasoning is sound. A skill folder with a .claude-plugin/plugin.json in it loads as a plugin named <name>@skills-dir, which means it can bundle agents, hooks and MCP servers. If that folder lives in a project's .claude/skills/, it only loads after you accept the workspace trust dialog for that directory.

The restrictions stack from there. MCP servers a project-scope plugin declares go through the same per-server approval as a project .mcp.json. LSP servers start only after you trust the workspace. Background monitors don't load at all. Personal-scope plugins in ~/.claude/skills/ get none of these guardrails, because Anthropic assumes you put them there yourself.

So the dialog is a real gate, and clicking through it on a repo you cloned five minutes ago is how people get burned. There's a related trap in allowed-tools: a skill checked into a project can grant itself broad tool access once you trust the folder. The docs say to review project skills before trusting a repository. Auditing a skill before you install it walks through what to read.

Verify the install command itself

Plenty of directories and blog posts tell you to run claude skill add. That command is fabricated. It appears in no Anthropic documentation, and it spread by getting copied between AI-written listings until it looked like consensus. We pulled that one apart separately in how to verify a Claude Code skill install command; the same reflex that catches a fake command catches a real marketplace with a hook you didn't want, which is also why author trust tiers are worth keeping.

Namespacing removes one worry

Plugin skills use a plugin-name:skill-name namespace, so they can't collide with your personal, project or enterprise skills. Install a plugin containing a code-review skill and your own code-review keeps working untouched.

Among the other levels, precedence runs enterprise over personal over project, and a skill at any of those levels overrides a bundled skill of the same name. Plugins sit outside that contest entirely. Nice design, and one less reason to be nervous about installing.

One oddity to file away: plugin skills handle symlinks differently from normal skills. A personal or project skill folder can be a symlink to somewhere else on disk and Claude Code follows it. Plugins have their own rules, documented under the plugins reference. If you're symlinking skill folders around your dev box, check that page before assuming the behavior carries over.

FAQ

Do I have to add a marketplace before every install?

No. Register a catalog once and it stays. You'll only touch marketplace add again for a new catalog, or when a plugin name refuses to resolve and you realize you never added its source. /plugin marketplace update is the one you'll type more often, since catalogs go stale as authors add plugins.

Can my company control which marketplaces people add?

Yes, through strictKnownMarketplaces in managed settings. Admins can allowlist sources, and the check runs before any network or filesystem operation, on add and on every install, update, refresh and auto-update. There's also blockedMarketplaces, and extraKnownMarketplaces to register approved catalogs so nobody has to add them by hand. A repo can put extraKnownMarketplaces in its .claude/settings.json and team members get prompted to install when they trust the folder.

Are marketplaces only for other people's plugins?

No, and the local path source is underrated. /plugin marketplace add ./my-marketplace points at a directory on your own disk, which makes it the natural way to test a plugin you're building before pushing anywhere. If you haven't built one yet, start with your first Claude Code skill and add the plugin manifest afterward.

Is any of this Claude-only?

The skills themselves aren't. Claude Code skills follow the Agent Skills open standard, so a SKILL.md is portable across tools that implement it. The plugin and marketplace layer around them is Claude Code's own, along with extensions like invocation control and subagent execution. Write a plain skill and it travels. Wrap it in a plugin and you've bought distribution at the cost of portability.

Troubleshooting quick reference