---
name: Claude Code Plugin Developer
description: Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers. Use when building plugins for Claude Code, setting up plugin structure, or configuring plugin manifests.
---

# Claude Code Plugin Development

## When to Use This Skill

Use this skill when:
- Creating a new Claude Code plugin from scratch
- Adding components to an existing plugin (commands, agents, skills, hooks)
- Configuring plugin manifests and metadata
- Setting up plugin distribution and marketplaces
- Troubleshooting plugin structure or installation issues

Do NOT use this skill for:
- Creating standalone MCP servers (use MCP-specific documentation)
- General Claude Code usage (not plugin development)
- Creating individual skills without plugin context

## Quick Start: Creating a Plugin

### 1. Basic Plugin Structure

```bash
# Create plugin directory
mkdir my-plugin
cd my-plugin

# Create required manifest directory
mkdir -p .claude-plugin

# Create plugin.json manifest
cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "my-plugin",
  "description": "Description of what your plugin does",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}
EOF
```

### 2. Add Component Directories

```bash
# Create directories for plugin components
mkdir -p commands     # Slash commands
mkdir -p agents       # Custom agents
mkdir -p skills       # Agent Skills
mkdir -p hooks        # Event handlers
```

**Result**: Basic plugin structure ready for adding components.

## Plugin Manifest (plugin.json)

### Required Fields

```json
{
  "name": "plugin-name",           // Lowercase, kebab-case
  "description": "What it does",   // Clear, concise description
  "version": "1.0.0",              // Semantic versioning
  "author": {
    "name": "Author Name"          // Your name or organization
  }
}
```

### Optional Fields

```json
{
  "name": "my-plugin",
  "description": "Advanced features",
  "version": "1.2.0",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://yoursite.com"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo"
  },
  "license": "MIT",
  "keywords": ["productivity", "automation"]
}
```

## Plugin Components

### 1. Commands (Slash Commands)

Create markdown files in `commands/` directory:

```bash
# commands/review-security.md
---
description: Review code for security vulnerabilities
allowed-tools: Read(*), Grep(*)
---

Review the following files for common security issues:
- SQL injection vulnerabilities
- XSS vulnerabilities
- Hardcoded credentials
- Unsafe deserialization

$ARGUMENTS
```

**Usage**: `/review-security @src/auth.js`

### 2. Agents

Create agent configurations in `agents/` directory:

```bash
# agents/code-reviewer.md
---
description: Reviews code for best practices
tools: [Read, Grep, Bash]
model: claude-sonnet-4
---

You are a code review specialist. When reviewing code:
1. Check for common patterns and anti-patterns
2. Verify error handling
3. Look for security issues
4. Suggest improvements
```

### 3. Skills

Create skill directories in `skills/`:

```bash
mkdir -p skills/my-skill
# Then create skills/my-skill/SKILL.md with proper frontmatter
```

See the `claude-skills` skill for comprehensive skill creation guidance.

### 4. Hooks

Create `hooks/hooks.json` to define event handlers:

```json
{
  "PostToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [
        {
          "type": "command",
          "command": "echo 'File modified: $TOOL_ARGS' >> .claude/activity.log"
        }
      ]
    }
  ]
}
```

### 5. MCP Servers

Create `.mcp.json` for external tools:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "env:MY_API_KEY"
      }
    }
  }
}
```

## Complete Plugin Example

### File Structure

```
weather-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── weather.md
├── agents/
│   └── forecast-analyst.md
├── skills/
│   └── weather-api/
│       └── SKILL.md
└── README.md
```

### plugin.json

```json
{
  "name": "weather-plugin",
  "description": "Weather forecasting and analysis tools",
  "version": "1.0.0",
  "author": {
    "name": "Weather Team"
  }
}
```

### commands/weather.md

```markdown
---
description: Get current weather for a location
argument-hint: <location>
---

Get the current weather conditions for: $ARGUMENTS

Include:
- Temperature
- Conditions
- Humidity
- Wind speed
```

### agents/forecast-analyst.md

```markdown
---
description: Analyzes weather patterns and forecasts
tools: [WebFetch, Read]
---

You are a weather analysis specialist. When asked about weather:
1. Gather current conditions
2. Analyze patterns
3. Provide forecast insights
4. Suggest appropriate actions
```

## Distribution & Installation

### Local Development

Test your plugin locally:

```bash
# Install from local directory
/plugin install /path/to/my-plugin@local

