plugin-dev

What this skill does

# Plugin Dev Skill

This skill helps create production-ready Claude Code plugins following Anthropic's official plugin specifications.

## What is a Plugin?

A plugin is a **bundled collection** of Claude Code components that work together to provide cohesive functionality. Plugins enable:

- **Modular distribution**: Package related capabilities together
- **Team sharing**: Install once across multiple projects
- **Version management**: Track plugin versions independently
- **Marketplace discovery**: Publish for community use
- **Automatic updates**: Keep components synchronized

## Plugin vs Individual Components

| Approach | When to Use |
|----------|-------------|
| **Individual Components** | Single capability, personal use, experimental |
| **Plugin** | Multiple related components, team distribution, reusable across projects |

**Example - Individual approach**:
- `.claude/agents/postgres-expert.md` (one file)
- `.claude/commands/test.md` (one file)

**Example - Plugin approach**:
- `database-toolkit/` plugin containing:
  - Agents: postgres-expert, mongodb-expert, sql-expert
  - Skills: migration-management, query-optimization
  - Commands: /migrate, /db-status
  - Templates: schema templates

**Design consideration**: Claude supports 20-50 skills simultaneously. When designing plugins with multiple skills, keep each skill focused and avoid overlap. Beyond 50 simultaneous skills, activation accuracy may decrease. Consider bundling related capabilities into fewer, more comprehensive skills rather than many narrow ones.

## Plugin Structure

```
plugin-name/
├── .claude-plugin/
│   └── plugin.json              # Required: Plugin metadata
├── agents/                      # Optional: Sub-agent definitions
│   ├── agent-one.md
│   └── agent-two.md
├── skills/                      # Optional: Skill definitions
│   ├── skill-one/
│   │   ├── SKILL.md             # Do NOT add README.md inside skill dirs
│   │   ├── examples/
│   │   └── assets/              # Optional: Static resources
│   └── skill-two/
│       └── SKILL.md
├── commands/                    # Optional: Slash commands
│   ├── command-one.md
│   └── subfolder/
│       └── command-two.md
├── hooks/                       # Optional: Hook configurations
│   └── hooks.json
├── .mcp.json                    # Optional: MCP server integrations
├── .lsp.json                    # Optional: LSP server integrations
├── templates/                   # Optional: Code templates
│   └── template-files/
├── patterns/                    # Optional: Design patterns
│   └── pattern-docs/
├── README.md                    # Recommended: Plugin documentation
└── LICENSE                      # Recommended: License file
```

## plugin.json Configuration

**Required file**: `.claude-plugin/plugin.json`

```json
{
  "name": "database-toolkit",
  "version": "1.0.0",
  "description": "Comprehensive database management toolkit with experts for PostgreSQL, MongoDB, and SQL",
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "url": "https://example.com"
  },
  "homepage": "https://github.com/username/database-toolkit",
  "license": "MIT",
  "repository": "https://github.com/username/database-toolkit",
  "keywords": [
    "database",
    "postgresql",
    "mongodb",
    "sql",
    "migration",
    "optimization"
  ]
}
```

### Field Specifications

**name** (required)
- Unique plugin identifier
- Lowercase, alphanumeric, hyphens
- Example: `database-toolkit`, `api-testing-suite`

**version** (required)
- Semantic versioning: `MAJOR.MINOR.PATCH`
- Example: `1.0.0`, `2.3.1-beta`

**description** (required)
- Clear explanation of plugin capabilities
- 1-3 sentences
- Include key features

**author** (required)
- Object with `name` (required), `email` (optional), and `url` (optional)
- Example: `{"name": "Your Name", "email": "[email protected]", "url": "https://example.com"}`

**homepage** (optional)
- URL to plugin homepage or documentation site
- Example: `"https://github.com/username/plugin-name"`

**license** (recommended)
- SPDX identifier: `MIT`, `Apache-2.0`, `GPL-3.0`
- Or `"SEE LICENSE IN <filename>"`

