Plugin Development

Create, bundle, and distribute Claude Code plugins that package skills, commands, hooks, and MCP servers into a single installable unit.

Prerequisites

• Claude Code CLI installed and configured
• Node.js 18+ for build tooling
• At least one skill, command, or MCP server to package
• Understanding of the plugin manifest format

Workflow

Step 1: Plan the Plugin

Define the plugin scope:

1. Plugin name - human-readable name (e.g., "Docker Workflow Tools")
2. Plugin ID - unique kebab-case identifier (e.g., docker-workflow-tools)
3. Components - list what the plugin includes:
   • Skills (SKILL.md files)
   • Slash commands
   • Event hooks (pre-commit, post-push, etc.)
   • MCP servers
   • Configuration templates
4. Dependencies - external tools or services required
5. Target audience - who will use this plugin

Step 2: Scaffold the Plugin Structure

Create the plugin directory:

<plugin-id>/
  plugin.json           # Plugin manifest (required)
  skills/
    <skill-name>/
      SKILL.md          # Skill definition
  commands/
    <command-name>.js   # Slash command handlers
  hooks/
    pre-commit.js       # Git hook handlers
    post-push.js
  mcp-servers/
    <server-name>/      # Bundled MCP server
      src/
      package.json
  config/
    defaults.json       # Default configuration values
  README.md             # Plugin documentation

Step 3: Write the Plugin Manifest

Create plugin.json with required fields:

{
  "id": "<plugin-id>",
  "name": "<Plugin Name>",
  "version": "1.0.0",
  "description": "What this plugin does",
  "author": "<author>",
  "license": "MIT",
  "skills": ["skills/<skill-name>"],
  "commands": {
    "<command>": "commands/<command-name>.js"
  },
  "hooks": {
    "pre-commit": "hooks/pre-commit.js"
  },
  "mcpServers": {
    "<server-name>": {
      "command": "node",
      "args": ["mcp-servers/<server-name>/dist/index.js"]
    }
  },
  "config": {
    "schema": "config/schema.json",
    "defaults": "config/defaults.json"
  }
}

Step 4: Implement Components

For each component type:

Skills: Write SKILL.md files following the standard skill format with frontmatter, workflow steps, examples, and best practices.

Commands: Implement slash command handlers that receive user arguments and return responses. Each command exports a handler function.

Hooks: Implement event handlers that run at specific lifecycle points. Hooks receive context about the triggering event and can modify behavior.

MCP Servers: Build standalone MCP servers that the plugin manages. Include build scripts and proper dependency isolation.

Step 5: Add Configuration

1. Define a JSON Schema for plugin settings
2. Set sensible defaults in config/defaults.json
3. Document each setting with description and valid values
4. Support environment variable overrides for secrets

Step 6: Test the Plugin

1. Install the plugin locally for development testing
2. Verify each skill triggers correctly
3. Test all slash commands with various inputs
4. Confirm hooks fire at the right lifecycle events
5. Validate MCP servers start and respond properly
6. Test configuration loading and validation

Step 7: Package and Distribute

1. Run the build step for any compiled components
2. Validate the manifest against the plugin schema
3. Create the distributable package
4. Publish to the plugin registry or distribute directly

Output Format

The skill produces:

• Complete plugin directory with all components
• Valid plugin.json manifest
• Implemented skills, commands, hooks, and/or MCP servers
• Configuration schema and defaults
• README with installation and usage instructions

Examples

Example 1: CI/CD Plugin

User: "Create a plugin for managing CI/CD pipelines"

Action: Scaffold a plugin with skills for pipeline configuration, commands for triggering builds, hooks for pre-push validation, and an MCP server for build status queries.

Example 2: Code Quality Plugin

User: "Build a plugin that enforces code quality standards"

Action: Scaffold a plugin with a linting skill, pre-commit hooks for formatting, commands for running quality checks, and configuration for rule customization.

Example 3: Documentation Plugin

User: "Make a plugin for auto-generating project documentation"

Action: Scaffold a plugin with skills for API doc generation, a command for doc preview, and hooks that update docs on file changes.

Best Practices

1. Keep plugins focused - one domain or workflow per plugin
2. Minimize dependencies - fewer external requirements means easier adoption
3. Provide sensible defaults - the plugin should work out of the box
4. Version all components - use the plugin version to track breaking changes
5. Isolate MCP server dependencies - avoid conflicts with the host environment
6. Document installation steps - include any system-level prerequisites
7. Handle missing dependencies gracefully - check and report, do not crash
8. Test across platforms - verify on macOS, Linux, and Windows

Error Handling