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

1. Plan - Determine needed components (agents, skills, commands, hooks)
2. Create structure - Set up directories and plugin.json
3. Implement components - Create each component file
4. Add hooks - If automation needed
5. Document - Write README.md
6. Test - Use claude --plugin-dir /path/to/plugin
7. 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