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:

Create directory:
```
my-plugin/
```

Create

.claude-plugin/plugin.json

with at minimum:

json

{
  "name": "my-plugin"
}

Add components (commands, agents, skills, hooks, or MCP servers)

Test locally:

/plugin install file:///absolute/path/to/my-plugin

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:

json

{
  "name": "my-plugin"
}

Complete annotated manifest:

json

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

markdown

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

markdown

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

markdown

---
name: agent-name
description: When and why to use this agent (critical for auto-delegation)
tools: Read, Edit, Write, Grep, Glob, Bash
model: opus
---

# Agent Name

Detailed instructions and system prompt for this agent.

## Responsibilities
- Task 1
- Task 2

## Tools Available
- Read: File operations
- Grep: Code search
- Bash: Shell commands

## Workflow
1. Step 1
2. Step 2

Frontmatter fields:

```
name
```
- Required: kebab-case identifier
```
description
```
- Required: Max 1024 chars, used for auto-delegation
```
tools
```
- Comma-separated list of allowed tools
```
model
```
- Optional:
```
haiku
```
,
```
sonnet
```
, or
```
opus
```

Complete example (

agents/security-auditor.md

markdown

---
name: security-auditor
description: Use when reviewing code for security vulnerabilities, analyzing authentication flows, or checking for common security anti-patterns like SQL injection, XSS, or insecure dependencies
tools: Read, Grep, Glob, Bash
model: opus
---

# Security Auditor Agent

You are a security expert specializing in web application security and secure coding practices.

## Your Responsibilities

1. Identify security vulnerabilities (SQL injection, XSS, CSRF, etc.)
2. Review authentication and authorization logic
3. Check for insecure dependencies
4. Verify input validation and sanitization
5. Review cryptographic implementations

## Workflow

1. **Scan for patterns:** Use Grep to find common vulnerability patterns
2. **Read suspicious code:** Use Read to examine flagged files
3. **Check dependencies:** Use Bash to run security audit tools
4. **Report findings:** Provide severity ratings and remediation steps

## Common Vulnerability Patterns

- SQL injection: String concatenation in queries
- XSS: Unescaped user input in templates
- CSRF: Missing CSRF tokens
- Auth bypass: Missing authorization checks
- Hardcoded secrets: API keys, passwords in code

## Reporting Format

For each finding:
- **Severity:** Critical/High/Medium/Low
- **Location:** `file:line`
- **Issue:** What's vulnerable
- **Impact:** What attacker could do
- **Fix:** How to remediate

Creating Skills

REQUIRED SUB-SKILL: Use

writing-skills

for complete guidance on skill structure, testing, and deployment.

Skills follow a specific structure.

File location:

skills/my-skill/SKILL.md

Minimal template:

markdown

---
name: my-skill-name
description: Use when [specific triggers] - [what it does]
---

# Skill Name

## Overview
Core principle in 1-2 sentences.

## When to Use
- Symptom 1
- Symptom 2
- When NOT to use

## Quick Reference
[Table or bullets for common operations]

## Implementation
[Code examples, patterns]

## Common Mistakes
[What goes wrong + fixes]

Key principles:

```
name
```
uses only letters, numbers, hyphens (no special chars)
```
description
```
starts with "Use when..." in third person
Keep token-efficient (<500 words if frequently loaded)
One excellent example beats many mediocre ones
Use
```
writing-skills
```
skill for complete guidance

Creating Hooks

File location:

hooks/hooks.json

or inline in

plugin.json

Standalone hooks file:

json

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "Bash",
      "command": "echo 'About to run: $CLAUDE_TOOL_NAME'"
    },
    {
      "event": "PostToolUse",
      "matcher": "Edit|Write",
      "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
    },
    {
      "event": "SessionStart",
      "matcher": "*",
      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh"
    }
  ]
}

Hook events:

```
PreToolUse
```
- Before tool execution (can block)
```
PostToolUse
```
- After tool execution
```
UserPromptSubmit
```
- When user submits prompt
```
Stop
```
- When Claude finishes responding
```
SessionStart
```
- Session initialization
```
SessionEnd
```
- Session cleanup
```
Notification
```
- On Claude Code notifications
```
SubagentStop
```
- When subagent completes
```
PreCompact
```
- Before context compaction

Matcher patterns:

Specific tool:
```
"Bash"
```
Multiple tools:
```
"Edit|Write"
```
All tools:
```
"*"
```

Environment variables:

```
$CLAUDE_EVENT_TYPE
```
- Event type
```
$CLAUDE_TOOL_NAME
```
- Tool being used
```
$CLAUDE_TOOL_INPUT
```
- Tool input (JSON)
```
$CLAUDE_FILE_PATHS
```
- Space-separated file paths

Creating MCP Server Configs

File location:

.mcp.json

at plugin root or inline in

plugin.json

Standalone .mcp.json:

json

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}",
        "API_KEY": "${API_KEY:-default-key}"
      }
    },
    "web-scraper": {
      "command": "npx",
      "args": ["web-mcp-server", "--port", "3000"]
    }
  }
}

Configuration fields:

```
command
```
- Executable path or command name
```
args
```
- Array of arguments
```
env
```
- Environment variables (supports
```
${VAR}
```
or
```
${VAR:-default}
```
)

Special variable:

