Plugins

Level: 🌿 Intermediate Source: Plugins, Plugins Reference

← Back to Automating Your Workflows

Plugins are shareable bundles of skills, agents, hooks, and MCP servers packaged into a single installable unit. Think of them as the “app store” layer on top of Claude Code’s extension system.

When to Use Plugins vs Standalone Config

Approach Best for
Standalone (.claude/ directory) Personal workflows, project-specific tweaks, quick experiments
Plugins Sharing with teammates, distributing to community, reusing across projects

Rule of thumb: Start with standalone config in .claude/. Convert to a plugin when you want to share it.

Installing Plugins

Requires Claude Code v1.0.33 or later. Run claude --version to check.

From the built-in marketplace 

/plugin

This opens an interactive browser where you can search, install, enable, and disable plugins. The official Anthropic marketplace (claude-plugins-official) is available by default.

To install directly by name:

/plugin install plugin-name@claude-plugins-official

From a GitHub marketplace

Add a GitHub repo as a marketplace, then install plugins from it:

/plugin marketplace add owner/repo
/plugin install plugin-name@owner-repo

Or from the CLI:

claude plugin marketplace add owner/repo
claude plugin install plugin-name@owner-repo

From a local directory (permanent install)

Add a local plugin directory as a marketplace, then install:

/plugin marketplace add ./my-plugin
/plugin install my-plugin@my-plugin

From a team marketplace

If your team has a custom marketplace, it may be configured automatically via extraKnownMarketplaces in your project’s .claude/settings.json. When you open the project, Claude Code prompts you to install the marketplace and its plugins.

Load for current session only (development/testing) 

claude --plugin-dir ./my-plugin

This loads the plugin without installing it permanently — useful for development and testing. You can load multiple plugins at once:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

After installing a plugin, restart Claude Code for its skills to become available. The --plugin-dir flag does not require a restart since it loads the plugin at launch.

Installation Scopes

When you install a plugin, you choose where it applies:

Scope Settings file Use case
User (default) ~/.claude/settings.json Personal — available across all your projects
Project .claude/settings.json Team — shared via version control with all collaborators
Local .claude/settings.local.json Private to you in this repo only (gitignored)

From the interactive UI (/plugin → Discover tab → select a plugin), you’ll see all three options. From the CLI, use --scope:

claude plugin install my-plugin@marketplace --scope project
claude plugin uninstall my-plugin@marketplace --scope project

Managed scope is a fourth read-only scope set by administrators via managed settings — these plugins cannot be modified by users.

Managing Installed Plugins 

/plugin                    # Interactive UI — Installed tab to view/manage
/plugin disable name@mkt   # Disable without uninstalling
/plugin enable name@mkt    # Re-enable
/plugin uninstall name@mkt # Remove completely
/plugin update name@mkt    # Update to latest version from marketplace
/reload-plugins            # Apply changes without restarting

What Plugins Can Include

A plugin is a directory with a .claude-plugin/plugin.json manifest and any combination of:

Component Directory What it does
Skills skills/ Reusable prompts and workflows (invoked as /plugin-name:skill-name)
Agents agents/ Custom sub agents with their own tools and permissions
Hooks hooks/hooks.json Event handlers that fire on lifecycle events
MCP servers .mcp.json External tool integrations
LSP servers .lsp.json Language intelligence (go-to-definition, type errors, etc.)
Settings settings.json Default configuration applied when the plugin is enabled

Creating Your First Plugin

1. Create the directory structure 

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/skills/hello

2. Write the manifest

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

