Plugins

Lesson 5 left you with a skill in .claude/skills/. That works for you, in that one project. The moment a second person wants it, or you want it in a second repo, you are copying folders around and hoping nobody edits the wrong copy. Plugins are the answer to that. A plugin is a directory that packages skills, subagents, hooks, MCP servers, language servers, and a few other pieces into one unit that installs with a single command and updates as a single version.

What a plugin is, and what it is not

Claude Code has two ways to add your own behavior. The first is the standalone .claude/ directory you have been using since lesson 3: a skills/ folder, an agents/ folder, and a hooks block in settings.json. The second is a plugin: the same kinds of files, moved into their own directory, with an optional manifest at .claude-plugin/plugin.json that gives the bundle a name and a version.

The functional difference is small. The distribution difference is the whole point. A standalone setup lives in one project and travels only when you copy it. A plugin can be published to a marketplace, a catalog of plugins, and installed by anyone with one command. It carries a version, so people receive updates when you bump it. And it is self-contained, so a hook script it relies on ships inside the folder rather than assuming a path on your laptop.

One visible change: namespacing. A standalone skill runs as /hello. The same skill inside a plugin named my-first-plugin runs as /my-first-plugin:hello. The prefix is the name field from the manifest, and it exists so two plugins can both ship a skill called review without colliding. Subagents get the same treatment: a file at agents/reviewer.md becomes my-first-plugin:reviewer in the @-mention list.

A few rules about that tree. Only plugin.json goes inside .claude-plugin/. Every other folder sits at the plugin root; putting skills/ inside .claude-plugin/ is the single most common mistake in the docs' own troubleshooting list. There is also an older commands/ folder for flat Markdown files, which still loads but is the legacy format; use skills/ for anything new. And the plugin root is never ~/.claude/ itself. A .mcp.json dropped at ~/.claude/.mcp.json is ignored.

The manifest

The manifest is a small JSON file. The only required field is name, which must be kebab-case with no spaces, and if all your components sit in their default folders you can skip the manifest entirely. Claude Code will still find skills/, agents/, hooks/hooks.json, and the rest.

The fields you will actually use: description is what the plugin manager shows when someone browses. version is optional, but it controls updates: if you set it, people installing from a marketplace only receive a new copy when you change it. author is an object with a name and optional email. Past that, homepage, repository, license, and keywords are attribution and discovery. The manifest can also point components at custom paths (skills, agents, hooks, mcpServers, lspServers), but a new plugin should not need that. Here is a real one, the manifest of the superpowers plugin as installed on 2026-09-17:

{
  "name": "superpowers",
  "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
  "version": "6.3.0",
  "author": { "name": "Jesse Vincent", "email": "[email protected]" },
  "homepage": "https://github.com/obra/superpowers",
  "repository": "https://github.com/obra/superpowers",
  "license": "MIT",
  "keywords": ["skills", "tdd", "debugging", "collaboration", "best-practices", "workflows"]
}

Marketplaces, installing, and scopes

A marketplace is a catalog: a repository holding a .claude-plugin/marketplace.json file that lists plugins and where to fetch each one. Using one is two steps. First you add the marketplace, which registers the catalog but installs nothing. Then you install individual plugins from it.

As of September 2026 Anthropic runs two public marketplaces:

• claude-plugins-official, a curated set. Claude Code registers it automatically the first time you start it interactively. If that did not happen, for example because your first run was non-interactive, add it yourself with /plugin marketplace add anthropics/claude-plugins-official. Its catalog held 308 plugins on 2026-09-17, including language server plugins for TypeScript, Python, Go, and Rust, MCP bundles for GitHub, Linear, Vercel, Supabase, and Slack, and workflow plugins like commit-commands and security-guidance.
• claude-community, where third-party submissions land after Anthropic's automated validation and safety screening. You add it by hand: /plugin marketplace add anthropics/claude-plugins-community. Note the two names differ. The GitHub repo is claude-plugins-community; the marketplace name you install from is claude-community.

Anyone can host a marketplace too: a GitHub repo, another git host, a local folder, or a hosted JSON file. Teams use this for private plugins, and a project can list marketplaces in its .claude/settings.json so collaborators pick them up after trusting the folder.

Type /plugin in a session and a panel opens with tabs: Discover lists everything available across your marketplaces, Installed lets you enable, disable, or uninstall, Marketplaces manages the catalogs, and Errors shows anything that failed to load. Pick a plugin in Discover and the details pane shows a Context cost estimate, meaning how many tokens the plugin adds to every turn, plus a Will install list of its commands, agents, skills, hooks, and MCP and LSP servers. Read that list. It is the plugin telling you what it is about to do.

You can skip the panel and install by name with the marketplace after an @ sign:

/plugin install superpowers@claude-plugins-official

