plugin-development

What this skill does

# Plugin Development Complete Guide

Building Claude Code plugins means creating directories, manifests, and markdown files that extend Claude's capabilities through commands, skills, agents, and hooks.

## Plugin Anatomy

Every plugin follows this directory structure:

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json               # Manifest (REQUIRED)
├── commands/                      # Slash commands
│   ├── index.json                # Command index (optional)
│   └── my-command.md
├── skills/                        # Knowledge packs
│   ├── skill-name/
│   │   └── SKILL.md
│   └── another-skill/
│       └── SKILL.md
├── agents/                        # Specialized workers
│   ├── index.json                # Agent index (optional)
│   ├── my-agent.md
│   └── another-agent.md
├── hooks/                         # Lifecycle scripts
│   ├── hooks.json                # Hook configuration
│   ├── my-hook.sh
│   └── scripts/
│       └── helper.sh
├── mcp-server/                    # Optional: custom MCP server
│   ├── src/
│   │   └── index.js
│   ├── package.json
│   └── dist/
├── CLAUDE.md                      # Plugin routing guide (recommended)
├── CONTEXT_SUMMARY.md             # Bootstrap context (recommended, 700 tokens max)
└── README.md                      # Marketplace documentation
```

## Manifest Schema (plugin.json)

Located at `.claude-plugin/plugin.json`, the manifest defines plugin identity, permissions, and capabilities.

### Required Fields

| Field | Type | Example |
|-------|------|---------|
| `$schema` | string | `"https://claude.local/schemas/plugin.schema.json"` |
| `name` | string | `"my-awesome-plugin"` |
| `version` | string | `"1.0.0"` (semver) |
| `description` | string | One-line summary (50-80 chars) |
| `author.name` | string | Your name or org |
| `license` | string | `"MIT"` or other SPDX |
| `permissions.requires` | string[] | Minimum permissions needed |

### Example Manifest

```json
{
  "$schema": "https://claude.local/schemas/plugin.schema.json",
  "name": "my-awesome-plugin",
  "version": "1.0.0",
  "description": "Does something amazing with Claude Code",
  "author": {
    "name": "Your Name"
  },
  "license": "MIT",
  "repository": "https://github.com/user/my-awesome-plugin",
  "keywords": [
    "automation",
    "productivity",
    "development"
  ],
  "permissions": {
    "requires": [
      "read",
      "write"
    ],
    "optional": [
      "bash",
      "agent",
      "mcp"
    ]
  },
  "capabilities": {
    "provides": [
      "my-custom-capability"
    ],
    "requires": []
  },
  "contextEntry": "CONTEXT_SUMMARY.md",
  "context": {
    "entry": "CONTEXT_SUMMARY.md",
    "title": "My Awesome Plugin",
    "summary": "Essential context for using the plugin",
    "tags": [
      "automation",
      "claude-code"
    ],
    "bootstrapFiles": [
      "CONTEXT_SUMMARY.md"
    ],
    "maxTokens": 700,
    "excludeGlobs": [
      "**/node_modules/**",
      "**/.git/**"
    ],
    "lazyLoadSections": [
      "CLAUDE.md",
      "commands/advanced.md",
      "skills/expert-mode/SKILL.md"
    ]
  }
}
```

### Manifest Fields Explained

**`$schema`**: Validates against Claude's plugin schema. Use as shown above.

**`name`**: Unique identifier (lowercase, hyphens). Used in `claude plugin install` commands.

**`version`**: Semantic versioning. Increment when publishing updates (1.0.0 → 1.0.1 for patches, 1.1.0 for features, 2.0.0 for breaking changes).

**`permissions.requires`**: Minimum permissions needed. Plugin will not load without these:
- `read` — read files
- `write` — write files
- `bash` — execute shell commands
- `agent` — spawn subagents
- `mcp` — use MCP servers
- `network` — external HTTP

**`permissions.optional`**: Nice-to-have permissions. Plugin works without them but features are limited.

**`capabilities.provides`**: Custom capabilities your plugin exposes. Use for plugin discovery and dependency resolution.

**`contextEntry`**: Points to the bootstrap file. Always `"CONTEXT_SUMMARY.md"`.

**`context.bootstrapFiles`**: Files loaded into context when plugin installs. Keep to 700 tokens.

**`context.lazyLoadSections`**: Files loaded on-demand when user references them. Helps large plugins stay responsive.

**`context.excludeGlobs`**: Patterns to exclude from context scanning (node_modules, build artifacts, etc.).

## Command Authoring

Commands are markdown files in the `commands/` directory with YAML frontmatter and implementation body.

### Command Frontmatter Schema

```yaml
---
name: my-command
intent: What this command does (one sentence)
inputs:
  - name: description
  - task: what the user wants
  - query: optional search term
