name	plugin-maker
description	Create, validate, and maintain Claude Code plugins. Use when the user wants to create a plugin, add a plugin, make a plugin, build a plugin, or mentions plugin creation. Also use when adding commands, agents, skills, or hooks to existing plugins, configuring plugin.json manifests, or debugging plugin discovery.
allowed-tools	Read Write Edit Bash Glob Grep

Plugin Maker

Create discoverable Claude Code plugins that bundle commands, agents, skills, hooks, and MCP configurations.

Core Principles

1. Plugins bundle components: A plugin is a container for related commands, agents, skills, hooks, and MCP configs
2. Manifest-driven discovery: The .claude-plugin/plugin.json file makes the plugin discoverable
3. Convention over configuration: Standard directory names enable automatic component discovery
4. Plugins vs Skills: Use plugins when bundling multiple component types; use standalone skills for single capabilities

Plugin Structure

Warning: Do not place plugin.json directly in the plugin directory. It must be inside the .claude-plugin/ subdirectory for the plugin to be discovered.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: manifest file (MUST be here)
├── README.md                 # Recommended: documentation
├── commands/                 # Slash commands (*.md)
│   ├── my-command.md
│   └── help.md
├── agents/                   # Subagent definitions (*.md)
│   └── my-agent.md
├── skills/                   # Skills (subdirs with SKILL.md)
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # Hook configurations
│   ├── hooks.json
│   └── handler.py
├── .mcp.json                 # MCP server configuration
└── .lsp.json                 # LSP server configuration

Quick Template: plugin.json

Every plugin requires .claude-plugin/plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description of what this plugin does"
}

Optional author field for attribution:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description of what this plugin does",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  }
}

Version format: Use semantic versioning (MAJOR.MINOR.PATCH). See Manifest Reference for semantic versioning, component path customization, and metadata fields.

Creating a Plugin

Step 1: Create Directory Structure

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

Step 2: Create plugin.json

Create .claude-plugin/plugin.json with required fields:

{
  "name": "my-plugin",
  "description": "What this plugin does"
}

Step 3: Add Components

Add the components your plugin needs (see Component Quick Reference below).

Step 4: Test with --plugin-dir

Use the --plugin-dir flag to test your plugin without installing it:

claude --plugin-dir ./my-plugin

This loads your plugin for the current session only, allowing rapid iteration.

Step 5: Validate Structure

# Check manifest exists and is valid JSON
cat ./my-plugin/.claude-plugin/plugin.json | jq .

# List all components
ls -la ./my-plugin/

Step 6: Test Discovery

Ask Claude to use your plugin's commands or agents to verify discovery works.

Component Quick Reference

