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

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
│   │   └── examples/
│   └── skill-two/
│       └── SKILL.md
├── commands/                    # Optional: Slash commands
│   ├── command-one.md
│   └── subfolder/
│       └── command-two.md
├── hooks/                       # Optional: Hook configurations
│   └── hooks-config.json
├── mcp/                         # Optional: MCP server integrations
│   └── server-config.json
├── 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": "Your Name <email@example.com>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/username/database-toolkit"
  },
  "keywords": [
    "database",
    "postgresql",
    "mongodb",
    "sql",
    "migration",
    "optimization"
  ],
  "engines": {
    "claude-code": ">=2.0.0"
  },
  "dependencies": {
    "other-plugin": "^1.2.0"
  }
}

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)

• Name and email: "Name <email@example.com>"
• Organization: "Company Name"

license (recommended)

• SPDX identifier: MIT, Apache-2.0, GPL-3.0
• Or "SEE LICENSE IN <filename>"

repository (recommended)

• Version control information
• Helps users find source code
• Enables issue tracking

keywords (optional)

• Searchable terms for marketplace discovery
• Array of strings
• 5-10 relevant keywords

engines (optional)

• Minimum Claude Code version required
• Semantic version range: ">=2.0.0", "^2.1.0"

dependencies (optional)

• Other plugins this plugin requires
• Semantic version ranges

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:

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

2. Create repository:

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

3. Add to marketplace:

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

4. 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

1. Install plugin locally:

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

2. Verify components loaded:

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

3. Test each component:

   • Agents: Request tasks that should invoke them
   • Skills: Trigger with natural language
   • Commands: Execute slash commands
   • Hooks: Verify event triggers work

4. Check for conflicts:

   • Name collisions with existing components
   • Tool access issues
   • Dependency problems

Team Testing

1. Add to project settings:

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

2. Have team members clone project:

   git clone project-repo
   # Plugin auto-installs
   

3. 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

Plugin Dependencies

Reference other plugins:

{
  "name": "advanced-toolkit",
  "dependencies": {
    "database-toolkit": "^1.0.0",
    "api-testing-suite": "^2.1.0"
  }
}

Conditional Loading

Load components based on project type:

{
  "name": "full-stack-toolkit",
  "conditions": {
    "hasFile": ["package.json"],
    "environment": ["development", "staging"]
  }
}

Configuration Schema

Define expected configuration:

{
  "name": "deployment-toolkit",
  "configSchema": {
    "environments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "url": {"type": "string"}
        }
      }
    }
  }
}

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.