plugin-development

What this skill does

# Plugin Development Skill

Comprehensive guide to creating Claude Code plugins following official specifications.

## When to Use

Activate when:
- User wants to create a new plugin
- Discussing plugin architecture
- Questions about plugin structure
- Planning plugin features

## Official Resources

**Always reference**:
- https://code.claude.com/docs/en/plugins - Main plugin documentation
- https://code.claude.com/docs/en/plugins-reference - Complete reference
- https://github.com/anthropics/claude-code/tree/main/plugins - Official examples

## Plugin Architecture

### Directory Structure

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest (REQUIRED)
├── commands/                 # Slash commands
│   ├── start.md
│   └── validate.md
├── skills/                   # Guidance and workflows
│   ├── my-skill/
│   │   └── SKILL.md         # Skills are FOLDERS with SKILL.md
│   └── another-skill/
│       └── SKILL.md
├── agents/                   # Autonomous agents
│   ├── analyzer.md
│   └── validator.md
├── hooks/                    # Event handlers
│   ├── PreToolUse.sh
│   └── SessionStart.sh
└── README.md                 # Documentation (REQUIRED)
```

### plugin.json Format

**Minimal format** (recommended - uses auto-discovery):
```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin does",
  "author": {
    "name": "Your Name"
  }
}
```

**With optional fields**:
```json
{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Clear description of plugin purpose",
  "author": {
    "name": "Your Name"
  },
  "keywords": ["workflow", "development", "tools"],
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo"
  },
  "license": "MIT",
  "dependencies": ["other-plugin"]
}
```

**Important**: Commands, skills, agents, and hooks are **auto-discovered** from their directories. Do NOT list them manually in plugin.json.

## Component Types

### Skills vs Commands

**Both create slash commands**, but skills are preferred for new development:

| Feature          | Commands (`commands/name.md`)      | Skills (`skills/name/SKILL.md`)              |
| :--------------- | :--------------------------------- | :------------------------------------------- |
| **Structure**    | Flat .md file                      | Folder with SKILL.md                         |
| **Invocation**   | `/plugin:command-name`             | `/plugin:skill-name`                         |
| **Supporting**   | Single file only                   | Multiple files in folder                     |
| **Features**     | Basic frontmatter                  | `user-invocable`, `disable-model-invocation` |
| **Status**       | Works, backward compatible         | Preferred, more features                     |
| **Auto-discover**| From `commands/` directory         | From `skills/` directory                     |

**Recommendation**: Use skills for new plugins. Commands still work if you prefer flat files.

### Skills (Preferred)

**Purpose**: Provide guidance, enforce workflows, share knowledge

**When to use**:
- Teaching concepts
- Enforcing methodologies (TDD, API-first)
- Multi-step workflows
- Best practices

**Structure**:
```
skills/
└── skill-name/              # MUST be a folder
    └── SKILL.md             # MUST be named SKILL.md
```

**SKILL.md format**:
```yaml
---
name: skill-name
description: What this skill teaches or enforces
---

# Skill Name

## When to Use
Activate when: [triggering conditions]

## Process
[Step-by-step workflow]

## Examples
[Concrete examples]
```

**Best practices**:
- Use progressive disclosure (simple → detailed)
- Include concrete examples
- Clear triggering conditions
- Actionable guidance, not just theory

### Agents

**Purpose**: Autonomous specialized workers

**When to use**:
- Focused analysis tasks
- Background processing
- Specialized expertise domains
- Repetitive workflows

**Structure**:
```yaml
---
name: agent-name
description: Agent's specialized purpose
color: blue|green|orange|cyan|purple
tools: [Read, Grep, Glob, Bash, Edit, Write]
---

# Agent Name

## Your Role
[Clear role definition]

## Process
[How agent works]

## Output Format
[Expected output structure]
```

**Tool selection**:
- Read-only agents: [Read, Grep, Glob]
- Analysis agents: [Read, Grep, Glob, Bash]
- Implementation agents: [Read, Grep, Glob, Bash, Edit, Write]

### Hooks

**Purpose**: React to events automatically

**When to use**:
- Validation before actions
- Automatic logging
- Workflow enforcement
- Integration points

**Available hooks**:
- PreToolUse - Before any tool execution
- PostToolUse - After tool execution
- SessionStart - Session initialization
- SessionEnd - Session cleanup
- Stop - Before session ends
- SubagentStop - Agent completion
- UserPromptSubmit - After user input
- PreCompact - Before context compression
- Notification - System notifications

**Structure**:
```bash
#!/bin/bash
# hooks/PreToolUse.sh

# Exit 0: allow action
# Exit 1: block action
# Echo to stderr: show message to user
```

## Design Principles

### Single Responsibility
Each plugin should have ONE clear purpose:
- ✓ `task-management` - Task tracking only
- ✓ `tdd-workflow` - TDD enforcement only
- ✗ `super-tool` - Does everything

### Component Selection

**Commands/Skills** (user-invocable workflows):
- User explicitly invokes with `/plugin:name`
- Interactive prompts and questions
- Multi-step guided processes
- Workflow orchestration
- **Choose skills** over commands for new development (more features)

**Agents** (autonomous specialized workers):
- Background processing
- Specialized domain expertise (security, performance)
- Parallel execution tasks
- Focused analysis

**Hooks** (event-driven automation):
- Automatic validation before actions
- Logging and auditing
- Cross-cutting concerns
- Safety checks and guardrails

### Composition Over Monoliths

**Good**: Small focused plugins
```
workflow/          → Workflow routing
tdd-workflow/      → TDD enforcement
sdd-workflow/      → Spec-first enforcement
task-management/   → Task tracking
```

**Bad**: One giant plugin
```
super-workflow/    → Does everything (harder to maintain, test, reuse)
```

## Development Workflow

### 1. Design Phase

**Clarify purpose**:
- What problem does this solve?
- Who is the target user?
- What's the core workflow?

**Choose components**:
- Commands for user actions
- Skills for guidance
- Agents for automation
- Hooks for events

### 2. Implementation Phase

**Start with plugin.json**:
```json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Clear purpose",
  "commands": [],
  "skills": [],
  "agents": []
}
```

**Build incrementally**:
1. Create basic structure
2. Implement one component fully
3. Test it works
4. Add next component
5. Repeat

### 3. Documentation Phase

**README.md must include**:
- What the plugin does
- When to use it
- Installation instructions
- Usage examples
- Component descriptions

### 4. Validation Phase

**Check**:
- [ ] plugin.json valid and complete
- [ ] All referenced components exist
- [ ] Skills are folders with SKILL.md
- [ ] Commands have frontmatter
- [ ] Agents have valid tools/colors
- [ ] README has examples
- [ ] Source attribution if applicable

## Common Patterns

### Workflow Plugin Pattern

Coordinates multi-step processes:
- Skill: Workflow routing logic
- Commands: Start, status, complete
- Agent: Specialized validation

Example: `workflow` plugin

### Methodology Enforcement Pattern

Ensures best practices:
- Skill: Methodology guide (TDD, API-first)
- Commands: Initialize workflow
- Hooks: Block violations

Example: `tdd-workflow` plugin

### Tool Integration Pattern

Wraps external tools:
- Commands: Tool operations
- Agent: Tool-specific tasks
- Hooks: Environment setup

Example: Database management plugin

### Meta Plugin Pattern

Helps create other plugins:
- Commands: Scaffolding operations
- Skills: Development guides
- Age