Claude Plugins Explained: What They Are and How They Differ from Skills

You typed /plugin once, saw a tabbed menu with words like "Discover" and "Marketplaces," and quietly closed it. Then you kept using skills the way you always had: a folder with a SKILL.md in .claude/skills/, working fine. So what is the /plugin thing for, and why does it look like an app store bolted onto your terminal?

Claude plugins are bundles. One plugin can carry several skills, plus slash commands, agents, hooks, MCP servers, and even language servers, all installed and versioned as a single unit. A skill is just one of the things a plugin can contain. That is the whole distinction in a sentence. The rest of this piece is the detail that makes the sentence useful: what goes in the bundle, where the bundles come from, how you install and manage them, and when you actually want a plugin instead of a loose skill.

What a Claude plugin actually is

A plugin is a directory with a manifest. The manifest lives at .claude-plugin/plugin.json, where it declares the plugin's name, an optional version, and a description. Everything else sits in sibling directories at the plugin root. The Claude Code plugins docs lay out the structure, and the one rule people break is putting component folders inside .claude-plugin/. Only the manifest goes there. The components live one level up.

Here is what a plugin can bundle, drawn straight from the structure table in the docs:

• skills/ holds Agent Skills as <name>/SKILL.md directories, the same format you already write by hand.
• commands/ holds flat Markdown slash commands (the docs steer new plugins toward skills/ instead).
• agents/ holds custom subagent definitions.
• hooks/hooks.json holds event handlers that fire on things like PostToolUse.
• .mcp.json holds MCP server configurations, so a plugin can ship a pre-wired connection to GitHub, Linear, Postgres, whatever.
• .lsp.json holds language-server config for real-time code intelligence.
• monitors/, bin/, and a plugin-level settings.json round it out, covering background watchers, executables added to PATH, and default settings applied while the plugin is on.

So a plugin is a delivery container, and the payloads vary wildly. The commit-commands plugin from the official marketplace gives you git skills like /commit-commands:commit that stage changes and write a message. The github plugin instead bundles a pre-configured MCP server, so Claude can talk to the GitHub API without you editing a single config file. Same packaging, very different cargo.

Two things about plugin skills surprise people coming from loose skills. First, skill names are namespaced by the plugin: a hello skill inside a plugin named my-first-plugin becomes /my-first-plugin:hello, never just /hello. The namespace prevents two plugins from fighting over the same command name. Second, plugins are copied into a cache at ~/.claude/plugins/cache when installed, so a plugin can't reach files outside its own directory with paths like ../shared-utils. The bundle has to be self-contained.

Plugins versus skills, stated plainly

A skill is a single capability: a SKILL.md, optionally with a scripts/ or references/ folder beside it. It teaches Claude one workflow, and that is all it does. If you have never packaged one, the no-code path in build a Claude skill gets you a valid SKILL.md without hand-writing YAML.

Wrap one or more of those in metadata and a version and you have a plugin. The Claude Code docs draw the line by use case. Standalone config in .claude/ is for personal workflows, project-specific tweaks, and quick experiments, and you get short names like /deploy. Plugins are for sharing with a team or community, reusing the same set across many projects, and shipping versioned releases, and you accept namespaced names like /my-plugin:deploy as the cost.

The practical read: if it is just you, on one machine, a loose skill in .claude/skills/ is less ceremony, so stay there. But the moment you want four teammates to get the same three skills plus a hook plus an MCP server, in one install, that updates when you push, you want a plugin. The docs even suggest starting standalone and converting to a plugin once you are ready to share, which copies your commands/, agents/, and skills/ into the plugin directory and moves hooks from settings.json into hooks/hooks.json.

Skills are also only one ingredient a plugin can carry, alongside subagents, slash commands, and the rest. Picking which ingredient fits a given job is its own decision, and the matrix in skills vs subagents vs slash commands vs plugins walks that choice. If your specific question is whether a capability should ship as a folder or as a running server, SKILL.md vs MCP server settles it. I won't re-litigate either here.

The Claude plugin marketplace

Think of a marketplace as a catalog: a marketplace.json file, usually in a GitHub repo, that lists plugins and where to fetch each one from. Adding a marketplace registers that catalog so you can browse it, but it installs nothing on its own. The mental model the docs use is an app store. Adding the store lets you browse; downloading individual apps is a separate step.

