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