# Verify installation
/plugin list
```

### Development Marketplace

Create a development marketplace for testing:

```json
// ~/.claude/settings.json
{
  "plugin-marketplaces": {
    "dev": {
      "url": "file:///path/to/marketplace-dir"
    }
  }
}
```

### Team Distribution

Add to project settings for automatic installation:

```json
// .claude/settings.json
{
  "plugins": [
    "my-plugin@company-marketplace"
  ],
  "plugin-marketplaces": {
    "company-marketplace": {
      "url": "https://plugins.company.com"
    }
  }
}
```

## Best Practices

### Plugin Design

1. **Single responsibility**: Each plugin should have a focused purpose
2. **Clear naming**: Use descriptive, kebab-case names
3. **Semantic versioning**: Follow SemVer for version numbers
4. **Documentation**: Include comprehensive README.md

### Directory Organization

```
my-plugin/
├── .claude-plugin/        # Manifest only
│   └── plugin.json
├── commands/              # At plugin root, not in .claude-plugin/
├── agents/               # At plugin root
├── skills/               # At plugin root
└── README.md             # Usage documentation
```

**IMPORTANT**: Component directories go at the plugin root, NOT inside `.claude-plugin/`

### Testing Checklist

- [ ] Plugin.json is valid JSON
- [ ] All required fields present
- [ ] Component directories at plugin root
- [ ] Commands have valid frontmatter
- [ ] Skills follow proper structure
- [ ] Local installation works
- [ ] No sensitive data in files
- [ ] README documents all features

### Version Management

```bash
# Update version in plugin.json
{
  "version": "1.1.0"  // Increment for changes
}

# Breaking changes: 2.0.0
# New features: 1.1.0
# Bug fixes: 1.0.1
```

## Common Patterns

### Multi-Command Plugin

For related commands, use subdirectories:

```
git-tools/
├── .claude-plugin/plugin.json
└── commands/
    ├── commit.md
    ├── pr.md
    └── review.md
```

**Usage**: `/commit`, `/pr`, `/review`

### Agent + Skill Combination

Combine agents with specialized skills:

```
api-plugin/
├── .claude-plugin/plugin.json
├── agents/
│   └── api-specialist.md
└── skills/
    └── rest-api/
        └── SKILL.md
```

The agent can leverage the skill for specialized knowledge.

### Hook-Based Automation

Use hooks for workflow automation:

```json
{
  "PostToolUse": [
    {
      "matcher": "Write",
      "hooks": [
        {
          "type": "command",
          "command": "npm run format $TOOL_ARGS"
        }
      ]
    }
  ]
}
```

## Troubleshooting

### Plugin Not Found

**Issue**: `/plugin install` can't find plugin

**Solutions**:
1. Check marketplace configuration in settings.json
2. Verify plugin name matches directory name
3. Ensure plugin.json exists in `.claude-plugin/`

### Commands Not Available

**Issue**: Slash commands don't appear

**Solutions**:
1. Verify commands are in `commands/` at plugin root
2. Check markdown files have `.md` extension
3. Restart Claude Code to refresh

### Invalid Structure Error

**Issue**: Plugin fails to load

**Solutions**:
1. Ensure `.claude-plugin/plugin.json` exists
2. Validate JSON syntax
3. Move component directories to plugin root (not in `.claude-plugin/`)

## Security Considerations

### Never Include

- API keys or credentials in plugin files
- Personal identifying information
- Proprietary code without permission
- Hardcoded paths to user-specific locations

### Use Environment Variables

```json
// .mcp.json
{
  "mcpServers": {
    "api-server": {
      "env": {
        "API_KEY": "env:MY_API_KEY"  // Reference env var
      }
    }
  }
}
```

### Command Permissions

Limit tool access in command frontmatter:

```markdown
---
allowed-tools: Read(src/**), Grep(src/**)
---
```

## Plugin Template

Use this as a starting point:

```bash
#!/bin/bash
# create-plugin.sh <plugin-name>

PLUGIN_NAME=$1

mkdir -p "$PLUGIN_NAME"/{.claude-plugin,commands,agents,skills,hooks}

cat > "$PLUGIN_NAME/.claude-plugin/plugin.json" << EOF
{
  "name": "$PLUGIN_NAME",
  "description": "TODO: Add description",
  "version": "0.1.0",
  "author": {
    "name": "TODO: Add author"
  }
}
EOF

cat > "$PLUGIN_NAME/README.md" << EOF
# $PLUGIN_NAME

TODO: Add plugin description

## Installation

\`\`\`
/plugin install $PLUGIN_NAME@marketplace
\`\`\`

## Features

TODO: List features

## Usage

TODO: Add usage examples
EOF

echo "Plugin structure created in $PLUGIN_NAME/"
```

## Resources

- [Official Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
- [Slash Commands Guide](../claude-code-slash-commands/SKILL.md)
- [Hooks Guide](../claude-code-hooks/SKILL.md)
- [Agent Skills Guide](../claude-skills/SKILL.md)

## Quick Reference

### Required Structure
```
plugin-name/
└── .claude-plugin/
    └── plugin.json
```

### Common Commands
```bash
# Install
/plugin install plugin-name@marketplace

# List installed
/plugin list

# Uninstall
/plugin uninstall plugin-name
```

### Manifest Template
```json
{
  "name": "plugin-name",
  "description": "What it does",
  "version": "1.0.0",
  "author": {"name": "Your Name"}
}
```

---

**Remember**: Plugins extend Claude Code with persistent, reusable functionality. Start simple with one or two components, test thoroughly, then expand based on actual needs.