**repository** (recommended)
- URL or object pointing to source code
- String format: `"https://github.com/username/plugin-name"`

**keywords** (optional)
- Searchable terms for marketplace discovery
- Array of strings
- 5-10 relevant keywords

**Component path overrides** (optional)
- Override default component directories: `commands`, `agents`, `skills`, `hooks`, `mcpServers`, `outputStyles`, `lspServers`
- Custom paths supplement default directories — they don't replace them
- Example: `"agents": ["./custom-agents/expert.md"]`

## Directory Organization Patterns

### Single-Purpose Plugin
Focused on one domain with minimal structure.

```
database-migration/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   └── migration-expert.md
├── skills/
│   └── schema-evolution/
│       └── SKILL.md
├── commands/
│   ├── migrate.md
│   └── rollback.md
└── README.md
```

### Multi-Component Plugin
Comprehensive toolkit with multiple agents and capabilities.

```
full-stack-toolkit/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   ├── backend/
│   │   ├── fastapi-expert.md
│   │   └── nodejs-expert.md
│   ├── frontend/
│   │   ├── react-expert.md
│   │   └── nextjs-expert.md
│   └── database/
│       └── postgres-expert.md
├── skills/
│   ├── api-testing/
│   ├── deployment/
│   └── monitoring/
├── commands/
│   ├── dev/
│   │   ├── start-dev.md
│   │   └── run-tests.md
│   └── deploy/
│       └── production-deploy.md
├── templates/
│   ├── api-endpoint/
│   ├── react-component/
│   └── database-schema/
└── README.md
```

### Plugin with MCP Integration
Includes external tool integrations.

```
devops-toolkit/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   ├── docker-expert.md
│   └── k8s-expert.md
├── mcp/
│   ├── docker-cli/
│   │   └── config.json
│   └── kubectl/
│       └── config.json
├── skills/
│   └── container-orchestration/
└── README.md
```

## Installation Methods

### User Installation

**Interactive interface**:
```
/plugin
```
Opens plugin browser with search and installation UI.

**Direct installation**:
```
/plugin install plugin-name@marketplace-name
```

**From local path**:
```
/plugin install /path/to/plugin-directory
```

**From Git URL**:
```
/plugin install https://github.com/user/plugin-name.git
```

### Project-Level Installation (Automatic for Team)

Configure in `.claude/settings.json`:

```json
{
  "plugins": {
    "database-toolkit": {
      "source": "github:username/database-toolkit",
      "version": "^1.0.0",
      "enabled": true
    },
    "local-plugin": {
      "source": "file:../plugins/local-plugin",
      "enabled": true
    }
  }
}
```

**Benefits**:
- Team members auto-install plugins on project clone
- Version-controlled plugin configuration
- Consistent development environment

## Marketplace Distribution

### Creating a Marketplace

**marketplace.json** format:

```json
{
  "name": "company-plugins",
  "description": "Internal company plugin marketplace",
  "plugins": [
    {
      "name": "database-toolkit",
      "description": "Database management toolkit",
      "version": "1.0.0",
      "source": "github:company/database-toolkit",
      "author": "Company DevOps",
      "keywords": ["database", "postgresql", "migration"]
    },
    {
      "name": "api-testing",
      "description": "API testing and validation suite",
      "version": "2.1.0",
      "source": "github:company/api-testing",
      "author": "Company QA",
      "keywords": ["testing", "api", "validation"]
    }
  ]
}
```

### Adding Marketplace

Users add your marketplace:

```
/plugin marketplace add https://company.com/plugins/marketplace.json
```

Or from local file:

```
/plugin marketplace add file:///path/to/marketplace.json
```

### Publishing Workflow

1. **Develop plugin locally**:
   ```bash
   cd plugins/my-plugin
   # Create .claude-plugin/plugin.