Claude Code Plugin Development

Guide for creating effective Claude Code plugins with skills, commands, and agents.

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json         # Plugin metadata
├── skills/
│   └── skill-name/
│       ├── SKILL.md        # Required
│       ├── references/     # Detailed docs
│       ├── examples/       # Working code
│       └── scripts/        # Utilities
├── commands/
│   └── command-name.md
├── agents/
│   └── agent-name.md
└── hooks/
    └── hooks.json

Skill Development

SKILL.md Structure

---
name: skill-name
description: This skill should be used when the user asks to "specific phrase 1", "specific phrase 2", or mentions "keyword". Be specific about triggers.
version: 1.0.0
---

# Skill Title

Core content here (1,500-2,000 words ideal).

## Additional Resources

- **`references/detailed.md`** - Detailed patterns
- **`examples/working.sh`** - Working example

Progressive Disclosure

Level	Content	When Loaded
Metadata	name + description	Always (~100 words)
SKILL.md	Core content	When triggered (<5k words)
References	Detailed docs	As needed (unlimited)

Description Best Practices

Good:

description: This skill should be used when the user asks to "create a hook", "add PreToolUse hook", "validate tool use", or mentions hook events.

Bad:

description: Provides hook guidance.  # Too vague
description: Use this skill for hooks.  # Not third person

Writing Style

Use imperative form, not second person:

# Good
Start by reading the configuration.
Validate the input before processing.

# Bad
You should start by reading...
You need to validate the input...

Command Development

Command Structure

---
name: command-name
description: What the command does
argument-hint: "[optional args]"
---

# Command Title

Instructions for executing the command.

Example Command

---
name: review-pr
description: Review a GitHub PR with detailed code analysis
argument-hint: "[PR number or URL]"
---

# Review PR Command

1. Fetch PR details using `gh pr view`
2. Get changed files with `gh pr diff`
3. Analyze each file for issues
4. Provide summary with recommendations

Agent Development

Agent Structure

---
agent: agent-name
description: |
  When to use this agent with examples:
  <example>
  Context: User situation
  user: "User request"
  assistant: "How assistant responds"
  <commentary>Why this agent is appropriate</commentary>
  </example>
model: sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
color: cyan
---

# Agent Instructions

Detailed instructions for the agent's behavior.

Agent Colors

Valid colors: red, green, yellow, blue, magenta, cyan, white

Hooks Development

hooks.json Structure

{
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": "Write|Edit",
      "type": "prompt",
      "prompt": "Validate code before writing...",
      "timeout": 10000
    }
  ]
}

Hook Events

Event	When Fired
SessionStart	Session begins
PreToolUse	Before tool execution
PostToolUse	After tool execution
Stop	Session ends
Notification	Background task complete

Validation Checklist

Skills:

• SKILL.md has valid YAML frontmatter
• Description uses third person with trigger phrases
• Body is 1,500-2,000 words (detailed content in references/)
• Uses imperative writing style
• Referenced files exist

Commands:

• Has name and description in frontmatter
• Clear instructions for execution
• argument-hint if accepts parameters

Agents:

• Has description with examples
• Specifies model and tools
• Valid color specified
• Detailed behavioral instructions

Common Mistakes

1. Weak skill descriptions - Be specific with trigger phrases
2. Too much in SKILL.md - Use progressive disclosure
3. Second person writing - Use imperative form
4. Missing resource references - Point to references/examples
5. Vague agent examples - Include concrete user/assistant pairs