claude-code-plugin-development

Claude Code Plugin Development

Create distributable plugins that bundle commands, agents, skills, hooks, MCP servers, and LSP servers.

Official docs: https://code.claude.com/docs/en/plugins-reference

Quick Reference

You MUST read these references for detailed schemas and examples:

• Plugin Manifest - Complete plugin.json schema
• Plugin Components - Commands, agents, skills, hooks, MCP, LSP
• CLI Commands - Install, uninstall, enable, disable, update
• Debugging - Common issues and troubleshooting

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required manifest
├── commands/                 # Slash commands (.md files)
├── agents/                   # Subagents (.md files)
├── skills/                   # Skills (subdirs with SKILL.md)
├── hooks/
│   └── hooks.json           # Hook configuration
├── .mcp.json                # MCP server definitions
├── .lsp.json                # LSP server configurations
└── scripts/                 # Hook and utility scripts

Important: Components go at plugin root, NOT inside .claude-plugin/. Only plugin.json belongs in .claude-plugin/.

Marketplace Structure

A marketplace can contain multiple plugins. The marketplace root has its own .claude-plugin/marketplace.json:

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json     # Lists all plugins in this marketplace
├── plugins/
│   ├── plugin-a/
│   │   ├── .claude-plugin/
│   │   │   └── plugin.json
│   │   └── skills/
│   └── plugin-b/
│       ├── .claude-plugin/
│       │   └── plugin.json
│       └── commands/

marketplace.json

{
  "name": "my-marketplace",
  "owner": {
    "name": "author-name"
  },
  "plugins": [
    {
      "name": "plugin-a",
      "source": "./plugins/plugin-a",
      "description": "First plugin description",
      "version": "1.0.0"
    },
    {
      "name": "plugin-b",
      "source": "./plugins/plugin-b",
      "description": "Second plugin description",
      "version": "0.2.0"
    }
  ]
}

Critical: When adding a new plugin to a marketplace:

1. Add it to marketplace.json or it won't be installable
2. If using release-please, add a jsonpath entry to the config for the new plugin's version

Minimal plugin.json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief plugin description"
}

Installation Scopes

Scope	Location	Use case
user	~/.claude/settings.json	Personal plugins (default)
project	.claude/settings.json	Team plugins via version control
local	.claude/settings.local.json	Project-specific, gitignored
managed	managed-settings.json	Read-only managed plugins

Environment Variables

Use ${CLAUDE_PLUGIN_ROOT} for paths in hooks and MCP configs:

{
  "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
}

Plugin Components Summary

Component	Location	Format
Commands	commands/	Markdown with frontmatter
Agents	agents/	Markdown with frontmatter
Skills	skills/*/SKILL.md	Directories with SKILL.md
Hooks	hooks/hooks.json	JSON configuration
MCP servers	.mcp.json	MCP server config
LSP servers	.lsp.json	Language server config

CLI Quick Reference

# Install
claude plugin install <plugin>@<marketplace> --scope user

# Manage
claude plugin enable <plugin>
claude plugin disable <plugin>
claude plugin update <plugin>
claude plugin uninstall <plugin>

# Debug
claude --debug

Permissions

Problem: Using ! backticks to run plugin scripts fails with permission error:

Error: Bash command permission check failed for pattern
"!`${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh 2>&1 || true`":
This Bash command contains multiple operations.

Cause: ! backticks have their own permission model separate from allowed-tools. Complex commands or scripts fail.

Solution: Use the Bash tool instead of ! backticks for scripts:

---
allowed-tools: Bash(${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh:*)
---

Run the script:
    ```bash
    ${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh
    ```

Simple git commands still work with ! backticks: !git branch --show-current``

Common Issues

Plugin installed but commands don't appear?

The plugin may be disabled. Check ~/.claude/settings.json:

"enabledPlugins": {
  "my-plugin@my-marketplace": false  // ← Disabled!
}

Fix with: claude plugin enable my-plugin@my-marketplace then restart Claude Code.

Local changes not picked up?

Use claude plugin update <plugin> or do a full reinstall:

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

Important

After creating or modifying plugins, inform the user:

Plugin changes take effect immediately after installation. Use claude --debug to verify plugin loading.

Checklist

Before finalizing a plugin:

• plugin.json has name, version, description
• Components at plugin root (not in .claude-plugin/)
• All paths use ${CLAUDE_PLUGIN_ROOT} variable
• Scripts are executable (chmod +x)
• If part of a marketplace, plugin is listed in marketplace.json
• If using release-please, add jsonpath for new plugin version in config
• Test with claude --debug to verify loading