plugins-reference

Claude Code Plugins Reference

Plugins bundle commands, agents, skills, hooks, and MCP servers into distributable packages.

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── commands/                 # Slash commands
│   └── deploy.md
├── agents/                   # Subagent definitions
│   └── reviewer.md
├── skills/                   # Agent skills
│   └── api-patterns/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # Hook configurations
├── .mcp.json                # MCP server configs
└── .lsp.json                # LSP server configs

plugin.json Manifest

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com"
  },
  "keywords": ["keyword1", "keyword2"]
}

Required vs Optional Fields

Field	Required	Description
name	Yes	Unique identifier (kebab-case)
version	No	Semantic version
description	No	Brief description
author	No	Author info
commands	No	Custom command paths
agents	No	Custom agent paths
skills	No	Custom skill paths
hooks	No	Hook config path/object
mcpServers	No	MCP config path/object
lspServers	No	LSP config path/object

Installation Scopes

Scope	Location	Use Case
user	~/.claude/settings.json	Personal (default)
project	.claude/settings.json	Team shared
local	.claude/settings.local.json	Project, gitignored

Plugin Commands

Install plugin:

/plugin install plugin-name@marketplace
claude plugin install plugin-name@marketplace --scope project

Uninstall plugin:

/plugin uninstall plugin-name

Enable/Disable:

/plugin enable plugin-name
/plugin disable plugin-name

Update plugin:

/plugin update plugin-name

Validate plugin:

/plugin validate ./path/to/plugin
claude plugin validate ./path/to/plugin

Marketplace Setup

marketplace.json

{
  "name": "my-marketplace",
  "owner": {
    "name": "Team Name"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "description": "Plugin description"
    }
  ]
}

Marketplace Commands

# Add marketplace
/plugin marketplace add owner/repo
/plugin marketplace add https://gitlab.com/org/plugins.git

# Update marketplaces
/plugin marketplace update

# List marketplaces
/plugin marketplace list

Plugin Sources

Relative Path

{ "source": "./plugins/my-plugin" }

GitHub

{
  "source": {
    "source": "github",
    "repo": "owner/repo"
  }
}

Git URL

{
  "source": {
    "source": "url",
    "url": "https://gitlab.com/org/plugin.git"
  }
}

Environment Variable

Use ${CLAUDE_PLUGIN_ROOT} in hooks and MCP configs:

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
      }]
    }]
  }
}

Project-Required Plugins

Add to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "formatter@company-tools": true
  }
}

Common Issues

Issue	Solution
Plugin not loading	Check plugin.json syntax
Commands missing	Ensure commands/ at root, not in .claude-plugin/
Hooks not firing	Check script permissions (chmod +x)
MCP fails	Use ${CLAUDE_PLUGIN_ROOT} for paths

Debugging

# Debug mode shows plugin loading
claude --debug

# Check for errors
/plugin  # Navigate to Errors tab

---

For complete documentation, see:

• plugins-full.md - Plugin creation guide
• plugins-tech-reference.md - Complete technical reference
• marketplace.md - Marketplace distribution