Claude Code Plugin Development

Comprehensive guidance for creating well-structured plugins, skills, hooks, agents, commands, and MCP integrations.

Core Principles (Anthropic Official)

1. •Composable - Multiple skills work together seamlessly, Claude coordinates automatically
2. •Portable - Same format works across Claude apps, Claude Code, and Claude API
3. •Efficient - Progressive disclosure loads only what's needed (description → SKILL.md → references)
4. •Powerful - Combines prompts + executable code for complete workflows
5. •Secure - Never hardcode secrets, use ${CLAUDE_PLUGIN_ROOT} for paths

Critical Budget Limits

Quick Start

Create a New Plugin

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/skills/my-skill/references

cat > my-plugin/.claude-plugin/plugin.json << 'PLUGIN'
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin does"
}
PLUGIN

cat > my-plugin/skills/my-skill/SKILL.md << 'SKILL'
---
name: my-skill
description: Use when creating X, configuring Y, or analyzing Z
---

# My Skill

Instructions for Claude when this skill activates...
SKILL

Install and Test

# Symlink to Claude's plugin directory
ln -s $(pwd)/my-plugin ~/.claude/plugins/my-plugin

# Restart Claude Code to load
/restart

# Test the skill
/my-plugin:my-skill

Component Reference

Choose a topic for detailed guidance:

📁 @references/structure.md - Plugin Directory Structure

• •Standard plugin layout
• •Marketplace vs standalone patterns
• •Auto-discovery rules
• •Portable path references (${CLAUDE_PLUGIN_ROOT})
• •Common troubleshooting

🎯 @references/skills-reference.md - Creating Skills

• •SKILL.md format and frontmatter
• •Progressive disclosure patterns
• •Bundled resources (scripts/, references/, assets/)
• •Description best practices with trigger phrases
• •Writing style (imperative, not second person)
• •Validation checklist

💬 @references/commands-reference.md - Slash Commands

• •Command file format with frontmatter
• •Dynamic arguments ($1, $2, @$1)
• •Bash execution inline
• •Tool restrictions (allowed-tools)
• •Organization (flat vs namespaced)
• •Plugin command portability

🤖 @references/agents-reference.md - Subagents

• •Agent frontmatter (name, description, model, color, tools)
• •Name validation rules
• •Description with examples
• •Color guidelines by purpose
• •Tool restriction patterns
• •System prompt best practices

🎣 @references/hooks-reference.md - Event Hooks

• •Hook types (prompt-based vs command)
• •Event types (PreToolUse, PostToolUse, Stop, etc.)
• •Configuration (hooks.json format)
• •Matchers (exact, wildcard, regex)
• •Output structure and exit codes
• •Security best practices
• •Environment variables

🔌 @references/mcp-reference.md - MCP Integration

• •MCP server configuration (.mcp.json)
• •Server types (stdio, SSE, HTTP, WebSocket)
• •Tool naming conventions
• •Environment variable usage
• •Security and testing

🏪 @references/marketplace-reference.md - Marketplaces

• •Standalone vs marketplace patterns
• •marketplace.json schema
• •Skills array pattern
• •Bundle plugin pattern
• •Common mistakes to avoid
• •Team configuration

📋 @references/plugin-reference.md - Plugin Manifest

• •plugin.json required fields
• •Optional metadata
• •Custom component paths
• •Installation and deployment

⚙️ @references/settings.md - Plugin Settings

• •.local.md settings files
• •YAML frontmatter for configuration
• •Reading settings in hooks
• •Best practices and gitignore

Common Patterns

Minimal Skill

---
name: simple-skill
description: Use when user asks to "do X" or "configure Y"
---

# Simple Skill

Step-by-step instructions...

1. Check if condition exists
2. Execute action
3. Verify result

For detailed patterns, see @references/advanced-patterns.md

Command with Arguments

---
description: Review code for security issues
allowed-tools: Read, Grep
argument-hint: [file] [severity]
---

Review @$1 for security issues.
Focus on severity level: $2

Use these patterns:
- SQL injection
- XSS vulnerabilities  
- Hardcoded credentials

Hook with Validation

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
        "timeout": 30
      }]
    }]
  }
}

File Organization

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Manifest
├── commands/                 # Slash commands
│   └── action.md
├── agents/                   # Subagents
│   └── analyzer.md
├── skills/                   # Skills
│   └── my-skill/
│       ├── SKILL.md         # Main skill file
│       ├── references/      # Detailed docs
│       ├── scripts/         # Executable code
│       └── assets/          # Templates, images
├── hooks/
│   └── hooks.json           # Event handlers
└── .mcp.json                # MCP servers

Development Workflow

1. •Plan - Identify what your plugin should do
2. •Structure - Create directory layout (see @references/structure.md)
3. •Implement - Write skills, commands, or agents
4. •Configure - Add hooks or MCP servers if needed
5. •Test - Install and verify functionality
6. •Iterate - Refine based on usage
7. •Document - Update README and examples

Best Practices

Common Mistakes

Validation

Before releasing a plugin:

• • plugin.json has required name field
• • All SKILL.md files have name and description
• • Descriptions include specific trigger phrases
• • All referenced files exist
• • No hardcoded paths (use ${CLAUDE_PLUGIN_ROOT})
• • Skills under 2000 words (details in references/)
• • Commands have argument-hint if they take args
• • Agents have valid name (3-50 chars, lowercase-hyphens)
• • Hooks return valid JSON with proper exit codes
• • README documents installation and usage

Related Tools

• •/plugin-dev:create-plugin - Interactive plugin scaffolding command
• •/plugin-dev:plugin-cli - CLI commands for plugin management
• •/skill-creator:skill-creation - Focused skill creation workflow
• •/agent-creator:agent-design - Subagent design patterns
• •/mcp-builder:mcp-servers - MCP server development

Quick Navigation:

Status: Consolidated plugin development skill with progressive disclosure pattern