plugin-development

name	plugin-development
description	Use when creating Claude Code plugins, writing skills, building commands, developing agents, or asking about "plugin development", "create skill", "write command", "build agent", "SKILL.md", "plugin structure", "progressive disclosure"
version	1.0.0

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