Creating Plugins

Create Claude Code plugins that bundle multiple extension types for distribution via marketplaces.

Quick Reference

Plugin vs Standalone

Choose the right approach for your use case:

Use standalone when:

• Customizing for a single project
• Personal configuration (not shared)
• Quick experiments before packaging

Use plugins when:

• Sharing with team or community
• Same functionality across multiple projects
• Distributing through marketplace
• Bundling multiple component types

Plugin Structure

my-plugin/
├── .claude-plugin/           # Metadata directory
│   └── plugin.json           # Required: plugin manifest
├── commands/                 # Slash commands (Markdown files)
│   ├── deploy.md
│   └── status.md
├── agents/                   # Subagent definitions
│   └── reviewer.md
├── skills/                   # Agent Skills
│   └── code-review/
│       └── SKILL.md
├── hooks/                    # Event handlers
│   └── hooks.json
├── .mcp.json                 # MCP server configurations
├── .lsp.json                 # LSP server configurations
├── scripts/                  # Hook and utility scripts
│   └── format.sh
└── README.md

Critical: Place commands/, agents/, skills/, hooks/ at plugin root. Only plugin.json goes inside .claude-plugin/.

Minimal Plugin Example

1. Create Structure

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/commands

2. Create Manifest

// my-plugin/.claude-plugin/plugin.json
{
  "name": "my-plugin",
  "description": "Brief description of plugin purpose",
  "version": "1.0.0"
}

3. Add a Command

<!-- my-plugin/commands/hello.md -->
---
description: Greet the user warmly
---

# Hello Command

Greet the user and ask how you can help today.

4. Test Locally

claude --plugin-dir ./my-plugin

Then run: /my-plugin:hello

Component Types

Plugins can include any combination of:

See COMPONENTS.md for detailed documentation of each type.

Manifest Schema

Required and optional fields:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "What the plugin does",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/user/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}

See MANIFEST.md for the complete schema.

Environment Variables

Use ${CLAUDE_PLUGIN_ROOT} for portable paths in hooks and servers:

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
      }]
    }]
  }
}

Distribution

Via Marketplace

1. Create marketplace.json in repository
2. Host on GitHub/GitLab
3. Users add via /plugin marketplace add
4. Users install via /plugin install plugin-name@marketplace

Team Configuration

Add to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "team-plugins": {
      "source": {
        "source": "github",
        "repo": "org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "deploy-tools@team-plugins": true
  }
}

Private Repository Support (2.1.5+)

Distribute plugins via private repositories using authentication tokens:

Set in shell config or when running Claude Code:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

See DISTRIBUTION.md for complete distribution guide.

Workflow: Create a Plugin

Prerequisites

• Claude Code 1.0.33+ installed
• Clear purpose for plugin
• Components identified

Steps

1. Create Structure

   • Create plugin directory
   • Create .claude-plugin/ subdirectory
   • Create component directories as needed

2. Create Manifest

   • Add plugin.json with name, description, version
   • Add author and metadata

3. Add Components

   • Create commands in commands/
   • Create agents in agents/
   • Create skills in skills/*/SKILL.md
   • Configure hooks in hooks/hooks.json
   • Configure MCP in .mcp.json
   • Configure LSP in .lsp.json

4. Test Locally

   • Run claude --plugin-dir ./my-plugin
   • Test each command
   • Verify agents in /agents
   • Confirm hooks fire correctly

5. Prepare Distribution

   • Add README.md
   • Create marketplace.json
   • Push to repository

Validation

• Commands appear with namespace prefix
• All components load without errors
• Scripts are executable (chmod +x)
• Paths use ${CLAUDE_PLUGIN_ROOT}

CLI Commands

# Install plugin
claude plugin install plugin-name@marketplace --scope user

# Uninstall plugin
claude plugin uninstall plugin-name@marketplace

# Enable/disable plugin
claude plugin enable plugin-name@marketplace
claude plugin disable plugin-name@marketplace

# Update plugin
claude plugin update plugin-name@marketplace

# Debug loading
claude --debug

Common Mistakes

Reference Files