Claude Code /plugin: Extend Your AI With Custom Skills

Why /plugin

Claude Code ships with 40+ tools and 80+ commands — already powerful. But every team and project has different needs. Some want a one-click deploy command, others need to connect internal MCP services, and some want Claude to run checks automatically before every commit.

Built-in features can’t satisfy everyone. That’s why Claude Code has a plugin system that lets you extend its capabilities yourself.

/plugin is the gateway to managing those plugins.

What Is /plugin

/plugin is Claude Code’s plugin management command (aliases: /plugins, /marketplace). It provides an interactive UI for browsing, installing, enabling, disabling, and managing plugins.

Type:

/plugin

This opens the plugin management interface, showing your installed plugins and available marketplaces.

What Plugins Can Do

A plugin can contain any combination of:

Component	Description	Examples
Commands	Custom slash commands	/build, /deploy
Skills	AI skills (SKILL.md format)	Code review skill, test generation skill
Agents	AI sub-agents	A dedicated test runner agent
Hooks	Lifecycle hooks	Auto-lint before commits
MCP Servers	MCP protocol servers	Connect to databases, internal APIs
LSP Servers	Language Server Protocol	Custom language support
Output Styles	Terminal output styling	Custom themes

In short, plugins are the standardized way to add features to Claude Code.

Plugin Structure

A typical plugin directory looks like this:

my-plugin/
├── plugin.json          # Plugin manifest (metadata + component declarations)
├── commands/            # Custom commands
│   ├── build.md
│   └── deploy.md
├── skills/              # AI skills
│   └── code-review/
│       └── SKILL.md
├── agents/              # AI agents
│   └── test-runner.md
├── hooks/               # Lifecycle hooks
│   └── hooks.json
├── .mcp.json            # MCP server configuration
└── data/                # Persistent data directory

The core is plugin.json, which declares all metadata and components:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A custom plugin for my team",
  "author": {
    "name": "Your Name"
  },
  "commands": "./commands",
  "skills": "./skills",
  "agents": "./agents",
  "hooks": "./hooks/hooks.json",
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["my-mcp-server"]
    }
  }
}

Installation and Management

Interactive Management

/plugin

Opens the graphical interface where you can install, enable, and disable plugins directly.

Command-Line Management

Better suited for scripts and automation:

# Install a plugin
claude plugin install my-plugin@github:owner/repo

# Uninstall
claude plugin uninstall my-plugin@github:owner/repo

# Enable / Disable
claude plugin enable my-plugin@github:owner/repo
claude plugin disable my-plugin@github:owner/repo

# Update
claude plugin update my-plugin@github:owner/repo

# List installed plugins
claude plugin list
claude plugin list --json        # JSON output
claude plugin list --available   # Show installable plugins

# Validate a plugin manifest
claude plugin validate ./path/to/plugin.json

Three Installation Scopes

Scope	Config Location	Who It Affects
user	~/.claude/settings.json	All your projects
project	.claude/settings.json	All collaborators in this repo
local	.claude/settings.local.json	Only you, only this repo copy

Specify with the --scope flag:

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

Default scope is user.

Marketplace

Marketplaces are where plugins come from. You can add multiple marketplaces:

# Add a GitHub repo as a marketplace
claude plugin marketplace add github:owner/plugin-repo

# List added marketplaces
claude plugin marketplace list

# Update marketplace cache
claude plugin marketplace update

# Remove
claude plugin marketplace remove marketplace-name

Marketplaces support multiple source types:

• GitHub repos: github:owner/repo
• Git URLs: Any Git repository
• URLs: Direct links to marketplace.json
• Local directories: For development and debugging

Plugin Identifiers

Each plugin has a unique identifier in the format name@marketplace, for example:

• my-tool@github:owner/repo — From a GitHub marketplace
• dev-util@builtin — Built-in plugin
• test-plugin@inline — Session-only plugin (loaded via --plugin-dir)

Built-in Plugins

Claude Code ships with some built-in plugins, identified as @builtin. Like third-party plugins, they can be enabled or disabled, but they don’t need installation — they ship with the CLI.

In the /plugin interface, built-in plugins appear in a separate “Built-in” section.

Plugin Environment Variables

Commands, hooks, and MCP configurations within plugins can use these variables:

Variable	Value	Purpose
${CLAUDE_PLUGIN_ROOT}	Plugin installation path	Reference files within the plugin
${CLAUDE_PLUGIN_DATA}	~/.claude/plugins/data/<id>/	Persistent data directory
${CLAUDE_SKILL_DIR}	Skill subdirectory path	Internal use within skills
${CLAUDE_SESSION_ID}	Current session ID	Cross-tool correlation
${user_config.KEY}	User-configured value	Dynamic parameters

The ${CLAUDE_PLUGIN_DATA} directory persists across plugin updates, making it ideal for storing user data.

User Configuration

Plugins can declare configuration fields that users need to fill in:

{
  "userConfig": {
    "API_KEY": {
      "type": "secret",
      "description": "Your API key for the service",
      "sensitive": true
    },
    "BUILD_FLAGS": {
      "type": "string",
      "description": "Extra build flags",
      "default": "--production"
    }
  }
}

After installing a plugin, Claude Code prompts users to fill in these configurations. Sensitive fields (like API keys) won’t appear in command content.

/reload-plugins

After modifying plugin configurations, you don’t need to restart Claude Code. Just run:

/reload-plugins

It will:

1. Clear the plugin cache
2. Reload all plugins
3. Report results: plugin count, skill count, agent count, hook count, MCP/LSP server count
4. Clearly indicate any loading errors

Plugin Hook System

Plugins can register hooks to listen to Claude Code lifecycle events. Supported events include:

• SessionStart / SessionEnd — Session begins and ends
• PreToolUse / PostToolUse — Before and after tool calls
• UserPromptSubmit — When users submit messages
• PreCompact / PostCompact — Before and after context compression
• Stop — When Claude stops responding

Hook configuration example:

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "name": "lint-before-bash",
          "command": "echo 'Running pre-check...'"
        }
      ]
    }
  ]
}

Troubleshooting

Plugin failed to load? Use the /doctor command to see detailed information about all plugin errors.

Common error types:

• plugin-not-found — Plugin not found in marketplace
• manifest-parse-error — plugin.json format error
• dependency-unsatisfied — Required plugin dependency not enabled
• mcp-config-invalid — MCP server configuration error

Real-World Scenarios

Scenario 1: Team-Shared Commands

Your team has a standard deployment workflow. Package it as a plugin, add it to .claude/settings.json (project scope), and everyone who clones the repo automatically gets the /deploy command.

Scenario 2: Internal Tool Integration

Your company has an internal MCP server connected to databases and monitoring systems. Declare the MCP configuration through a plugin, and team members can let Claude query production data directly after installation.

Scenario 3: Custom Code Checks

Write a hook plugin that automatically runs your lint and type-check every time Claude modifies a file. Catch issues immediately, instead of waiting until commit time.

Scenario 4: Development and Debugging

When developing your own plugin, use the --plugin-dir flag to temporarily load a local directory:

claude --plugin-dir ./my-local-plugin

Publish to a marketplace once debugging is complete.

Final Thoughts

/plugin transforms Claude Code from a “fixed-feature tool” into an extensible platform.

You’re no longer limited to what Claude Code ships with — if you need a feature, just write a plugin. And through the marketplace and installation scope mechanisms, plugins can be easily shared across teams.

A great tool isn’t one that does everything — it’s one that lets you do anything.