name: plugin-development 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 Development 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

Develop plugin locally:

cd plugins/my-plugin
# Create .claude-plugin/plugin.json
# Add agents, skills, commands
# Test locally

Create repository:

git init
git add .
git commit -m "Initial plugin release"
git tag v1.0.0
git push origin main --tags

Add to marketplace:

{
  "plugins": [{
    "name": "my-plugin",
    "source": "github:username/my-plugin",
    "version": "1.0.0"
  }]
}

Announce and distribute:
- Share marketplace URL
- Document in README
- Provide installation instructions

Component Organization Best Practices

Agents

Group related agents by domain:

agents/
├── database/
│   ├── postgres-expert.md
│   └── mongodb-expert.md
├── api/
│   ├── rest-api-expert.md
│   └── graphql-expert.md
└── infrastructure/
    ├── docker-expert.md
    └── k8s-expert.md

Skills

Organize by capability:

skills/
├── data-processing/
│   ├── SKILL.md
│   └── examples/
├── api-testing/
│   ├── SKILL.md
│   └── templates/
└── deployment-automation/
    ├── SKILL.md
    └── scripts/

Commands

Group by workflow or domain:

commands/
├── development/
│   ├── start-dev.md
│   ├── run-tests.md
│   └── lint-code.md
├── database/
│   ├── migrate.md
│   └── seed-data.md
└── deployment/
    ├── deploy-staging.md
    └── deploy-production.md

Testing Your Plugin

Local Testing

Install plugin locally:

/plugin install /absolute/path/to/plugin-directory

Verify components loaded:

/agents          # Check agents available
/commands        # Check commands available

Test each component:
- Agents: Request tasks that should invoke them
- Skills: Trigger with natural language
- Commands: Execute slash commands
- Hooks: Verify event triggers work
Check for conflicts:
- Name collisions with existing components
- Tool access issues
- Dependency problems

Team Testing

Add to project settings:

{
  "plugins": {
    "test-plugin": {
      "source": "file:../plugins/test-plugin",
      "enabled": true
    }
  }
}

Have team members clone project:

git clone project-repo
# Plugin auto-installs

Collect feedback:
- Component discovery issues
- Missing capabilities
- Documentation clarity
- Installation problems

Version Management

Semantic Versioning

Follow semver:

MAJOR (1.0.0 → 2.0.0): Breaking changes
- Remove components
- Change command syntax
- Incompatible updates
MINOR (1.0.0 → 1.1.0): New features (backward compatible)
- Add new agents/skills
- Add new commands
- Enhance existing features
PATCH (1.0.0 → 1.0.1): Bug fixes
- Fix agent prompts
- Correct command syntax
- Update documentation

Changelog

Maintain CHANGELOG.md:

# Changelog

## [1.1.0] - 2025-01-15

### Added
- New mongodb-expert agent
- /db-backup command

### Changed
- Improved postgres-expert query optimization

### Fixed
- Migration skill path resolution bug

## [1.0.0] - 2025-01-01

### Added
- Initial release
- postgres-expert agent
- schema-evolution skill

README Template

# Plugin Name

Brief description of plugin capabilities.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

\`\`\`
/plugin install plugin-name
\`\`\`

Or add to project `.claude/settings.json`:

\`\`\`json
{
  "plugins": {
    "plugin-name": {
      "source": "github:username/plugin-name",
      "version": "^1.0.0"
    }
  }
}
\`\`\`

## Components

### Agents
- **agent-one**: Description
- **agent-two**: Description

### Skills
- **skill-one**: Description
- **skill-two**: Description

### Commands
- `/command-one`: Description
- `/command-two`: Description

## Usage Examples

### Example 1
\`\`\`
User: Request example
Claude: Uses component to handle request
\`\`\`

### Example 2
\`\`\`
/command-example arg1 arg2
\`\`\`

## Configuration

Optional configuration in `.claude/settings.json`:

\`\`\`json
{
  "plugin-name": {
    "option1": "value1"
  }
}
\`\`\`

## License

MIT

## Contributing

Contributions welcome! See CONTRIBUTING.md.

Common Mistakes to Avoid

❌ Missing plugin.json

plugin-name/
├── agents/
└── README.md              # No .claude-plugin/plugin.json

✅ Proper structure

plugin-name/
├── .claude-plugin/
│   └── plugin.json        # Required
├── agents/
└── README.md

❌ Unversioned plugin

{
  "name": "my-plugin"
  // Missing "version" field
}

✅ Properly versioned

{
  "name": "my-plugin",
  "version": "1.0.0"
}

❌ No documentation

plugin-name/
├── .claude-plugin/
└── agents/                # No README explaining usage

✅ Well-documented

plugin-name/
├── .claude-plugin/
├── agents/
├── README.md              # Installation and usage guide
└── CHANGELOG.md           # Version history

❌ Conflicting component names

plugin-name/agents/postgres-expert.md
# Conflicts with user's existing postgres-expert agent

✅ Unique naming

plugin-name/agents/company-postgres-expert.md
# Prefixed to avoid conflicts

Advanced Features

Organization-Level Deployment

For enterprise teams, Anthropic provides the /v1/skills API endpoint for programmatic skill management:

List and manage skills via the API
Add skills to Messages API requests via the container.skills parameter
Centralized version control and management through the Claude Console
Works with the Claude Agent SDK for building custom agents

This is relevant when plugins contain skills intended for organization-wide deployment beyond individual Claude Code installations.

Namespacing

All plugin components are automatically prefixed with the plugin name when installed. For example, a plugin named my-plugin with a /deploy command becomes accessible as my-plugin:deploy. This prevents naming collisions between plugins.

Agents: my-plugin:agent-name
Skills: my-plugin:skill-name
Commands: /my-plugin:command-name

Caching Behavior

Installed plugins are copied to ~/.claude/plugins/cache. Key implications:

Plugins cannot reference files outside their root directory — all resources must be self-contained
Changes to the source directory are not reflected until you uninstall and reinstall
Use claude --plugin-dir ./my-plugin during development for rapid iteration (see Development Workflow below)

Development Workflow

Use these tools for rapid plugin iteration:

claude --plugin-dir ./my-plugin — Load a plugin from a local directory without installing. Changes take effect immediately on next session.
claude --debug — Enable diagnostic output to troubleshoot plugin loading issues, component discovery, and activation.
Uninstall/reinstall cycle — For installed plugins, run /plugin uninstall plugin-name then /plugin install /path/to/plugin to pick up changes.

Resources

Reference the examples directory for:

Complete plugin structures across different scales
plugin.json configurations for various use cases
Marketplace setup and distribution patterns
Multi-component organization strategies

Next Steps: After creating a plugin, test locally with /plugin install /path/to/plugin, gather feedback from team members, version appropriately, and distribute via marketplace or Git repository.