{
  "name": "my-plugin",
  "description": "A helpful plugin for my team",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

3. Add a skill

Create my-plugin/skills/hello/SKILL.md:

---
description: Greet the user and offer help
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

4. Test it 

claude --plugin-dir ./my-plugin

Then type /my-plugin:hello to invoke your skill.

Important: Don’t put skills/, agents/, or hooks/ inside .claude-plugin/. Only plugin.json goes in there. Everything else goes at the plugin root.

Plugin Directory Structure 

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Manifest (required)
├── skills/
│   └── code-review/
│       └── SKILL.md          # /my-plugin:code-review
├── agents/
│   └── security-reviewer.md  # Custom sub agent
├── hooks/
│   └── hooks.json            # Lifecycle hooks
├── .mcp.json                 # MCP server configs
├── .lsp.json                 # Language server configs
└── settings.json             # Default settings

Namespacing

Plugin skills are namespaced to prevent conflicts: /plugin-name:skill-name. This means two plugins can both have a review skill without clashing.

Converting Standalone Config to a Plugin

If you already have skills, agents, or hooks in .claude/, you can convert them:

  1. Create a plugin directory with .claude-plugin/plugin.json
  2. Copy your .claude/skills/ → my-plugin/skills/
  3. Copy your .claude/agents/ → my-plugin/agents/
  4. Move hook config from .claude/settings.json → my-plugin/hooks/hooks.json
  5. Test with claude --plugin-dir ./my-plugin

After migrating, you can remove the originals from .claude/ to avoid duplicates.

Key Plugins to Know About

Notable plugins from the official and community marketplaces:

  • frontend-design (Anthropic) — Auto-invoked skill that improves Claude’s frontend/UI output
  • code-review (Anthropic) — Parallel sub agent architecture for thorough code reviews
  • plugin-dev (Anthropic) — Guided end-to-end plugin creation workflow
  • context7 (Upstash, community-managed) — MCP-powered access to up-to-date library documentation
  • claude-code-setup (schuettc) — Meta-plugin that helps configure Claude Code for your project

For detailed descriptions, install instructions, and the patterns each plugin demonstrates, see Plugin Examples.

🌳 Distributing Your Plugin

Push your plugin to a Git repository and share it through a marketplace. You can submit to the official Anthropic marketplace, create your own community marketplace on GitHub, or distribute via your team’s internal marketplace using extraKnownMarketplaces.

For the full guide to marketplace creation, publishing, and discovery, see Marketplace.

🌳 Versioning Your Plugin

Source: Plugins Reference — Version Management

Plugin cache

Marketplace plugins are not used in-place. When you install a plugin, Claude Code copies it to ~/.claude/plugins/cache. All subsequent reads come from that cache — changes to the source directory have no effect on installed users until an update occurs.

Version is the cache key

If you change your plugin’s code but don’t bump the version in plugin.json, your plugin’s existing users won’t see your changes due to caching.

Without a version bump, Claude Code has no way to know that anything changed. Always bump the version when you ship changes.

Semantic versioning

Bump When Examples
Major (X) Breaking changes, structural redesigns Removing a skill, renaming hook events, incompatible schema changes
Minor (Y) New features, new reference docs, new behaviors Adding a skill, new tracking category, new reference doc
Patch (Z) Bug fixes, wording tweaks, small improvements Fixing a regex in a hook, typo in a doc, adjusting a case branch

Where the version lives

The version field can be set in:

  • plugin.json ("version": "X.Y.Z") — the plugin manifest
  • marketplace.json (inside a plugin entry) — the marketplace listing

If both are set, plugin.json takes priority. Keep them in sync to avoid confusion.

Update workflow

After bumping your version and pushing to the marketplace repository:

  1. Users run /plugin update name@mkt (or claude plugin update name@mkt from the CLI)
  2. Claude Code pulls the latest version into ~/.claude/plugins/cache, replacing the old copy
  3. A restart (or /reload-plugins) picks up the new version

Development shortcut

During local development, --plugin-dir bypasses the cache entirely — Claude Code reads directly from the directory you point to. Use /reload-plugins to pick up mid-session changes without restarting:

claude --plugin-dir ./my-plugin   # reads live from disk, no cache

Automating version bumps

This repository includes a version-bump agent (agents/version-bump.md) that bumps the version in both plugin.json and marketplace.json in a single step, keeping them in sync.

Next Steps

Claude and Claude Code are products of Anthropic, PBC. This guide is a community project and is not affiliated with or endorsed by Anthropic. Original content is licensed under CC BY 4.0 — the license does not cover Anthropic's product or official documentation.

This site uses Just the Docs, a documentation theme for Jekyll.