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

| Limit | Value | Consequence if Exceeded | |-------|-------|------------------------| | All skill descriptions combined | 15,000 chars | Silent filtering, skills won't activate | | Individual description | 1,024 chars | Truncation | | SKILL.md body | 5,000 words | Context saturation, partial execution | | Target per description | 300-400 chars | Allows ~40 skills safely |

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

| Practice | Reason | |----------|--------| | Keep SKILL.md under 2000 words | Move details to references/ for progressive disclosure | | Use specific trigger phrases | "when user asks to 'create X'" not "provides guidance" | | Imperative writing style | "Parse the config" not "You should parse" | | Portable paths | ${CLAUDE_PLUGIN_ROOT} not hardcoded | | Test after changes | /restart then invoke skill/command | | Single responsibility | One focused purpose per component |

Common Mistakes

| Mistake | Solution | |---------|---------| | Vague skill descriptions | Add specific trigger phrases users would say | | 8000-word SKILL.md | Move content to references/, keep SKILL.md brief | | Hardcoded paths | Use ${CLAUDE_PLUGIN_ROOT} for portability | | Missing frontmatter | All components need valid YAML frontmatter | | Wrong directory structure | See @references/structure.md for correct layout |

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:

| Need to... | See | |-----------|-----| | Understand plugin layout | @references/structure.md | | Create a skill | @references/skills-reference.md | | Add a slash command | @references/commands-reference.md | | Configure a subagent | @references/agents-reference.md | | Set up hooks | @references/hooks-reference.md | | Integrate MCP server | @references/mcp-reference.md | | Build a marketplace | @references/marketplace-reference.md |

Status: Consolidated plugin development skill with progressive disclosure pattern