Claude Code plugins: install, build and publish

Who this is for

This guide is for developers who already use Claude Code and want to package their skills, agents, hooks or MCP servers, or want to install a setup someone else has built. After reading it you should be able to decide whether a plugin is the right tool, install one from a marketplace, build a small plugin with one skill, validate and load it, and choose how to share it.

What a plugin is, and when to use one

A Claude Code plugin is a directory of components that Claude Code installs and loads as one unit. Those components can be skills, agents, hooks, MCP servers and other items. Most plugins come from a marketplace^[1].

Skills, subagents, hooks and MCP servers all work without a plugin. A plugin makes sense when you want several of them packaged together. It also makes sense when you want someone else's setup installed with one command, with updates from its marketplace, or when you want to give your own setup to teammates^[1][2].

The manifest, a JSON file at .claude-plugin/plugin.json, gives the plugin its name and can add a version, a description and other metadata^[1]. A skill is a SKILL.md instruction file that Claude loads when it is relevant. A subagent is a definition Claude can delegate to. Hooks are commands Claude Code runs at points in its lifecycle. MCP servers are tool servers that Claude Code connects to while the plugin is enabled^[1].

Know what an enabled plugin costs

An enabled plugin is part of every session, not just the ones where you use it. The names and descriptions of the skills and agents Claude can invoke on its own sit in Claude's context on every turn. The MCP servers run alongside each session, and the plugin's hooks fire at their events. Whatever a plugin runs, it runs as you^[1].

Check this before you install. In /plugin, the Marketplaces tab shows a context cost estimate for plugins in Anthropic's official marketplace. If you want to keep a plugin without using it, disable it with /plugin or with claude plugin disable in your shell^[1].

Install from a marketplace

A marketplace is a repository or directory with a .claude-plugin/marketplace.json file. The file lists plugins and says where to fetch each one. It is a catalog, not a hosted store^[1]. Claude Code adds Anthropic's official marketplace the first time you start an interactive terminal session, unless a managed policy blocks it^[1].

In a Claude Code terminal session, run /plugin and install a plugin from the Discover tab, which lists the plugins from your marketplaces^[1]. When you install, you choose a scope. User scope enables the plugin in every project on your computer. Project scope enables it for everyone who works in the repository, through the committed .claude/settings.json. Local scope enables it in that repository only^[1].

Marketplaces fall into three tiers: official, community and third-party. Official names include claude-plugins-official and claude-code-plugins. A community name such as claude-community marks a community marketplace, and every other marketplace is third-party. Treat third-party marketplaces with the same care as any other code, because an installed plugin can run code with your user privileges^[1].

Build your first plugin

You need Claude Code installed and signed in^[2]. The walkthrough builds a plugin with one greeting skill and loads it with --plugin-dir, which loads a plugin for a single session without installing it^[2].

Start by creating the plugin directory with a .claude-plugin/ folder inside it:

mkdir -p my-first-plugin/.claude-plugin

Save the manifest as my-first-plugin/.claude-plugin/plugin.json:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

name is required. It becomes the prefix on every skill and agent the plugin provides, so do not put spaces in it. description is the text shown for the plugin in /plugin. version is optional, and setting it keeps users on that version until you change it. author needs a name^[2].

Each skill lives in its own directory under skills/, with a SKILL.md file inside. Create the directory:

mkdir -p my-first-plugin/skills/hello

Then save my-first-plugin/skills/hello/SKILL.md with this content:

---
name: hello
description: Greet the user with a friendly message
disable-model-invocation: true
---
Greet the user warmly and ask how you can help them today.

The disable-model-invocation: true line stops Claude from running the skill on its own. Remove it from a skill you want Claude to run by itself. The command combines the plugin name and the skill name, so this skill runs as /my-first-plugin:hello^[2].

Validation comes before loading, so manifest and frontmatter mistakes show up first. When it fails, work through each message in order instead of rerunning the command.

Validate and load

Run the validator before you start a session:

claude plugin validate ./my-first-plugin

A passing run prints ✔ Validation passed. If it prints ✘ Validation failed, each line above that result names the field to fix^[2].

Now start a session with the plugin loaded and run the skill:

claude --plugin-dir ./my-first-plugin

Inside the session, type /my-first-plugin:hello. The plugin loads only in sessions started with --plugin-dir. When you edit its files during a session, run /reload-plugins to pick up the changes^[2].

The flag accepts a directory or a .zip archive and can be repeated. --plugin-url fetches a .zip from a URL for one session, and the CLAUDE_CODE_PLUGIN_DIRS environment variable lists absolute paths when you cannot add a flag^[2]. claude plugin init my-tool instead scaffolds a plugin under ~/.claude/skills/ that loads in every session. Adding --with skills also creates a skill under skills/^[2].

Because the plugin name is prefixed to every skill and agent, two plugins can each provide a skill with the same short name without clashing in the command list. That makes the name field worth choosing with care.

Plugin layout

The plugin root is the directory you pass to --plugin-dir. Inside it, .claude-plugin/plugin.json is the manifest. skills/ holds one <name>/SKILL.md directory per skill. commands/ holds flat Markdown files, the older form of skills, and new plugins should use skills/. agents/ holds one Markdown file per subagent. hooks/hooks.json configures hooks, and .mcp.json defines MCP servers. Only plugin.json belongs inside .claude-plugin/^[2].

Share the plugin

There are three ways to hand a finished plugin to others. You can send its directory or a .zip to a few people, which requires no publishing. You can list it in your own marketplace so teammates install it by name and get your updates. You can also submit it to Anthropic's directory after review^[2].

Before handing a plugin to others, load it once with --plugin-dir and confirm that each skill runs as you expect.

Before you share, make sure the plugin holds only what you want others to run, because once installed it runs with the user's own privileges.

A cloud session, including one at claude.ai/code, does not load the plugins in your local settings. Plan for that when a teammate works from the browser^[1].

Next steps

For the full install steps and the manifest fields, follow the official documentation^[1][2].