Creating Plugins

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

Quick Reference

.claude-plugin/plugin.json

name

.claude-plugin/

/plugin-name:command

claude --plugin-dir ./my-plugin

Plugin vs Standalone

Choose the right approach for your use case:

.claude/

/hello

.claude-plugin/plugin.json

/plugin-name:hello

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/

plugin.json

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

commands/

agents/

skills/*/SKILL.md

hooks/hooks.json

.mcp.json

.lsp.json

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}

{
  "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:

GITHUB_TOKEN

GH_TOKEN

repo

GITLAB_TOKEN

GL_TOKEN

read_repository

BITBUCKET_TOKEN

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

.claude-plugin/

${CLAUDE_PLUGIN_ROOT}

chmod +x script.sh

#!/bin/bash

Reference Files