plugin-dev

What this skill does

# 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

```bash
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

```bash
# 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

```yaml
---
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

```markdown
---
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

```json
{
  "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-ref