plugin-sdk-patterns

# Plugin SDK Patterns

## Overview

This skill documents unified patterns and templates for creating consistent, professional Claude Code plugins. Following these patterns ensures your plugins integrate seamlessly with Claude Code's ecosystem and provide a predictable developer experience.

### Why Standardized Plugin Patterns Matter

**Consistency**: Users expect the same structure across all plugins, making them easier to learn and use.

**Maintainability**: Standard patterns make it easier to update and extend plugins over time.

**Discoverability**: Consistent naming and structure helps users find what they need quickly.

**Quality**: Templates enforce best practices and reduce common errors.

**Collaboration**: Teams can work together more effectively with shared conventions.

### The Builder Pattern Approach

Claude Code plugins follow a **builder pattern** where components (skills, commands, agents, hooks) are modular and composable:

- Each component is self-contained in its own directory
- Components declare their metadata via frontmatter
- The plugin.json manifest ties everything together
- Hooks provide lifecycle integration points

### Plugin Anatomy

```
my-plugin/
├── plugin.json              # Plugin manifest (required)
├── README.md                # User-facing documentation
├── DEPENDENCIES.md          # External dependencies (if any)
├── skills/                  # Reusable knowledge modules
│   ├── skill-one/
│   │   └── SKILL.md
│   └── skill-two/
│       └── SKILL.md
├── commands/                # Interactive commands
│   ├── command-one.md
│   └── command-two.md
├── agents/                  # Autonomous agents
│   ├── agent-one.md
│   └── agent-two.md
├── hooks/                   # Lifecycle hooks (optional)
│   └── hooks.json
├── mcp-servers/            # MCP server configurations (optional)
│   └── servers.json
└── examples/               # Example workflows (optional)
    └── example-workflow.md
```

## Plugin Manifest (plugin.json) Template

### Complete Template

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description of what the plugin does",
  "author": "Your Name <email@example.com>",
  "license": "MIT",
  "homepage": "https://github.com/yourusername/your-repo",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/your-repo.git"
  },
  "tags": ["category1", "category2", "category3"],
  "keywords": ["keyword1", "keyword2", "keyword3"],
  "skills": [
    {
      "name": "skill-one",
      "path": "skills/skill-one/SKILL.md",
      "description": "Brief description of skill one"
    },
    {
      "name": "skill-two",
      "path": "skills/skill-two/SKILL.md",
      "description": "Brief description of skill two"
    }
  ],
  "skillBundles": [
    {
      "name": "core-bundle",
      "description": "Core skills for basic functionality",
      "skills": ["skill-one", "skill-two"]
    }
  ],
  "commands": [
    {
      "name": "/command-one",
      "path": "commands/command-one.md",
      "description": "Brief description of command one"
    }
  ],
  "agents": [
    {
      "name": "agent-one",
      "path": "agents/agent-one.md",
      "description": "Brief description of agent one"
    }
  ],
  "hooks": {
    "enabled": true,
    "configPath": "hooks/hooks.json"
  },
  "mcpServers": {
    "enabled": true,
    "configPath": "mcp-servers/servers.json"
  },
  "dependencies": {
    "system": ["node>=18.0.0", "git"],
    "npm": ["package-name@^1.0.0"],
    "plugins": ["other-plugin@marketplace-name"]
  },
  "compatibility": {
    "claudeCode": ">=1.0.0"
  }
}
```

### Field Descriptions

**Core Metadata:**
- `name` (required): Lowercase, hyphen-separated plugin identifier
- `version` (required): Semantic version (MAJOR.MINOR.PATCH)
- `description` (required): One-sentence summary (under 150 characters)
- `author`: Name and email in standard format
- `license`: SPDX license identifier (typically MIT)
- `homepage`: Primary documentation URL
- `repository`: Git repository information

**Discovery:**
- `tags`: Broad categories (e.g., "frontend", "backend", "testing")
- `keywords`: Specific search terms (e.g., "react", "typescript", "api")

**Components:**
- `skills`: Array of skill definitions
- `skillBundles`: Logical groupings of skills for auto-load
- `commands`: Array of command definitions
- `agents`: Array of agent definitions

**Integration:**
- `hooks`: Lifecycle hook configuration
- `mcpServers`: MCP server configuration
- `dependencies`: External requirements
- `compatibility`: Claude Code version requirements

## Skill File Template

### Standard SKILL.md Structure

```markdown
---
name: skill-name
description: Clear, concise description of what this skill teaches. Include trigger keywords and use cases. Trigger keywords - "keyword1", "keyword2", "keyword3".
version: 1.0.0
tags: [category1, category2, category3]
keywords: [keyword1, keyword2, keyword3, keyword4]
plugin: plugin-name
updated: 2026-01-28
---

# Skill Name

## Overview

Brief introduction to the skill and its purpose. Explain when to use this skill and what problems it solves.

### Key Concepts

- **Concept 1**: Brief explanation
- **Concept 2**: Brief explanation
- **Concept 3**: Brief explanation

### When to Use This Skill

- Scenario 1
- Scenario 2
- Scenario 3

## Core Patterns

### Pattern 1: Pattern Name

**Purpose**: Why this pattern exists

**Structure**:
```
Example code or structure
```

**Usage**:
- Step 1
- Step 2
- Step 3

**Best Practices**:
- Do this
- Don't do that

### Pattern 2: Pattern Name

(Same structure as Pattern 1)

## Integration

### With Other Skills

How this skill works alongside other skills in your plugin or ecosystem.

### With Tools

Which Claude Code tools are most relevant:
- Read/Write/Edit for file operations
- Bash for system commands
- Grep/Glob for searching
- Task for delegation

### With External Systems

Any external dependencies or integrations.

## Best Practices

### Do

- ✅ Best practic