Guide for creating, configuring, and distributing Claude Code plugins with hooks, skills, commands, and MCP servers. Use when user asks to create a plugin, set up hooks, add plugin functionality, create a marketplace, or distribute custom Claude Code extensions.
Complete guide for building Claude Code plugins with all available features.
Documentation sources:
Plugins extend Claude Code with shareable, versioned functionality distributed through marketplaces. They can include:
Use Plugins when:
Use Project Files (.claude/) when:
Use Personal Files (~/.claude/) when:
| Component | File Location | Use When |
|---|---|---|
| Plugins | See plugins.md | Distributing packaged functionality |
| Hooks | See hooks.md | Automating responses to events |
| Skills | See skills.md | Claude should auto-discover capability |
| Commands | See commands.md | User explicitly invokes with /command |
| Agents | See agents.md | Need specialized subagent |
| MCP Servers | See mcp-servers.md | Integrating external tools |
mkdir -p my-plugin/.claude-plugin
cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
{
"name": "my-plugin",
"version": "1.0.0",
"description": "My first plugin",
"author": {"name": "Your Name"}
}
EOF
Choose what to add:
Add a hook (see hooks.md):
mkdir -p my-plugin/hooks
# Create hooks/hooks.json
Add a skill (see skills.md):
mkdir -p my-plugin/skills/my-skill
# Create skills/my-skill/SKILL.md
Add a command (see commands.md):
mkdir -p my-plugin/commands
# Create commands/my-command.md
mkdir -p ~/dev-marketplace/.claude-plugin
cat > ~/dev-marketplace/.claude-plugin/marketplace.json << 'EOF'
{
"name": "Development Marketplace",
"plugins": [
{
"name": "my-plugin",
"source": "my-plugin",
"description": "My first plugin"
}
]
}
EOF
# Move plugin into marketplace
mv my-plugin ~/dev-marketplace/
claude plugins add ~/dev-marketplace
claude plugins install my-plugin
# Test your plugin
claude
# After changes, reinstall
claude plugins uninstall my-plugin
claude plugins install my-plugin
claude --debug and check logsEnable debug mode:
claude --debug
Check plugin status:
claude plugins list
View registered hooks:
In Claude session, use /hooks command
| Pattern | Components | Use Case |
|---|---|---|
| Auto-formatter | PostToolUse hook | Format code after edits |
| File protection | PreToolUse hook | Block edits to sensitive files |
| Test generator | Skill + Command | Auto-generate or explicitly create tests |
| Code reviewer | Skill + Agent | Auto-review or detailed analysis |
| Dev workflow | Hook + Skill + Command | Complete development automation |
| Security guard | Multiple hooks | Prevent secrets, validate imports |
For comprehensive information on each component, see:
Available in plugin configurations:
${CLAUDE_PLUGIN_ROOT} - Absolute path to plugin directory${CLAUDE_PROJECT_DIR} - Current project root${CLAUDE_ENV_FILE} - SessionStart hooks only: file to persist env vars"$VAR"if [[ "$PATH" == *".."* ]].env, .git/, credentialsclaude --debug/hooks command to view registered hooks