flags:
  - name: force
    type: boolean
    description: Skip confirmations
  - name: output
    type: choice
    choices: [json, text, html]
    description: Output format
risk: low
cost: low
tags:
  - my-plugin
  - productivity
---
```

### Command Body Structure

After frontmatter, the body contains:

1. **Usage Examples** (code blocks with bash syntax)
2. **Operating Protocol** (numbered phases)
3. **Output Contract** (what the command produces)

### Full Command Example

```yaml
---
name: batch-process
intent: Process multiple files with transformation rules
inputs:
  - files: pattern matching files to process
  - rule: transformation function (e.g., "uppercase", "snake_case")
flags:
  - name: dry-run
    type: boolean
    description: Show changes without applying
  - name: workers
    type: string
    description: Number of parallel workers (default 4)
risk: medium
cost: medium
tags:
  - my-plugin
  - batch
---

# Batch Process Command

Process multiple files with transformation rules applied in parallel.

## Usage

```bash
/batch-process --files "src/**/*.ts" --rule uppercase
/batch-process --files "*.md" --rule snake_case --dry-run
/batch-process --files "src/**/*.js" --rule lowercase --workers 8
```

## Operating Protocol

1. **Parse** input flags and file pattern
2. **Validate** files exist and are readable
3. **Check dry-run** — if set, show preview without modifying
4. **Scan** matching files into queue
5. **Apply rule** to each file (parallel if workers > 1)
6. **Report** changes: files modified, skipped, failed
7. **Rollback** if failures exceed threshold (--continue-on-error overrides)

## Output Contract

Returns JSON object:
```json
{
  "processed": 42,
  "modified": 40,
  "skipped": 2,
  "failed": 0,
  "duration_ms": 1234,
  "files": [
    {"path": "src/file.ts", "status": "modified", "size_before": 100, "size_after": 120}
  ]
}
```
```

### Command Naming

Prefix commands with plugin name for namespacing:
- Good: `/my-plugin-batch`, `/my-plugin-audit`
- Avoid: `/batch`, `/process` (too generic)

## Skill Authoring

Skills are knowledge packs in `skills/SKILLNAME/SKILL.md` with frontmatter and progressive loading.

### Skill Frontmatter

```yaml
---
name: my-skill
description: What this skill teaches (one sentence)
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
triggers:
  - use my skill
  - teach me about skill
  - how to use skill
disable-model-invocation: false
---
```

Set `disable-model-invocation: true` for user-only reference skills (no model can invoke them).

### Skill Body Structure

1. **Goal** (why someone uses this skill)
2. **Core Loop** (numbered steps, 5-10 steps typical)
3. **Examples** (real code snippets)

### Full Skill Example

```yaml
---
name: database-migrations
description: Safely design and test database migrations with rollback paths
allowed-tools:
  - Read
  - Write
  - Bash
triggers:
  - database migration
  - db migration
  - migration strategy
  - rollback plan
---

# Database Migrations

Design, test, and execute database migrations safely with automatic rollback paths.

## Goal

Write migrations that are **testable**, **reversible**, and **traceable**. Catch issues in development, not production.

## Core Loop

1. **Analyze** existing schema using introspection (PRAGMA for SQLite, DESCRIBE for MySQL)
2.