title: "Plugins" description: "Package and distribute skills, agents, hooks, and MCP servers as shareable bundles" section: "Core" readTime: "9 min" badge: "NEW"

Plugins

Plugins bundle skills, custom agents, hooks, and MCP servers into a single unit that Claude Code installs and loads together. Most plugins come from a marketplace — a catalog that lists plugins and where to fetch each one. Share them with your team, publish them for your organization, or have IT/DevOps require them through managed settings.

What a Plugin Contains

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # Manifest (only this file goes here)
├── skills/
│   ├── deploy/
│   │   └── SKILL.md
│   └── code-review/
│       └── SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/
│   └── hooks.json         # Same shape as "hooks" in settings.json
└── .mcp.json              # MCP server definitions

Component directories live at the plugin root, not inside .claude-plugin/ — anything saved there doesn't load. A legacy commands/ directory of flat Markdown files also works, but use skills/ for new plugins.

Skills from a plugin use a namespaced command: /plugin-name:skill-name. This prevents conflicts with project or personal skills of the same name.

Install a Plugin

Inside a session, /plugin opens the plugin manager (tabs: Discover, Installed, Marketplaces, Errors). Anthropic's official marketplace, claude-plugins-official, is added automatically the first time you start an interactive session.

# In a session: open the plugin's details, then pick a scope
/plugin install commit-commands@claude-plugins-official
 
# Add another marketplace first (GitHub repo, git URL, local path, or marketplace.json URL)
/plugin marketplace add your-org/plugins
/plugin install deploy-helper@<marketplace-name>   # name from its marketplace.json
 
# Apply changes made on disk or pending installs
/reload-plugins

From your shell (scripts, CI):

claude plugin install formatter@your-org --scope project
claude plugin list
claude plugin disable formatter@your-org
claude plugin enable formatter@your-org
claude plugin update formatter@your-org
claude plugin uninstall formatter@your-org
claude plugin marketplace add your-org/plugins

Install scopes

Local overrides project, and project overrides user. A project-scoped plugin is enabled for collaborators via the committed settings, but each person still installs it once with claude plugin install <name>@<marketplace> --scope project.

Plugins from Anthropic's official marketplaces auto-update by default; third-party and local marketplaces don't (toggle per marketplace in the Marketplaces tab).

Create a Plugin

1. Create the directory and manifest

mkdir -p my-plugin/.claude-plugin

my-plugin/.claude-plugin/plugin.json:

{
  "name": "my-plugin",
  "description": "ACME internal Claude Code skills",
  "version": "1.0.0",
  "author": { "name": "ACME Platform Team" }
}

Only name is required (no spaces) — it becomes the prefix for every skill and agent. Setting version pins users to that version until you bump it.

2. Add skills

mkdir -p my-plugin/skills/deploy
cat > my-plugin/skills/deploy/SKILL.md << 'EOF'
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(./scripts/deploy.sh *)
---
 
Run the deployment pipeline:
1. Run tests: `./scripts/test.sh`
2. Build: `./scripts/build.sh`
3. Deploy: `./scripts/deploy.sh $ARGUMENTS`
4. Verify: check health endpoint
EOF

3. Validate and test locally

claude plugin validate ./my-plugin
claude --plugin-dir ./my-plugin      # loads for this session only

Then run /my-plugin:deploy staging. Edit files and run /reload-plugins to pick up changes; check the Errors tab in /plugin if something doesn't load.

4. Share it

Send the folder or a .zip to a few people (they load it with --plugin-dir), or list it in a marketplace. A marketplace is just a repo with .claude-plugin/marketplace.json:

{
  "name": "acme-tools",
  "owner": { "name": "ACME Platform Team" },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "ACME internal Claude Code skills"
    }
  ]
}

Push it to a git host; teammates run claude plugin marketplace add acme/claude-plugins and then claude plugin install my-plugin@acme-tools. Plugin sources can also be github, git-subdir, url, npm, and others. You can also submit a plugin to Anthropic's directory.

Enterprise-Managed Plugins

IT/DevOps can require plugins on every machine via managed settings (server-managed from the claude.ai admin console, MDM, or managed-settings.json). Users can't override them.

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme/claude-plugins" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "security-standards@acme-tools": true,
    "deployment-tools@acme-tools": true
  }
}

extraKnownMarketplaces registers the marketplace and enabledPlugins force-enables plugins (false blocks one everywhere). Other managed controls:

This ensures every developer has the same security hooks, company coding standards, and deployment workflows — without each person installing them manually.

Plugin Skill Namespace

Plugin skills appear in the / menu as plugin-name:skill-name (the plugin's name, not the marketplace's). You can invoke them directly:

/my-plugin:deploy staging
/my-plugin:code-review src/api/

Plugin agents are namespaced the same way, e.g. my-plugin:security-reviewer.

skillOverrides does not apply to plugin skills. Manage them via /plugin instead.

Scope Priority

When skills share the same name across levels, this is the resolution order:

1. Enterprise managed (always wins)
2. Personal (~/.claude/skills/)
3. Project (.claude/skills/)
4. Plugin (namespaced, so no conflict)

Related

• Skills — The skills system plugins extend
• Subagents — Custom agents distributed via plugins
• Hooks — Hook configurations bundled in plugins