Either way you choose a scope, the same three you met for settings. User installs for you in every project, recorded in ~/.claude/settings.json. Project installs for everyone on the repo by writing to .claude/settings.json, which goes into git. Local installs for you in this repo only via .claude/settings.local.json. There is a fourth, managed, that an administrator sets and you cannot change. From a plain shell the equivalent is claude plugin install name@marketplace, which defaults to user scope unless you pass --scope project or --scope local.

Installed plugins are copied to ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/. That path matters later, because it is where you go to read what you installed.

After a change, Claude Code needs to reload. When you close the /plugin panel it runs /reload-plugins for you. If the reload would throw away the prompt cache, which means the next request re-reads the whole conversation at full price, it warns and waits; run /reload-plugins --force to apply anyway. Changes made outside the panel, such as a claude plugin install in another terminal or an edit to a plugin you are developing, need a manual /reload-plugins. Disable without removing with /plugin disable name@marketplace; remove entirely with /plugin uninstall name@marketplace.

Building one

The quickest start is claude plugin init my-tool. Note where it puts things: it scaffolds ~/.claude/skills/my-tool/ with a manifest and a starter SKILL.md, and on your next session it loads automatically as my-tool@skills-dir with no marketplace and no install step. A plugin living in your skills directory can carry agents, hooks, MCP, and LSP config just like any other. Edits to a SKILL.md show up immediately; edits to hooks, agents, or server config need /reload-plugins.

If you would rather keep the plugin in its own folder, say inside the project you are sharing it from, point Claude Code at it when you launch:

claude --plugin-dir ./tint-tools

That loads it for the session only. Repeat the flag to load several, or pass a folder that contains several plugins and each subfolder with a manifest loads separately. If a --plugin-dir plugin has the same name as one you installed from a marketplace, the local copy wins for that session, which is exactly what you want when testing a fix to a plugin you already use. Make a change, run /reload-plugins, try the skill again.

Before sharing, validate. claude plugin validate ./tint-tools checks the manifest against the schema, flags misspelled or unknown fields as warnings, and reports agent files whose frontmatter will not parse. Warnings do not fail the check; add --strict to make them fail, which catches a typo like descripton before your teammates do. The community marketplace runs the same validation on every submission.

Converting an existing .claude/ setup is mostly copying. Make the plugin directory next to .claude/, write a manifest, then copy .claude/skills, .claude/agents, and, if you still have one, .claude/commands to the plugin root. Hooks move from the hooks block of settings.json into hooks/hooks.json; the format inside is identical, so it is a cut and paste. Test with --plugin-dir. Then remove the originals from .claude/, and here is the part that trips people: a project or user .claude/agents/ definition overrides a plugin agent with the same name, so the plugin version does nothing until the original is gone. Skills are namespaced, so /write-quote and /tint-tools:write-quote would both keep working, which is confusing rather than broken.

Trust: read before you install

A plugin is not a document. It is code that runs with your user permissions. A hook fires shell commands on your machine at the moments it chooses, including every session start. An MCP server is a process that starts when the plugin is enabled. A bin/ folder puts executables on Claude's PATH. Anthropic's own warning is blunt: it does not control what a plugin contains and cannot verify that a plugin works as intended. The official catalog is curated and the community one is screened, but curation is not an audit of every version.

So the habit is: open the folder and read it. The install path is predictable, the files are plain text, and a plugin small enough to be useful is small enough to read in ten minutes. Look at hooks/hooks.json first, since that is what runs without being asked. Then .mcp.json, since that is what talks to the network, and check which environment variables it reads. Then the skills, which are just instructions. If a plugin ships a hook script you cannot follow, do not enable it. The same rule applies to a marketplace: adding one clones a repository onto your machine, and removing a marketplace uninstalls everything you took from it.

Try this yourself

Install one plugin from the official marketplace, run one of its skills, then read what you installed. superpowers is a good first pick: it is listed in claude-plugins-official, it is third-party (Jesse Vincent, MIT license), and its one hook is a clean example of what to look for.

# inside a Claude Code session
/plugin install superpowers@claude-plugins-official
# choose User scope; if the summary says to reload, it runs /reload-plugins for you

/superpowers:brainstorming
# describe a small feature you want to build and answer its questions

# in a normal terminal
ls ~/.claude/plugins/cache/claude-plugins-official/superpowers/
# open the version folder you see there, for example 6.3.0
cat ~/.claude/plugins/cache/claude-plugins-official/superpowers/*/.claude-plugin/plugin.json
cat ~/.claude/plugins/cache/claude-plugins-official/superpowers/*/hooks/hooks.json
ls ~/.claude/plugins/cache/claude-plugins-official/superpowers/*/skills/

You should find the manifest shown earlier, fourteen skill folders, and a hooks.json with a single SessionStart entry that runs a script from inside the plugin on startup, clear, and compact. Open that script too. Now you know exactly what the plugin does on your machine, which is the standard to hold every other plugin to. Next lesson: MCP servers, the piece of this tree that reaches outside your computer.