Plugins add skills, agents, hooks, and MCP servers to Claude Code without you building any of them. The Claude Code plugin marketplace is where you find them. The confusing part is that "marketplace" and "plugin" are two different things: a marketplace is a catalog, and each plugin in it is a separate item. Install commands also behave differently inside a session than in your terminal, and they change depending on where the plugin comes from.
This guide shows how to find plugins, install them with the right scope, add a custom marketplace, use the --marketplace option, verify the result, manage plugins afterwards, and fix the errors people hit most.
What Is the Claude Code Plugin Marketplace?
A plugin is a package that extends Claude Code. It can contain skills, agents, hooks, and MCP servers. A marketplace is a catalog that lists plugins and tells Claude Code where to fetch them. Claude Code has to know about a marketplace before you can install anything from it.
You will meet three kinds of marketplace:
The official marketplace, named claude-plugins-official. Anthropic maintains it, and Claude Code registers it automatically the first time you start an interactive terminal session.
Anthropic's community marketplace, which you add yourself. Its registered name is claude-community, even though its repository is called claude-plugins-community.
Custom marketplaces, which anyone can publish in a Git repository, at a URL, or in a local folder.
A marketplace name only tells you who publishes the catalog. It does not tell you what each plugin does, so review plugins from every marketplace before installing.
Before You Install a Claude Code Plugin
Claude Code installed and launched. Follow Anthropic's official setup instructions for your platform, then run claude in your project folder.
Your version number. Some flags depend on the version. Check yours from your terminal:
claude --version
Terminal commands versus session commands. This is the most common source of confusion.
/plugin ... is a slash command you type inside a running Claude Code session. Typed at a normal shell prompt, it fails with an error such as zsh: no such file or directory: /plugin.
claude plugin ... is a shell command you run in your terminal, with no session needed. claude plugins works as an alias.
In non-interactive runs such as claude -p, /plugin is not available, so use the claude plugin shell commands there.
A trust check. A plugin you install can execute code on your machine with your user privileges. Read its details before you confirm (more in the security section).
How to Find Plugins in the Official Marketplace
Start Claude Code with Claude.
Type /plugin. The panel opens on the Discover tab, which lists plugins from all your marketplaces.
Type to search, then press Enter on a plugin to open its details.
The details pane is where you decide whether a plugin fits your workflow. It shows the description and can also show:
Will install: the commands, agents, skills, hooks, and MCP and LSP servers the plugin adds.
Last updated: shown for plugins in the official marketplace.
Context cost: for official-marketplace plugins, estimates of the tokens the plugin adds to every turn and when its skills or agents are invoked. This appears when you open the plugin by naming its marketplace or from the Marketplaces tab, but not from the Discover list.
Plugins from custom marketplaces may show "Components will be discovered at installation" instead, so you cannot always preview their contents.
If Discover is empty, or you see "No marketplaces configured," the official marketplace is not registered yet. Add it with:
/plugin marketplace add anthropics/claude-plugins-official
Other places to look: plugins you turn on in your claude.ai account can sync into Claude Code and appear with the @synced suffix.
How to Install a Claude Code Plugin
The command follows one pattern:
/plugin install @
/plugin install is the session command.
is the plugin's name in the catalog.
@ says which catalog it comes from. This is the marketplace's registered name, not its repository or URL.
Here is an example from the official marketplace. It installs commit-commands, which adds commands for committing, pushing, and opening pull requests. Run it inside a Claude Code session:
/plugin install commit-commands@claude-plugins-official
In a session this does not install immediately. It opens the plugin's details so you can review it and choose a scope. After you pick one, Claude Code installs the plugin and any dependencies it declares, then prints a summary.
Choosing an Installation Scope
Scope
Menu option
Who gets it
Recorded in
User
Install for you
You, in every project on this machine
~/.claude/settings.json
Project
Install for all collaborators on this repository
Everyone who works in this repository
.claude/settings.json (you commit it)
Local
Install for you, in this repo only
You, in this repository only
.claude/settings.local.json
If the same plugin is set at several scopes, local overrides project, and project overrides user.
Project scope has a catch. Committing the settings entry enables the plugin for collaborators but does not download it to their machines. Each collaborator runs this once:
claude plugin install @ --scope project
Installing from Your Terminal Instead
claude plugin install commit-commands@claude-plugins-official --scope project
Without --scope, the shell command installs at user scope. Valid values are user, project, and local. On success it prints Successfully installed plugin: commit-commands@claude-plugins-official (scope: project).
One caveat: on a machine where nobody has opened an interactive session yet, the official marketplace is not registered, because shell commands never register it. Run claude plugin marketplace add anthropics/claude-plugins-official first.
How to Install a Plugin from a Custom Marketplace
Many plugins are not in the official marketplace. A coworker's plugin or an open-source project's plugin lives in its own catalog. Claude Code has no global index to look marketplace names up in, so an install line like name@some-marketplace will not work until you have added that marketplace.
The values below are placeholders (your-org/plugins, deploy-helper). They do not refer to a real marketplace or plugin, so replace them with your own.
Add the marketplace (in a session):
/plugin marketplace add your-org/pluginsThe source can be a GitHub owner/repo (add #ref to pin a branch or tag), a full git URL, a local path starting with ./ or ../, or an https:// link to a hosted marketplace.json. Include the https:// prefix on URLs: a bare gitlab.example.com/group/repo is read as GitHub shorthand and fails.
Identify the marketplace name. The success message reads Successfully added marketplace: . That name comes from the marketplace's own manifest and may differ from the repository name. You can also list names:
/plugin marketplace list
Install the plugin using that registered name:
/plugin install deploy-helper@
Confirm the scope in the details pane.
Verify that the plugin is available (see the verification section).
The new marketplace appears on the Discover tab the next time you open /plugin, with no reload needed. Auto-update is off by default for community and third-party marketplaces, so refresh them yourself with /plugin marketplace update .
How to Use the Claude Code --marketplace Option
The --marketplace option combines two steps: it registers a marketplace you have not added yet and starts the plugin install. You pass the marketplace source, and you give the plugin name by itself, with no @marketplace suffix.
In a session (requires Claude Code v2.1.275 or later):
/plugin install deploy-helper --marketplace your-org/plugins
Claude Code shows the source it resolved and asks you to confirm before adding the marketplace. Then the plugin's details open and you choose a scope. If the source matches a marketplace you have already added, it skips the confirmation. In a session, the source cannot contain spaces.
From your shell (requires Claude Code v2.1.292 or later):
claude plugin install deploy-helper --marketplace your-org/plugins
The shell version adds the marketplace without a confirmation step, so be sure of the source before you run it. A new marketplace added this way is declared in your user settings even if you pass --scope project. A marketplace you already added from the same source is reused.
The two forms have different minimum versions, so do not assume one number covers both. Run claude plugin install --help to confirm your build supports the flag.
Source versus name. In --marketplace your-org/plugins, the value is a source: where to fetch the catalog. In deploy-helper@marketplace-name, the part after the @ is the registered name: what the catalog calls itself. They often differ.
Two limitations to know about:
/plugin install your-org/plugins (a source with no plugin name and no --marketplace) installs nothing and reports a "marketplace not found" error.
If the catalog at your source has the same name as a marketplace you already added from a different source, Claude Code keeps the existing one and installs nothing. Remove the old marketplace first if you want the new source.
Claude Code Plugin Installation Examples
Replace the placeholders in angle brackets with your own values.
Goal
Command
Where to run it
Browse plugins
/plugin
Claude Code session
Install from a registered marketplace
/plugin install @
Claude Code session
Install at project scope from the terminal
claude plugin install @ --scope project
System shell
Add a marketplace
/plugin marketplace add
Claude Code session
Add a marketplace from the terminal
claude plugin marketplace add
System shell
Add a marketplace and install in one step
/plugin install --marketplace
Claude Code session
Same, from the terminal
claude plugin install --marketplace
System shell
List registered marketplaces
/plugin marketplace list
Claude Code session
Refresh a marketplace listing
/plugin marketplace update
Claude Code session
List installed plugins
/plugin list (v2.1.163+)
Claude Code session
List installed plugins with status
claude plugin list
System shell
Apply pending plugin changes
/reload-plugins
Claude Code session
How to Verify That a Plugin Is Installed
Start with the install summary. Its last sentence tells you the plugin's state:
"Plugin is now active." No reload is needed.
"Run /reload-plugins to apply." Claude Code runs the reload for you when the panel closes. If the reload would invalidate the prompt cache, it warns and leaves the plugin pending. Run /reload-plugins --force to activate it anyway, which costs one uncached request.
"The plugin couldn't be loaded." Open the Errors tab in /plugin for the reason.
Active, but a bundled MCP server needs configuration. Open the plugin on the Installed tab and choose Configure.
So not every plugin needs a reload. The summary tells you. Plugins installed from your shell load the next time you start Claude Code, or when you run /reload-plugins in an open session.
Then confirm the plugin in any of these ways:
Type / and look for the plugin's skills in the form /:. For commit-commands, that is /commit-commands:commit. The namespace prevents two plugins from colliding on similar command names.
Open the Installed tab in /plugin, which lists each plugin with its scope.
Run claude plugin list in your shell. It prints Version, Scope, and Status for each plugin.
How to Manage Plugins After Installing
Disable or enable: On the Installed tab, press Space on a plugin. From your shell, use claude plugin disable @ or claude plugin enable @.
Uninstall: Use /plugin uninstall in a session, or claude plugin uninstall @ --scope project in your shell. If the project's shared settings enable the plugin, Claude Code asks whether to disable it only for you or uninstall it for everyone.
Update: Run claude plugin update @. No single command updates every plugin. To update everything from one marketplace, open the Marketplaces tab in /plugin, select it, and choose Update marketplace. A running session keeps the versions it already loaded, so run /reload-plugins or start a new session.
Remove a marketplace: This also uninstalls every plugin you installed from it. To refresh a marketplace without losing its plugins, use update instead of remove.
Check the cost: Run claude plugin details in your shell. The Always-on line shows how many tokens the plugin adds to every session.
Common Claude Code Plugin Marketplace Errors and Fixes
These come from Anthropic's troubleshooting guidance. Exact messages vary by version, so treat the fixes as starting points rather than guarantees.
Problem: Marketplace "claude-plugins-official" not found, or the same message for another marketplace name.
Likely cause: The marketplace is not registered on this machine. For the official one, that happens if you have only used the VS Code extension, or if a policy or environment setting blocks auto-registration. For other names, the install line you received does not say where the marketplace is hosted.
Fix: Run /plugin marketplace add anthropics/claude-plugins-official for the official marketplace. For any other, ask whoever sent the line for the marketplace's source, add it with /plugin marketplace add
Problem: Plugin "" not found in marketplace "".
Likely cause: A misspelled plugin name, or a local copy of the catalog that is out of date.
Fix: Copy the name from the Discover tab. If the message includes a refresh hint, run /plugin marketplace update and install again.
Problem: Invalid marketplace source format.
Likely cause: The source is not in an accepted form. A bare name such as claude-plugins-official or a bare hostname does not qualify.
Fix: Use owner/repo, a full https:// URL, user@host:path, or a path beginning with ./, ../, /, or ~.
Problem: SSH authentication failed or HTTPS authentication failed when adding or updating a marketplace.
Likely cause: Claude Code runs git with interactive prompts disabled, so only credentials that already work non-interactively succeed. A misspelled repository or one you cannot see can produce the same message.
Fix: Run git ls-remote in your terminal to confirm the repository exists and you have access. For SSH, ssh -T git@ must succeed without a passphrase prompt. For GitHub over HTTPS, run gh auth login and gh auth setup-git. Retry once git ls-remote works without prompting.
Problem: The plugin appears installed but does not work.
Likely cause: It may need a reload, may have load errors, may be disabled, or may not contain what you expected.
Fix: Open /plugin, check Installed for enabled status, and read the Errors tab. Run /reload-plugins if you installed during this session. Check the plugin's details pane to see what it actually adds.
Problem: A code intelligence (language server) plugin is installed, but the Errors tab shows Executable not found in $PATH.
Likely cause: These plugins connect to a language server binary that you install separately. The plugin alone is not enough.
Fix: Install the language server binary, confirm it is on the PATH of the terminal you start claude from (for example with which typescript-language-server), then start a new session.
Problem: error: unknown command 'add', unknown option '--project', or Unknown command: /install.
Likely cause: Those spellings do not exist. Some older tutorials still use them.
Fix: Use claude plugin marketplace add
Problem: A plugin is "enabled in project settings but isn't installed here," or you are unsure which scope applies.
Likely cause: A repository's settings can enable a plugin for everyone, but they do not download it. Separately, when a plugin is set at several scopes, the most specific one wins.
Fix: Run claude plugin install @ --scope project, then /reload-plugins. Run claude plugin list to see each plugin's scope.
Plugin Security and Best Practices
Anthropic's documentation states that an installed plugin can execute arbitrary code on your machine with your user privileges. That is a reason for a quick review habit, not for alarm.
Check source and maintainer. A marketplace name tells you who publishes the catalog, not what every plugin in it does. Prefer plugins from maintainers you recognize.
Read "Will install" before you confirm. Hooks and MCP servers deserve the closest look. Hooks run commands in response to events, and MCP servers give Claude access to external tools and data. Their processes are separate from Claude's own tool calls, so a plugin's description is not a substitute for reading its hook and MCP configuration.
Be careful with unfamiliar repositories. This applies to --marketplace especially, because the shell form adds the marketplace without asking.
Remember that updates can change what you reviewed. When auto-update is on for a marketplace, Claude Code updates its plugins in the background. It is on by default for the official marketplace and off by default for third-party ones. For a third-party plugin you audited carefully, leave auto-update off and update by hand.
Agree on project-level plugins as a team. Project scope puts the plugin in a committed settings file, so everyone gets the same setup. Decide together what goes there, and keep personal experiments at user or local scope.
To remove a plugin you no longer trust, uninstall it. If you do not trust the marketplace either, remove the marketplace too.
Frequently Asked Questions
What is the Claude Code plugin marketplace?
A catalog of plugins that Claude Code can install from. The official one is claude-plugins-official, and you can add others from Git repositories, URLs, or local paths.
How do I install a Claude Code plugin?
Run /plugin install @ in a session, choose a scope, and read the install summary. From your shell, use claude plugin install @.
How do I install a plugin from a custom marketplace?
Add the marketplace with /plugin marketplace add
What does the Claude Code --marketplace option do?
It registers a marketplace you have not added and starts the plugin install in one command. It requires v2.1.275 or later in a session and v2.1.292 or later from the shell.
Do I need to add the official marketplace manually?
Usually not. Claude Code registers it on your first interactive terminal session. You may need to add it yourself if you have only used the VS Code extension, if a policy blocks auto-registration, or on a fresh machine where you install from the shell.
How do I list installed Claude Code plugins?
Use /plugin list in a session (v2.1.163 or later), open the Installed tab in /plugin, or run claude plugin list in your shell.
Why is my plugin not appearing after installation?
Check the Installed and Errors tabs in /plugin, and run /reload-plugins if you installed during this session. Open the plugin's details to confirm what it provides.
Can I share a plugin installation with my team?
Yes, with project scope. It records the plugin in .claude/settings.json, which you commit. Collaborators still run claude plugin install @ --scope project once to download it.
How do I update Claude Code plugins?
Run claude plugin update @, or use Update marketplace on the Marketplaces tab. No single command updates every plugin.
How do I uninstall a plugin?
Use /plugin uninstall in a session, or claude plugin uninstall @ in your shell. Add --scope to target one scope.
Conclusion
The simplest workflow is short. Open Claude Code, run /plugin to browse the Claude Code plugin marketplace, review the plugin's details, and install it with /plugin install @. If the plugin lives in another marketplace, add that marketplace first, or use --marketplace to combine both steps. Before you confirm any install, check who published the plugin and choose the scope that matches who should have it.
Want more practical Claude Code walkthroughs? Keep exploring the guides on HustleToAI.
Top comments (0)