name: creating-plugins description: Guide for creating full Claude Code plugins that bundle commands, agents, hooks, MCP servers, and LSP servers. Use when building distributable extensions, packaging multiple components together, or preparing plugins for marketplace distribution. allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

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