There are a few marketplaces worth knowing by name. The official one, claude-plugins-official, is curated by Anthropic and ships available in every Claude Code install. You browse it from the Discover tab of /plugin, or at claude.com/plugins, and install from it like so:

/plugin install github@claude-plugins-official

Per the discover-plugins docs, the official catalog includes code-intelligence LSP plugins (Python's pyright-lsp, Rust's rust-analyzer-lsp, and so on), external-integration plugins that bundle MCP servers (github, gitlab, linear, notion, figma, slack, sentry, and more), a security-guidance plugin that reviews each change for vulnerabilities, and workflow toolkits like commit-commands, pr-review-toolkit, and plugin-dev.

Then there is the community marketplace, anthropics/claude-plugins-community, which holds third-party plugins that passed Anthropic's automated validation and safety screening, each pinned to a specific commit SHA. You add it by hand and install with the claude-community name:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install <plugin-name>@claude-community

You can point a marketplace at any GitHub repo (owner/repo), any git URL, a local path, or a remote marketplace.json. So "best Claude plugins" and "Claude plugins github" both resolve to the same mechanic underneath: a marketplace is just a git repo someone published, and you trust it the way you trust any repo you clone. Which brings up the warning the docs print in bold. I will repeat it, because it matters: plugins can run arbitrary code on your machine with your privileges. Anthropic does not vet what is inside third-party plugins. Add marketplaces and install plugins only from sources you trust. Organizations can hard-restrict which marketplaces are allowed with the strictKnownMarketplaces managed setting, down to an empty array for total lockdown.

Installing and managing plugins

The flow has two steps. Add the catalog, install the plugin. Here is the full loop with the community demo marketplace:

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

After installing, run /reload-plugins to activate it without restarting Claude Code. The skill then answers to its namespaced name, /commit-commands:commit. That /reload-plugins step trips people up; the plugin is installed but dormant until you reload or restart.

Installation has a scope, the same three you know from settings. User scope installs the plugin for you across every project. Project scope writes it into .claude/settings.json so every collaborator on the repo gets it. Local scope keeps it to you in this one repo. Pick scope from the interactive UI by pressing Enter on a plugin in the Discover tab, or pass --scope project on the CLI. Recent Claude Code versions also show a context-cost estimate and a "Will install" breakdown of exactly which commands, agents, skills, hooks, and MCP and LSP servers a plugin adds, which is worth reading before you accept a heavy MCP-bundling plugin into every turn.

Managing what you have installed happens in the Installed tab of /plugin, or with direct commands:

/plugin disable plugin-name@marketplace-name
/plugin enable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

Disable turns a plugin off without removing it. Uninstall removes it. And a sharp edge worth memorizing: removing a marketplace uninstalls every plugin you got from it, so if you only want fresh listings use /plugin marketplace update, not remove.

Lifecycle: versions and updates

Versioning is where plugins earn their keep over loose folders. It is also where one footgun lives. A plugin's version comes from the first of these that is set: version in plugin.json, then version in the marketplace entry, then the git commit SHA of the source. Pin a version string and forget to bump it, and pushing new commits does nothing for existing users, because Claude Code sees the same version and keeps the cached copy. Either bump the field on every release, or omit it entirely and let each commit SHA count as a new version. For an actively developed internal plugin, omitting version is the simpler path.

Updates can run on their own. Official Anthropic marketplaces have auto-update on by default; third-party and local ones default to off, and you toggle them per marketplace in the Marketplaces tab. When an auto-update pulls a new version, Claude Code nudges you to run /reload-plugins. If you want to manage Claude Code's own updates by hand but still receive plugin updates, the docs cover the DISABLE_AUTOUPDATER plus FORCE_AUTOUPDATE_PLUGINS=1 combination.

So which do you reach for

Start with a loose skill. It is a folder and a markdown file, it works on your machine today, and it carries zero of the install ceremony above. When you need the same set of capabilities to land on other people's machines in one move, versioned, with a hook or an MCP server riding along, wrap it in a plugin and put that plugin in a marketplace.

The part that stays manual either way is writing the SKILL.md that does the actual work. A plugin packages skills; it does not author them. If the bottleneck is turning what you know into a clean SKILL.md in the first place, Knack runs a short interview and hands you a valid one, which you can then drop into a plugin and ship. The container is easy. The contents are the job.