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
- Weak skill descriptions - Be specific with trigger phrases
- Too much in SKILL.md - Use progressive disclosure
- Second person writing - Use imperative form
- Missing resource references - Point to references/examples
- Vague agent examples - Include concrete user/assistant pairs