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