Claude Code plugins: what they are, how to install them, how to make one

What is a Claude Code plugin?

A Claude Code plugin is a folder of components that Claude Code installs and loads as one unit. The plugins overview puts it simply: "a directory of skills, agents, hooks, MCP servers, or other components."

Every one of those components already works on its own. You can drop a skill into ~/.claude/skills/ without any plugin. What a plugin adds is packaging: one install command gives you a whole setup someone else built, with updates from its marketplace. If you build one, you can share your setup with teammates, use it across projects, and ship versioned releases.

What a plugin can bundle

A plugin usually has a manifest at .claude-plugin/plugin.json, then one folder or file per component type at the plugin root:

The components reference also lists output styles, color themes, monitors and default settings. Most plugins use only one or two of these. If you are new to the pieces, see the guides on skills, hooks, subagents and MCP.

Plugin skills and agents get the plugin's name as a prefix. A review skill in a plugin called my-plugin runs as /my-plugin:review, so two plugins can each ship a review skill without clashing.

What is a plugin marketplace?

A plugin marketplace is, in the docs' words, "a catalog that lists plugins and where to fetch each one." You don't download plugins one by one from random places; you add a marketplace. It is a repo or folder with a .claude-plugin/marketplace.json file. It's a catalog, not a hosted store.

Claude Code adds Anthropic's official marketplace, claude-plugins-official, the first time you start an interactive terminal session. To add another one, run /plugin marketplace add with its source:

# a GitHub repo
/plugin marketplace add your-org/plugins

# pin a tag
/plugin marketplace add your-org/plugins#v1.2.0

# any git host, a local folder, or a hosted marketplace.json
/plugin marketplace add https://gitlab.example.com/your-group/your-marketplace.git
/plugin marketplace add ./my-marketplace
/plugin marketplace add https://example.com/marketplace.json

Private repos work as long as your Git credentials can already reach them. Claude Code doesn't prompt for a password.

Marketplace names tell you who runs them. Claude Code accepts Anthropic's official and community marketplace names only from repos under github.com/anthropics/. Anything else is third-party, including your own company's.

How do you install a plugin?

You install a plugin by running /plugin inside Claude Code, then picking the plugin and a scope:

1. Start Claude Code in your project with claude.

2. Run /plugin. The Discover tab lists plugins from your marketplaces. Type to search and press Enter to open one. Or name it directly:

   /plugin install commit-commands@claude-plugins-official
   

3. Read the details pane. It shows what the plugin will install: commands, agents, skills, hooks, and MCP and LSP servers. Official marketplace plugins also show a context cost estimate when you open them by name, as above, or from the Marketplaces tab.

4. Pick a scope:

   • User scope: you get it in every project on this computer.
   • Project scope: enabled for everyone in the repo through the committed .claude/settings.json. Each teammate still installs it on their own machine.
   • Local scope: you get it in this repo only.

5. Check it worked. Type / and look for the plugin's skills under its name, such as /commit-commands:commit.

From your shell, without opening a session:

claude plugin install commit-commands@claude-plugins-official
claude plugin list
claude plugin disable commit-commands@claude-plugins-official

The Installed tab in /plugin is where you enable, disable, update or uninstall later. Plugins from the official marketplace update automatically by default; third-party marketplaces don't unless you turn auto-update on.

What an installed plugin costs you

An enabled plugin is part of every session, not just the ones where you use it. The docs list three effects worth knowing:

• Context. The name and description of every skill and agent Claude can call on its own sits in context every turn. Full instructions load only when used.
• Processes. Its MCP servers run alongside each session and its hooks fire on their events.
• Permissions. "What the plugin runs, it runs as you."

So install what you use, and disable the rest. claude plugin details <name> in your shell shows how many tokens a plugin adds to every session.

Make a simple plugin

Here is the smallest useful plugin: one skill. It follows the steps in Create a plugin.

1. Create the folders:

   mkdir -p release-tools/.claude-plugin
   mkdir -p release-tools/skills/release-notes
   

2. Write the manifest at release-tools/.claude-plugin/plugin.json. Only name is required, and it becomes the prefix for every skill:

   {
     "name": "release-tools",
     "description": "Release notes and changelog helpers",
     "version": "1.0.0",
     "author": { "name": "Your Name" }
   }
   

3. Add the skill at release-tools/skills/release-notes/SKILL.md:

   ---
   name: release-notes
   description: Draft release notes from merged pull requests, grouped as
     New, Improved and Fixed. Use when the user asks for release notes.
   ---
   
   1. List the pull requests merged since the last tag.
   2. Group them as New, Improved and Fixed.
   3. Write one plain line per change, from the user's point of view.
   

4. Validate it, then load it for one session:

   claude plugin validate ./release-tools
   claude --plugin-dir ./release-tools
   

5. In the session, run /release-tools:release-notes, or just ask for release notes and let Claude pick the skill. After editing files, run /reload-plugins to load your changes.

The most common mistake: only plugin.json goes inside .claude-plugin/. A skills/ folder placed in there doesn't load. Keep component folders at the plugin root.

If you already have skills, agents or hooks under a project's .claude/ folder, you can copy them into a plugin as they are. Hooks move from your settings file into hooks/hooks.json in the same shape.

To share the plugin, send someone the folder, list it in your own marketplace so teammates can install it by name, or submit it to Anthropic's directory.

Plugins vs skills

A good rule: start with plain skills. When you find yourself shipping several skills plus a hook or an MCP server to the same group of people, wrap them in a plugin.

Keep the skills portable

Plugins are great for distribution inside Claude Code, but the skills inside them are the part you will reuse everywhere. Kipt keeps your prompts and skills in your own private GitHub repo. Save a prompt, use Promote to skill to turn it into a SKILL.md, and install your whole library into Claude Code or Codex with npx skills add https://github.com/<you>/<repo>.git. To start from a single prompt, try the free SKILL.md generator, then drop the result into a plugin's skills/ folder.