Creating Plugins

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

Quick Reference

Element	Requirement
Manifest location	.claude-plugin/plugin.json
Required field	name (kebab-case)
Component dirs	At plugin root, NOT inside .claude-plugin/
Command naming	/plugin-name:command (namespaced)
Testing	claude --plugin-dir ./my-plugin

Plugin vs Standalone

Choose the right approach for your use case:

Approach	Command Names	Best For
Standalone (.claude/)	/hello	Personal workflows, single project
Plugin (.claude-plugin/plugin.json)	/plugin-name:hello	Sharing, distribution, reuse

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:

Component	Location	Format
Commands	commands/	Markdown with frontmatter
Agents	agents/	Markdown with capabilities
Skills	skills/*/SKILL.md	Markdown with YAML frontmatter
Hooks	hooks/hooks.json or inline	JSON configuration
MCP Servers	.mcp.json or inline	JSON configuration
LSP Servers	.lsp.json or inline	JSON configuration

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": "[email protected]"
  },
  "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:

Provider	Environment Variable	Notes
GitHub	GITHUB_TOKEN or GH_TOKEN	PAT with repo scope
GitLab	GITLAB_TOKEN or GL_TOKEN	Token with read_repository scope
Bitbucket	BITBUCKET_TOKEN	App password or repo access 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

Mistake	Fix
Components inside .claude-plugin/	Move to plugin root
Absolute paths in hooks	Use ${CLAUDE_PLUGIN_ROOT}
Scripts not executable	Run chmod +x script.sh
Missing shebang	Add #!/bin/bash first line
Referencing parent dirs	Use symlinks or restructure

Reference Files

File	Contents
MANIFEST.md	Complete manifest.json documentation
COMPONENTS.md	All component type specifications
DISTRIBUTION.md	Marketplace and team distribution