name: plugin-creator description: >- Use this skill when asked to "create a plugin", "build a new plugin", "make a Claude Code plugin", "scaffold plugin", "plugin structure", "add commands/agents/skills/hooks to plugin", or when helping with plugin development.

Plugin Creator Skill

This skill provides comprehensive guidance for creating Claude Code plugins with proper structure, following official patterns from the Anthropic claude-code repository.

Plugin Directory Structure

A complete Claude Code plugin follows this structure:

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin metadata manifest
├── agents/                  # Optional: Agent definitions (.md files)
│   └── agent-name.md
├── skills/                  # Optional: Skill directories
│   └── skill-name/
│       └── SKILL.md
├── commands/                # Optional: Slash commands (.md files)
│   └── command-name.md
├── hooks/                   # Optional: Event handlers
│   └── hooks.json           # Hook configuration
└── README.md                # Plugin documentation

Plugin Manifest (plugin.json)

Required fields:

name: Plugin identifier (kebab-case, 3-50 chars)

Optional fields:

version: Semantic version (X.Y.Z)
description: Brief description
author: Object with name and optional email
mcpServers: MCP server configurations

Example:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What the plugin does",
  "author": {
    "name": "Your Name",
    "email": "email@example.com"
  }
}

Creating Agents

Agent files go in agents/ directory with .md extension.

Agent frontmatter fields:

name: Agent identifier (required)
description: Triggering conditions with <example> blocks
model: inherit (default), sonnet, opus, or haiku
color: blue, cyan, green, yellow, magenta, red
tools: Array of allowed tools (optional, all tools if omitted)

Agent template:

---
name: my-agent
description: >-
  Use this agent when the user asks to "do something", "perform action",
  or mentions specific keywords.

  <example>
  Context: User wants to perform specific task
  user: "Please do the thing"
  assistant: "I'll use the my-agent agent to help with this."
  <commentary>
  User explicitly requested the functionality this agent provides.
  </commentary>
  </example>
model: inherit
color: green
tools: ["Read", "Write", "Bash"]
---

You are an expert [role] specializing in [domain].

**Core Responsibilities:**
1. First responsibility
2. Second responsibility
3. Third responsibility

**Process:**
1. Analyze the request
2. Plan the approach
3. Execute the solution
4. Verify the results

**Quality Standards:**
- Standard one
- Standard two

**Output Format:**
Describe expected output format here.

Creating Skills

Skills go in skills/ directory, each in its own subdirectory with a SKILL.md file.

Skill frontmatter:

name: Skill identifier (required)
description: When to trigger (with strong trigger phrases)

Skill template:

---
name: my-skill
description: >-
  Use this skill when asked to "specific action", "related task",
  "keyword phrase", or when dealing with [domain].
---

# Skill Name

Brief description of what this skill provides.

## When to Use

- Trigger condition 1
- Trigger condition 2
- Trigger condition 3

## Core Concepts

Explain the main concepts and techniques.

## Best Practices

1. Practice one
2. Practice two
3. Practice three

## Examples

### Example 1: Basic Usage
```code
example code here

Example 2: Advanced Usage

more complex example


## Creating Commands

Commands go in `commands/` directory with `.md` extension.

Command frontmatter:
- `description`: What the command does (shown in `/` menu)
- `argument-hint`: Placeholder text for arguments (optional)
- `allowed-tools`: Array of tools command can use (optional)

Command template:
```markdown
---
description: Brief description of what command does
argument-hint: <optional argument>
allowed-tools: ["Read", "Write", "Bash"]
---

Instructions for Claude when this command is invoked.

You should:
1. Step one
2. Step two
3. Step three

Creating Hooks

Hooks go in hooks/hooks.json and execute on specific events.

Hook events:

PreToolUse: Before tool execution (validate/block)
PostToolUse: After tool execution (audit/react)
Stop: When Claude stops (force continue)
SubagentStop: When subagent stops
SessionStart: When session begins (load context)
SessionEnd: When session ends (cleanup)
UserPromptSubmit: When user submits prompt
PreCompact: Before context compaction
Notification: On notifications

hooks.json template:

{
  "description": "Plugin hooks description",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-write.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
          }
        ]
      }
    ]
  }
}

Hook types:

command: Execute bash script
prompt: LLM-based evaluation (for Stop, SubagentStop)

Important: Use ${CLAUDE_PLUGIN_ROOT} for portable paths within plugin.

Hook Scripts

Create executable scripts in scripts/ directory:

#!/usr/bin/env bash
# scripts/validate-write.sh

# Read JSON input from stdin
INPUT=$(cat)

# Extract fields
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Validation logic
if [[ "$FILE_PATH" == *.env* ]]; then
  echo "Cannot write to .env files" >&2
  exit 2  # Exit 2 = block with message to Claude
fi

exit 0  # Exit 0 = allow

Exit codes:

0: Success, allow action
2: Block action, stderr shown to Claude
Other: Non-blocking error, stderr shown to user

Plugin Creation Workflow

Plan - Determine needed components (agents, skills, commands, hooks)
Create structure - Set up directories and plugin.json
Implement components - Create each component file
Add hooks - If automation needed
Document - Write README.md
Test - Use claude --plugin-dir /path/to/plugin
Validate - Check structure matches specification

Quick Start Commands

Create minimal plugin:

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

Add an agent:

mkdir -p my-plugin/agents
# Create agents/my-agent.md with frontmatter

Add a skill:

mkdir -p my-plugin/skills/my-skill
# Create skills/my-skill/SKILL.md

Add hooks:

mkdir -p my-plugin/hooks my-plugin/scripts
# Create hooks/hooks.json and scripts/*.sh

References

Official plugins: https://github.com/anthropics/claude-code/tree/main/plugins
Plugin documentation: https://code.claude.com/docs/en/plugins
Hooks reference: https://code.claude.com/docs/en/hooks

plugin-creator