/creating-a-plugin

name: creating-a-plugin
description: Use when creating a new Claude Code plugin or setting up plugin structure - provides complete file organization, manifest format, and component definitions for commands, agents, skills, hooks, and MCP servers
user-invocable: false

Creating a Plugin

Overview

A **Claude Code plugin** packages reusable components (commands, agents, skills, hooks, MCP servers) for distribution. Create a plugin when you have components that work across multiple projects.

**Don't create a plugin for:**

• Project-specific configurations (use `.claude/` in project root)
• One-off scripts or commands
• Experimental features still in development

**Plugin storage locations:**

• Development: Anywhere during development, installed via `file:///` path
• User-level: `~/.claude/plugins/` (after installation)
• Project-level: `.claude/plugins/` (project-specific installations)

Quick Start Checklist

Minimal viable plugin:

1. Create directory: `my-plugin/` 2. Create `.claude-plugin/plugin.json` with at minimum:

   {
     "name": "my-plugin"
   }

3. Add components (commands, agents, skills, hooks, or MCP servers) 4. Test locally: `/plugin install file:///absolute/path/to/my-plugin` 5. Reload: `/plugin reload`

Directory Structure

my-plugin/
 .claude-plugin/
    plugin.json              # Required: plugin manifest
 commands/                    # Optional: slash commands
    my-command.md
 agents/                      # Optional: specialized subagents
    my-agent.md
 skills/                      # Optional: reusable techniques
    my-skill/
        SKILL.md
 hooks/                       # Optional: event handlers
    hooks.json
 .mcp.json                    # Optional: MCP server configs
 README.md                    # Recommended: documentation

**Critical:** The `.claude-plugin/` directory with `plugin.json` inside must exist at plugin root.

Component Reference

| Component | Location | File Format | When to Use | |-----------|----------|-------------|-------------| | Commands | `commands/*.md` | Markdown + YAML frontmatter | Custom slash commands for repetitive tasks | | Agents | `agents/*.md` | Markdown + YAML frontmatter | Specialized subagents for complex workflows | | Skills | `skills/*/SKILL.md` | Markdown + YAML frontmatter | Reusable techniques and patterns | | Hooks | `hooks/hooks.json` | JSON | Event handlers (format code, validate, etc.) | | MCP Servers | `.mcp.json` | JSON | External tool integrations |

plugin.json Format

**Minimal valid manifest:**

{
  "name": "my-plugin"
}

**Complete annotated manifest:**

{
  "name": "my-plugin",                    // Required: kebab-case identifier
  "version": "1.0.0",                     // Recommended: semantic versioning
  "description": "What this plugin does", // Recommended: brief description

  "author": {                             // Optional but recommended
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://github.com/yourname"
  },

  "homepage": "https://github.com/yourname/my-plugin",
  "repository": "https://github.com/yourname/my-plugin",
  "license": "MIT",
  "keywords": ["productivity", "automation"],

  "commands": [                           // Optional: explicit command paths
    "./commands/cmd1.md",
    "./commands/cmd2.md"
  ],

  "agents": [                             // Optional: explicit agent paths
    "./agents/agent1.md"
  ],

  "hooks": [                              // Optional: inline hooks
    {
      "event": "PostToolUse",
      "matcher": "Edit|Write",
      "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
    }
  ],

  "mcpServers": {                         // Optional: inline MCP configs
    "my-server": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/my-server",
      "args": ["--port", "8080"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

**Key points:**

• `name` is required, everything else is optional
• Use `${CLAUDE_PLUGIN_ROOT}` to reference plugin directory
• Commands/agents auto-discovered from `commands/` and `agents/` directories if not listed explicitly
• Skills auto-discovered from `skills/*/SKILL.md` pattern

Creating Commands

**File location:** `commands/my-command.md` creates `/my-command` slash command

**Nested commands:** `commands/feature/sub-command.md` creates `/plugin-name:feature:sub-command`

**Template:**

---
description: Brief description of what this command does
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
argument-hint: "[file-path]"
---

# Command Name

Your command prompt goes here.

You can use:
- $1, $2, etc. for positional arguments
- $ARGUMENTS for all arguments as single string
- @filename to include file contents
- !bash command to execute shell commands

Example implementation instructions...

**Frontmatter fields:**

• `description` - Brief description shown in `/help`
• `allowed-tools` - Comma-separated list: `Read, Grep, Glob, Bash, Edit, Write, TodoWrite, Task`
• `model` - Optional: `haiku`, `sonnet`, or `opus` (defaults to user's setting)
• `argument-hint` - Optional: shown in help text
• `disable-model-invocation` - Optional: `true` to prevent auto-run

**Complete example** (`commands/review-pr.md`):

---
description: Review pull request for security and best practices
allowed-tools: Read, Grep, Glob, Bash
model: opus
argument-hint: "[pr-number]"
---

# Pull Request Review

Review pull request #$1 for:

1. Security vulnerabilities
2. Performance issues
3. Best practices compliance
4. Error handling

Steps:
1. Use Bash to run: gh pr diff $1
2. Use Read to examine changed files
3. Use Grep to search for common anti-patterns
4. Provide structured feedback with file:line references

Focus on critical issues first.

Creating Agents

**File location:** `agents/code-reviewer.md` creates agent named "code-reviewer"

**Template:**