plugin-sdk-patterns

What this skill does

# 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 protected]>",
  "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 practice 1
- ✅ Best practice 2
- ✅ Best practice 3

### Don't

- ❌ Anti-pattern 1
- ❌ Anti-pattern 2
- ❌ Anti-pattern 3

## Examples

### Example 1: Basic Usage

**Scenario**: Clear description of the use case

**Implementation**:
```
Code or step-by-step example
```

**Result**: Expected outcome

### Example 2: Advanced Usage

(Same structure as Example 1)

## Troubleshooting

### Common Issues

**Issue 1**: Problem description
- **Cause**: Why it happens
- **Solution**: How to fix it

**Issue 2**: Problem description
- **Cause**: Why it happens
- **Solution**: How to fix it

## Summary

### Key Takeaways

- Takeaway 1
- Takeaway 2
- Takeaway 3

### Quick Reference

| Scenario | Pattern to Use | Key Points |
|----------|---------------|------------|
| Scenario 1 | Pattern 1 | Point 1, Point 2 |
| Scenario 2 | Pattern 2 | Point 1, Point 2 |

---

*Inspired by [Source/Project Name]*
```

### Frontmatter Fields

**Required:**
- `name`: Lowercase, hyphen-separated identifier
- `description`: Include trigger keywords and use cases
- `version`: Semantic version
- `plugin`: Parent plugin name
- `updated`: ISO date (YYYY-MM-DD)

**Recommended:**
- `tags`: 3-5 broad categories
- `keywords`: 5-10 specific terms for search

### Section Guidelines

**Overview** (50-100 lines):
- Introduction and purpose
- Key concepts
- When to use

**Core Patterns** (100-200 lines):
- 2-5 main patterns
- Each with purpose, structure, usage, best practices

**Integration** (30-50 lines):
- How it works with other components
- Tool usage recommendations

**Best Practices** (30-50 lines):
- Do/Don't lists
- Common pitfalls

**Examples** (50-100 lines):
- 2-3 concrete examples
- Scenario, implementation, result

**Troubleshooting** (30-50 lines):
- Common issues and solutions

**Summary** (20-30 lines):
- Key takeaways
- Quick reference table

## Command File Template

### Standard Command Structure

```markdown
---
name: /command-name
description: Brief description of what this command does
version: 1.