After seven levels, todo-api has a whole toolkit: the /add-endpoint and pr-review skills, the reviewer, tester and debugger subagents, hooks that check syntax and guard .env, a GitHub MCP configuration. But it's all scattered across one repo's .claude/ folder. What about a second repo? Copy each file by hand, and copy again after every change? This lesson introduces plugins, the way to package and install all of that as one unit, starting from the user's side: installing, choosing a scope, counting the cost, and deciding whether to trust one. Lesson 8.3 builds a plugin yourself.
What a plugin is
A plugin is a folder holding things you already know:
- Skills (level 3), run as
/<plugin>:<skill>, such as/commit-commands:commit; - Subagents (level 4);
- Hooks (level 6);
- MCP servers (level 5).
There's usually also a manifest, .claude-plugin/plugin.json, which names the plugin and can add a version and a description.
The docs are clear: all of these work without a plugin. Use a plugin when you want to package several things as one unit, install them in many projects, share them with a team, or publish versioned releases. A single skill just for you can stay in ~/.claude/skills/.
Marketplaces: a catalog, not a store
Plugins usually come from a marketplace: a repo or folder with a .claude-plugin/marketplace.json file that lists plugins and where to fetch each one. It's a catalog, not a place that hosts them. You install by name, in the form plugin@marketplace.
- The first time you start an interactive session, Claude Code adds the official marketplace,
claude-plugins-official. - Add other marketplaces with
/plugin marketplace addand a source: a GitHubowner/repo(add#v1.2.0to pin a version), a git URL, a local folder (starting with./), or a URL to amarketplace.jsonfile. - Add and install in one go:
/plugin install deploy-helper --marketplace your-org/plugins.
Marketplaces come in three tiers: official, community (such as claude-community) and third-party (everything else, including your coworker's or your company's). Official and community names are only accepted for marketplaces sourced from github.com/anthropics/, so nobody can impersonate them. But a marketplace's tier only tells you who maintains the catalog, not anything about each plugin in it.
Installing a plugin
In a session:
/plugin install commit-commands@claude-plugins-officialThis doesn't install right away. It opens the details page so you can look first:
- Will install: which skills, agents, hooks and MCP servers the plugin adds.
- Context cost (for official plugins): how many tokens it adds to every turn, and how many when a skill is invoked.
Then you choose a scope (next section) and install. Type / to see the new skills, such as /commit-commands:commit. /plugin on its own opens the Discover tab for browsing.
From the shell, without opening a session, for example in a new-machine setup script:
claude plugin install commit-commands@claude-plugins-official --scope localWhen we tried it in todo-api, the command printed "Successfully installed plugin … (scope: local)", wrote enabledPlugins into .claude/settings.local.json, and claude plugin list showed the plugin with "Scope: local".
Choosing a scope
| Scope | Enabled for | Written to |
|---|---|---|
| user | You, every project | ~/.claude/settings.json |
| project | Everyone in the repo | .claude/settings.json (committed) |
| local | You, this repo only | .claude/settings.local.json |
One detail that's often misunderstood: project scope writes to a committed file, so the plugin is enabled for the whole team, but it isn't downloaded to their machines. Each person still runs claude plugin install … --scope project once on their own machine. If the same plugin is set at several scopes, local beats project and project beats user.
Cost and trust
An enabled plugin is present in every session, even when you don't use it:
- Context: the names and descriptions of skills and agents Claude can invoke on its own sit in the context on every turn. The
plugin detailscommand gives the number:commit-commandsadds about 105 tokens per session, plus a few hundred tokens whenever a skill is invoked. - Processes: the plugin's MCP servers run alongside the session, and its hooks fire on their events.
- Permissions: the docs say it plainly: a plugin can run arbitrary code with your permissions. More importantly, permission rules and the sandbox only cover Claude's tool calls. A plugin's own hooks and servers run outside those layers.
So review before you install, whatever the marketplace:
claude plugin marketplace list: where the marketplace comes from.- Read the details page in
/plugin. - Read the source:
hooks/hooks.json(what each hook runs),.mcp.json, thebin/folder. - List the components without installing:It prints a "Component inventory" and the token cost. We ran it onTerminal
claude --plugin-dir <plugin folder> plugin details <name>commit-commands: 3 skills, 0 hooks, 0 MCP servers. A simple, low-risk plugin.
One more thing: auto-update can change the files you reviewed. It's on by default for the official marketplace and off for the others.
Managing plugins
/plugin, Installed tab: enable/disable (Space), update, uninstall.- From the shell:
claude plugin disable,enable,uninstall,update, with--scope. - Disable rather than uninstall when you just want to save context for a while.
- When a new version arrives Claude Code tells you; run
/reload-pluginsto use it right away. - Removing a marketplace uninstalls every plugin installed from it, and Claude Code lists them before asking you to confirm.
Plugins go to CI too: lesson 8.1's GitHub action takes plugin_marketplaces and plugins, then runs a skill with prompt: "/plugin:skill". The last lesson, 8.3, brings it all together: package todo-api's toolkit as a plugin, put it in a team marketplace, and install it in another repo with a single command.