```
${CLAUDE_PLUGIN_ROOT}
```
- Resolves to plugin root directory

Setting Up Dev Marketplace

For local development, create a marketplace to organize your plugins:

File:

dev-marketplace/.claude-plugin/marketplace.json

json

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "my-dev-marketplace",
  "version": "1.0.0",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "metadata": {
    "description": "Local development marketplace for my plugins",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "my-plugin-one",
      "version": "1.0.0",
      "description": "What this plugin does",
      "source": "./plugins/my-plugin-one",
      "category": "development",
      "author": {
        "name": "Your Name",
        "email": "you@example.com"
      }
    },
    {
      "name": "my-plugin-two",
      "version": "0.1.0",
      "description": "Experimental plugin",
      "source": "./plugins/my-plugin-two",
      "category": "productivity",
      "strict": false
    }
  ]
}

Directory structure:

dev-marketplace/
�� .claude-plugin/
   �� marketplace.json
�� plugins/
    �� my-plugin-one/
       �� .claude-plugin/
          �� plugin.json
       �� commands/
    �� my-plugin-two/
        �� .claude-plugin/
           �� plugin.json
        �� agents/

Install dev marketplace:

bash

/plugin marketplace add file:///absolute/path/to/dev-marketplace
/plugin browse
/plugin install my-plugin-one@my-dev-marketplace

Plugin entry fields:

```
name
```
- Required: plugin identifier
```
source
```
- Required: relative path or git URL
```
version
```
- Recommended: semantic version
```
description
```
- Recommended: brief description
```
category
```
- Optional: development, productivity, security, etc.
```
author
```
- Optional: author details
```
strict
```
- Optional: default
```
true
```
(requires plugin.json), set
```
false
```
to use marketplace entry as manifest

Source formats:

json

// Local relative path
"source": "./plugins/my-plugin"

// GitHub repository
"source": {
  "source": "github",
  "repo": "owner/repo"
}

// Git URL
"source": {
  "source": "url",
  "url": "https://gitlab.com/team/plugin.git"
}

Naming Conventions

Use kebab-case everywhere:

Plugin names:
```
my-awesome-plugin
```
Command names:
```
review-code
```
Agent names:
```
security-auditor
```
Skill names:
```
test-driven-development
```

Filename mapping:

```
commands/my-command.md
```
�
```
/my-command
```

commands/project/build.md

�

/plugin-name:project:build

```
agents/code-reviewer.md
```
� agent name
```
code-reviewer
```
```
skills/my-skill/SKILL.md
```
� skill name
```
my-skill
```

Testing Locally

Development workflow:

Create plugin structure:

bash

mkdir -p my-plugin/.claude-plugin
echo '{"name":"my-plugin"}' > my-plugin/.claude-plugin/plugin.json

Add components (commands, agents, skills)

Install locally:

bash

/plugin install file:///absolute/path/to/my-plugin

Test functionality:

bash

/my-command arg1 arg2
# Use Task tool with your agent
# Use Skill tool with your skill

Iterate:
- Edit plugin files
- Run
```
/plugin reload
```
- Test again

Using dev marketplace:

Create marketplace structure

Add marketplace:

bash

/plugin marketplace add file:///absolute/path/to/dev-marketplace

Browse and install:

bash

/plugin browse
/plugin install my-plugin@my-dev-marketplace

Common Mistakes

Issue	Symptom	Fix
Missing `.claude-plugin/`	Plugin not recognized	Create `.claude-plugin/plugin.json` at root
Invalid plugin.json	Parse error on load	Validate JSON syntax, ensure `name` field exists
Wrong tool name	Tool not available in command/agent	Check spelling: `Read` , `Grep` , `Glob` , `Bash` , `Edit` , `Write`
Description too long	Warning or truncation	Keep under 1024 characters total
Not using third person	Description sounds wrong	Use "Use when..." not "I will..."
Absolute paths in plugin.json	Breaks on other machines	Use relative paths or `${CLAUDE_PLUGIN_ROOT}`
Forgetting `/plugin reload`	Changes not visible	Run `/plugin reload` after edits
Command not found	Slash command doesn't work	Check filename matches expected command, reload plugin
Agent not auto-delegated	Agent never gets used	Improve `description` with specific triggers and symptoms

Distribution

For production/team use:

Push plugin to Git repository (GitHub, GitLab, etc.)
Create or update team's marketplace repository
Add plugin entry to marketplace.json

Team members install:

bash

/plugin marketplace add user-or-org/marketplace-repo
/plugin install plugin-name@marketplace-name

For public distribution:

Refer to official Claude Code documentation for publishing to public marketplaces.

Reference Links

Official plugin docs: https://docs.claude.com/en/docs/claude-code/plugins
Plugin reference: https://docs.claude.com/en/docs/claude-code/plugins-reference
MCP servers: https://docs.claude.com/en/docs/claude-code/mcp-servers

creating-a-plugin

NPX Install

Tags

SKILL.md Content

Creating a Plugin

Overview

Quick Start Checklist

Directory Structure

Component Reference

plugin.json Format

Creating Commands

Creating Agents

Creating Skills

Creating Hooks

Creating MCP Server Configs

Setting Up Dev Marketplace

Naming Conventions

Testing Locally

Common Mistakes

Distribution

Reference Links