creating-a-plugin

What this skill does

# 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:
   ```json
   {
     "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:**
```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": "[email protected]",
    "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.

**Fi