plugin-dev

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/
│   ├── 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:

{
  "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:

{
  "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.j