Commands (commands/*.md)

Slash commands users invoke explicitly. Plugin commands are namespaced as /plugin-name:command-name.

---
description: What this command does
argument-hint: [optional-args]
allowed-tools: ["Read", "Write", "Bash"]
---

# Command Name

Instructions for Claude when this command is invoked.

The user's input is available as $ARGUMENTS.

**Advanced argument access:**
- `$ARGUMENTS` - Full argument string
- `$1`, `$2`, `$3` - Individual arguments (space-separated)

Fields:

Field	Required	Description
description	Yes	Shown in /help and command completion
argument-hint	No	Hint text for arguments (e.g., [file-path])
allowed-tools	No	Restrict available tools (JSON array)
disable-model-invocation	No	If true, only explicit /command triggers it
model	No	Override model: inherit, sonnet, opus, haiku

Agents (agents/*.md)

Specialized subagents for parallel or delegated work.

---
name: my-agent
description: Use this agent when analyzing code for security issues. Examples: <example>Context: User asks about security\nuser: "Check this file for vulnerabilities"\nassistant: "I'll analyze with the security agent"</example>
model: sonnet
color: yellow
tools: ["Read", "Grep", "Glob"]
---

You are an expert at [specific task].

## Your Role

Detailed instructions for the agent...

Fields:

Field	Required	Description
name	Yes	Agent identifier (lowercase, hyphens)
description	Yes	When to use. Include Examples tags: <example>Context: ...\nuser: "..."\nassistant: "..."</example>
model	No	inherit, sonnet, opus, haiku
color	No	Visual indicator: yellow, blue, green, etc.
tools	No	Array of available tools

Triggering Tip: Use <example> tags in descriptions for complex use cases. Include context, user message, and assistant response to guide invocation.

Skills (skills/skill-name/SKILL.md)

Model-invoked capabilities that Claude activates based on context. Plugin skills are namespaced as /plugin-name:skill-name.

---
name: my-skill
description: What this skill does. Use when user mentions [trigger terms].
---

# Skill Name

Instructions...

Hooks (hooks/hooks.json)

Event-driven automation scripts. Use for validation, context injection, and workflow automation.

Hook Types:

• Prompt-based (recommended): LLM-driven decisions with "type": "prompt"
• Command-based: Bash scripts with "type": "command"

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "prompt",
        "prompt": "Validate file write safety. Check: path traversal, credentials. Return 'approve' or 'deny'."
      }]
    }],
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "prompt",
        "prompt": "Verify task completion: tests run, build succeeded. Return 'approve' or 'block'."
      }]
    }]
  }
}

Available Events:

Event	Trigger
PreToolUse	Before any tool executes
PostToolUse	After a tool executes
UserPromptSubmit	When user submits a prompt
Stop	When Claude wants to stop
SubagentStop	When subagent wants to stop
SessionStart	Session begins
SessionEnd	Session ends
PreCompact	Before context compaction
Notification	User notification sent

Important: Use ${CLAUDE_PLUGIN_ROOT} for paths in hook commands.

See Hook Development Guide for comprehensive patterns.

MCP Configuration (.mcp.json)

Integrate Model Context Protocol servers for additional tools:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-server/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Server types: stdio (local), SSE (hosted/OAuth), HTTP (REST), WebSocket (real-time). Tools appear as mcp__plugin_<plugin-name>_<server-name>__<tool-name>.

See MCP Integration Guide for server types, tool naming, and authentication patterns.

Plugin Settings (.claude/plugin-name.local.md)

Store per-project configuration with YAML frontmatter:

---
enabled: true
strict_mode: false
max_retries: 3
---

# Plugin Configuration

Settings documentation here.

Usage:

• Read from hooks, commands, and agents
• Control plugin behavior per-project
• Store state and configuration
• Should be in .gitignore

See Plugin Settings Guide for parsing techniques and patterns.

LSP Configuration (.lsp.json)

Configure Language Server Protocol servers for enhanced editor support:

{
  "lspServers": {
    "my-lsp": {
      "command": "my-language-server",
      "args": ["--stdio"],
      "filetypes": ["mylang"]
    }
  }
}

Fields:

Field	Required	Description
command	Yes	The LSP server executable
args	No	Command-line arguments
filetypes	Yes	File extensions to activate for

Plugin Locations

Location	Purpose
--plugin-dir ./path	Development/testing (primary workflow)
~/.claude/plugins/	Personal plugins (installed)
.claude/plugins/	Project plugins (committed to git)

When to Create a Plugin

Standalone Skill vs Plugin Comparison

Feature	Standalone Skill	Plugin
Simplest option	One SKILL.md file	Multiple files/directories
Commands	No	Yes
Multiple skills	No	Yes
Agents	No	Yes
Hooks	No	Yes
MCP servers	No	Yes
LSP servers	No	Yes
Namespacing	None	/plugin-name:*
Distribution	Copy file	Package directory

Create a plugin when:

• You need multiple component types (commands + agents, skills + hooks, etc.)
• You want to bundle and distribute related functionality
• Your team needs shared tooling with consistent behavior

Don't create a plugin when:

• You only need a single skill (use standalone skill instead)
• You only need a single command (consider a skill or CLAUDE.md instruction)
• The functionality is project-specific and simple

Naming Conventions

Item	Convention	Example
Plugin directory	lowercase-hyphenated	my-plugin
plugin.json name	matches directory	"name": "my-plugin"
Commands directory	plural commands/	not command/
Agents directory	plural agents/	not agent/
Skills directory	plural skills/	not skill/
Hooks directory	singular hooks/	with hooks.json inside

Quick Reference

Create:

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

Test during development:

claude --plugin-dir ./my-plugin

Validate manifest:

cat ./my-plugin/.claude-plugin/plugin.json | jq .

Install plugin:

cp -r ./my-plugin ~/.claude/plugins/

List installed plugins:

ls ~/.claude/plugins/*/
ls .claude/plugins/*/

Additional Resources

• Hook Development Guide - Events, prompt/command hooks, 7 proven patterns
• MCP Integration Guide - Server types, tool naming, authentication
• Manifest Reference - plugin.json fields, semantic versioning, component paths
• Plugin Settings Guide - Configuration files with YAML frontmatter
• Validation checklists - Frontmatter reference, hook schema validation
• Common mistakes - 30 common issues with MCP and hooks
• Complete plugin examples
• Copy-paste templates - Commands, agents, hooks with patterns