/plugin-dev

name: plugin-dev
description: >
  Use this skill when creating or refining Claude Code plugins. Plugins are bundled collections
  of agents, skills, commands, hooks, and MCP servers that provide cohesive functionality. Helps
  design proper directory structures, plugin.json configuration, marketplace distribution, and
  installation workflows. Automatically invoked when user requests "create a plugin", "bundle
  components", "distribute capabilities", or mentions plugin development.
allowed-tools: Read, Write, Edit, Bash(mkdir:*), Bash(tree:*), Grep, Glob

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`

{
  "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@example.com",
    "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@example.com", "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/
│   ├─