building-plugins

What this skill does

# Building Plugins Skill

You are an expert at creating Claude Code plugins. Plugins are bundled packages that combine agents, skills, commands, and hooks into cohesive, distributable units.

## What is a Plugin?

A **plugin** is a package that bundles related Claude Code components:
- **Agents**: Specialized subagents for delegated tasks
- **Skills**: Auto-invoked expertise modules
- **Commands**: User-triggered slash commands
- **Hooks**: Event-driven automation

Plugins enable users to install complete functionality with a single command.

## When to Create a Plugin vs Individual Components

**Use a PLUGIN when:**
- You want to distribute multiple related components together
- You're building a cohesive feature set or domain expertise
- You want users to install everything with one command
- You need to maintain version compatibility across components
- You're creating a reusable toolkit for a specific domain

**Use INDIVIDUAL COMPONENTS when:**
- You only need a single agent, skill, or command
- Components are unrelated and can be used independently
- You're customizing for a specific project
- You don't plan to distribute or share

## Plugin Creation Process

Creating a plugin involves:
1. Gathering requirements (name, components, metadata)
2. Creating the directory structure
3. Writing the plugin.json manifest
4. Creating each component (agents, skills, commands, hooks)
5. Writing comprehensive README.md
6. Validating the complete plugin

**Component Creation**: Each component type (agents, skills, commands, hooks) should follow its respective best practices. Use the corresponding building-* skills for expertise on creating each type.

## Plugin Structure & Schema

### Directory Structure

```
plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── agents/                  # Optional: Agent definitions
│   ├── agent1.md
│   └── agent2.md
├── skills/                  # Optional: Skill directories
│   ├── skill1/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   ├── references/
│   │   └── assets/
│   └── skill2/
│       └── SKILL.md
├── commands/                # Optional: Slash commands
│   ├── command1.md
│   └── command2.md
├── hooks/                   # Optional: Event hooks
│   ├── hooks.json
│   └── scripts/
├── scripts/                 # Optional: Helper scripts
│   └── setup.sh
├── .mcp.json               # Optional: MCP server configuration
└── README.md               # Required: Documentation
```

### Minimal Plugin Structure

The absolute minimum for a valid plugin:

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── README.md
```

### plugin.json Schema

#### Required Fields

```json
{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "What the plugin does"
}
```

#### Recommended Fields

```json
{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Comprehensive description of plugin functionality",
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "url": "https://github.com/yourname"
  },
  "homepage": "https://github.com/yourname/plugin-name",
  "repository": "https://github.com/yourname/plugin-name",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2", "keyword3"]
}
```

#### Component Registration

```json
{
  "commands": "./commands/",
  "agents": ["./agents/agent1.md", "./agents/agent2.md"],
  "skills": "./skills/",
  "hooks": ["./hooks/hooks.json"]
}
```

**Notes:**
- Use directory paths (`"./commands/"`) to include all files in a directory
- Use file arrays (`["file1.md", "file2.md"]`) to list specific files
- Paths are relative to plugin root directory

> **⚠️ CRITICAL FORMAT WARNING**
>
> **Arrays MUST contain simple path strings, NOT objects!**
>
> ❌ **WRONG** (will silently fail to load):
> ```json
> "commands": [
>   {"name": "init", "path": "./commands/init.md", "description": "..."},
>   {"name": "status", "path": "./commands/status.md"}
> ]
> ```
>
> ✅ **CORRECT**:
> ```json
> "commands": [
>   "./commands/init.md",
>   "./commands/status.md"
> ]
> ```
>
> This applies to **all component arrays**: `agents`, `skills`, `commands`, and `hooks`.
>
> **Also note**: Single-item arrays must still be arrays, not strings:
> - ❌ `"agents": "./agents/my-agent.md"` (string - won't load)
> - ✅ `"agents": ["./agents/my-agent.md"]` (array - correct)

#### Optional: MCP Servers

```json
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-name"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}
```

### Naming Conventions

**Plugin Name:**
- **Lowercase letters, numbers, and hyphens only** (no underscores!)
- **Max 64 characters**
- **Descriptive and domain-specific**
- Examples: `code-review-suite`, `data-analytics-tools`, `git-workflow-automation`

**Component Names:**
- Follow individual component naming rules
- **Agents**: Action-oriented (`code-reviewer`, `test-generator`)
- **Skills**: Gerund form preferred (`analyzing-data`, `reviewing-code`)
- **Commands**: Verb-first (`new-feature`, `run-tests`)
- **Consistency**: Use similar naming patterns within a plugin

### Semantic Versioning

Plugins must follow semantic versioning: `MAJOR.MINOR.PATCH`

- **MAJOR**: Breaking changes (e.g., removed components, changed interfaces)
- **MINOR**: New features (e.g., new commands, enhanced capabilities)
- **PATCH**: Bug fixes and minor improvements

Examples:
- `1.0.0` → Initial release
- `1.1.0` → Added new command
- `1.1.1` → Fixed bug in existing command
- `2.0.0` → Removed deprecated agent (breaking change)

## Creating a Plugin

Follow these steps to create a well-structured plugin:

#### Step 1: Gather Requirements

Ask the user:
1. **Plugin name and purpose**: What will this plugin do?
2. **Target domain**: What problem does it solve?
3. **Components needed**:
   - How many agents? What tasks?
   - How many skills? What expertise?
   - How many commands? What workflows?
   - Any hooks? What events?
4. **Metadata**:
   - Author information
   - License type (MIT, Apache 2.0, etc.)
   - Repository URL
   - Keywords for searchability

#### Step 2: Design Plugin Architecture

Plan the component structure:

**Example: Code Review Plugin**
```
code-review-suite/
├── agents/
│   ├── code-reviewer.md          # Deep code analysis
│   └── security-auditor.md       # Security scanning
├── skills/
│   ├── reviewing-code/           # Always-on review expertise
│   └── detecting-vulnerabilities/ # Security pattern matching
├── commands/
│   ├── review.md                 # /review [file]
│   ├── security-scan.md          # /security-scan
│   └── suggest-improvements.md   # /suggest-improvements
└── hooks/
    └── hooks.json                # Pre-commit validation
```

**Design Principles:**
- **Cohesion**: Components should work together toward a common goal
- **Single Responsibility**: Each component has a clear, focused purpose
- **Minimal Overlap**: Avoid duplicating functionality
- **Progressive Complexity**: Start simple, add features iteratively

#### Step 3: Create Directory Structure

```bash
mkdir -p plugin-name/.claude-plugin
mkdir -p plugin-name/agents
mkdir -p plugin-name/skills
mkdir -p plugin-name/commands
mkdir -p plugin-name/hooks
mkdir -p plugin-name/scripts
```

#### Step 4: Create plugin.json Manifest

Use the plugin.json schema template and populate all fields:

```json
{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Detailed description of what this plugin provides",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://github.com/username"
  },
  "homepage": "https://github.com/username/plugin-name",
  "repository": "https://github.com/username/plugin-name",
  "license": "MIT",
  "keywords": ["domain", "automation", "tools"],
  "commands": "./commands/",
  "agents": "./agents/",
  "skills": "./skills/",
  "hooks": ["./hooks/hooks.json"]
}
```

**Critical Validation:**
- Valid