claude-plugins/claude-code/skills/claude-plugins/SKILL.md

---
name: Claude Code Plugin Developer
description: Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers. Use PROACTIVELY when users package multiple related features, mention "create a plugin", "package for distribution", "plugin marketplace", or have 3+ commands/skills to organize. NOT for creating individual components in isolation.
---

# Claude Code Plugin Development

## When to Use This Skill

Use this skill when:
- Creating a new plugin from scratch
- Adding components to existing plugin
- Configuring plugin manifests
- Setting up distribution/marketplaces
- Packaging 3+ related commands/skills/agents

Do NOT use this skill for:
- Creating standalone MCP servers
- Single commands (use claude-commands skill)
- General Claude Code usage

## Quick Start

### 1. Basic Plugin Structure

```bash
mkdir my-plugin && cd my-plugin
mkdir -p .claude-plugin

cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "my-plugin",
  "description": "What your plugin does",
  "version": "1.0.0",
  "author": {"name": "Your Name"}
}
EOF

# Add component directories
mkdir -p commands agents skills hooks
```

### 2. Test Installation

```bash
/plugin install /path/to/my-plugin@local
/plugin list
```

## Plugin Manifest (plugin.json)

### Required Fields

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

### Optional Fields

```json
{
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo"
  },
  "license": "MIT",
  "keywords": ["productivity", "automation"]
}
```

## Plugin Components

### 1. Commands (commands/)

**→ [See claude-commands skill for full guide](../claude-commands/skill.md)**

```markdown
# commands/review.md
---
description: Review code for issues
---

Review $ARGUMENTS for:
- Logic errors
- Style issues
```

**Usage**: `/review @file.js`

### 2. Agents (agents/)

**→ [See claude-subagents skill for full guide](../claude-subagents/skill.md)**

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

You are a code review specialist...
```

### 3. Skills (skills/)

**→ [See claude-skills skill for full guide](../claude-skills/skill.md)**

```
skills/
└── my-skill/
    └── skill.md    # With frontmatter
```

### 4. Hooks (hooks/hooks.json)

**→ [See claude-hooks skill for full guide](../claude-hooks/skill.md)**

```json
{
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "npx prettier --write $TOOL_ARGS"
    }]
  }]
}
```

### 5. MCP Servers (.mcp.json)

**→ [See mcp-config skill for full guide](../mcp-config/skill.md)**

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

## Directory Organization

**IMPORTANT**: Components at plugin root, NOT in `.claude-plugin/`

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

## Distribution

### Local Testing

```bash
/plugin install /path/to/plugin@local
```

### Team Marketplace

```json
// .claude/settings.json
{
  "plugin-marketplaces": {
    "team": {
      "url": "file:///path/to/marketplace"
    }
  },
  "plugins": ["my-plugin@team"]
}
```

### Marketplace Structure

```
marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugin-name/
    ├── .claude-plugin/plugin.json
    └── [components]
```

## Common Patterns

### Multi-Command Plugin

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

### Agent + Skill Combo

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

### Hook-Based Automation

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

## Testing Checklist

- [ ] plugin.json valid JSON
- [ ] All required fields present
- [ ] Components at plugin root
- [ ] Commands have frontmatter
- [ ] Local installation works
- [ ] No sensitive data
- [ ] README documents features

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Plugin not found | Check plugin.json in `.claude-plugin/` |
| Commands unavailable | Verify `commands/` at root, restart |
| Invalid structure | Move components to root, not `.claude-plugin/` |

## Security

**Never include**:
- API keys or credentials
- Hardcoded secrets
- Personal paths

**Use environment variables**:
```json
{
  "mcpServers": {
    "api": {
      "env": {"API_KEY": "env:MY_API_KEY"}
    }
  }
}
```

## Version Management

```json
{
  "version": "1.1.0"  // Semantic versioning
}

// Breaking: 2.0.0
// Features: 1.1.0
// Fixes: 1.0.1
```

## Additional Resources

**Component Skills:**
- [Commands Guide](../claude-commands/skill.md) - Create slash commands
- [Subagents Guide](../claude-subagents/skill.md) - Configure specialized agents
- [Skills Guide](../claude-skills/skill.md) - Build contextual knowledge skills
- [Hooks Guide](../claude-hooks/skill.md) - Automate with event-driven hooks
- [MCP Config Guide](../mcp-config/skill.md) - Integrate MCP servers
- [Memory Guide](../claude-memory/skill.md) - Manage persistent memory

**External Resources:**
- [Official Docs](https://docs.claude.com/en/docs/claude-code/plugins)
- [MCP Protocol](https://modelcontextprotocol.io/)

💡 **Tip**: Start with one component type, test thoroughly, then expand. Plugins organize related functionality.

---

**Remember**: Plugins package related features. Components go at root. Test locally first. Use semantic versioning.