Creating and Editing Claude Plugins

What this skill does

# Building Claude Code Plugins

This skill provides comprehensive guidance for creating Claude Code plugins that extend Claude with shareable, discoverable functionality.

## What Are Claude Code Plugins?

Plugins are packages of functionality that can be shared across projects and teams. They can contain:
- **Custom slash commands**: User-invoked commands
- **Custom agents**: Specialized agent behaviors
- **Agent skills**: Reusable capabilities agents can invoke
- **Event hooks**: Handlers that trigger on specific events
- **MCP servers**: External tool integrations

Plugins are discoverable through plugin marketplaces and easy to install with `/plugin install`.

## Core Requirements

Every plugin requires exactly one file: `.claude-plugin/plugin.json`

**Minimum valid plugin:**
```json
{
  "name": "my-plugin",
  "version": "1.0.0"
}
```

All other components (commands, agents, skills, hooks, MCP servers) are optional.

## Quick Start

1. **Create plugin directory**: `mkdir my-plugin`
2. **Create manifest**: `mkdir my-plugin/.claude-plugin`
3. **Create plugin.json** with name and version
4. **Add components** (skills, commands, etc.) as needed
5. **Test locally**: `/plugin install /path/to/my-plugin`

For complete templates, see `templates/plugin.json` and `templates/README.md`.

## Plugin Manifest

The `plugin.json` file defines your plugin's metadata and component locations.

### Required Fields
- `name`: Unique identifier in kebab-case
- `version`: Semantic versioning (MAJOR.MINOR.PATCH)

### Optional Metadata
- `description`: Brief plugin purpose
- `author`: Object with `name` (required) and `email` (optional)
- `homepage`: Documentation URL
- `repository`: Source code link
- `license`: Open source license identifier
- `keywords`: Array of discovery tags

### Component Paths
Specify where Claude should find each component type:

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "commands": ["./commands"],
  "agents": ["./agents"],
  "skills": ["./skills"],
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./.mcp.json"
}
```

**Path rules:**
- Must be relative to plugin root
- Should start with `./`
- Can be arrays for multiple directories
- Use `${CLAUDE_PLUGIN_ROOT}` variable for flexible resolution

See `reference/plugin-structure.md` for detailed structure information.

## Component Types

### Commands
Custom slash commands users invoke directly.
- Location: Specified in `commands` field
- Format: Markdown files with frontmatter
- Example: `/my-command`

### Agents
Specialized agent behaviors with custom capabilities.
- Location: Specified in `agents` field
- Format: Markdown files describing agent

### Skills
Reusable capabilities agents can invoke autonomously.
- Location: Specified in `skills` field
- Format: Directories containing `SKILL.md`
- Most common component type

### Hooks
Event handlers triggered by specific events.
- Location: Specified in `hooks` field (points to hooks.json)
- Events: PreToolUse, PostToolUse, UserPromptSubmit
- Format: JSON configuration file

### MCP Servers
External tool integrations via Model Context Protocol.
- Location: Specified in `mcpServers` field (points to .mcp.json)
- Purpose: Connect external data sources and tools

## Ensuring Consistency Between Commands and Skills

**CRITICAL**: When a plugin contains both slash commands and skills that work together, they must provide consistent instructions. Inconsistencies cause Claude to follow the wrong workflow.

### The Problem

Slash commands execute first and provide initial instructions. If the command has different instructions than a skill it invokes, Claude will follow the command's approach instead of the skill's approach.

**Example issue:**
- Slash command says: "Clone the repository with `gh repo clone`"
- Skill says: "Create a git worktree with `git worktree add`"
- Result: Claude clones instead of using worktrees (following the command's instructions)

### The Solution

1. **Align workflows**: Ensure slash commands and skills describe the same approach
2. **Avoid duplication**: Have the command reference the skill rather than duplicating instructions
3. **Provide complete context**: When handing off to another Claude session, include all necessary details (what, where, what to skip)

### Example: Correct Pattern

**Slash command approach:**
```markdown
## 1. Setup
Create git worktree following the standard workflow:
[Include essential setup instructions]

## 2. Launch New Session
Provide user with complete context to continue:
- What PR/task they're working on
- Where the code is located
- Which skill to invoke
- What steps to skip (already completed)
```

**Skill approach:**
```markdown
## 1. Setup (if needed)
[Same setup instructions as command]

## 2. Continue workflow
[Rest of the process]
```

### Portability Considerations

**DON'T hardcode machine-specific paths:**
```markdown
# Bad: Assumes all users organize code the same way
cd ~/src/<repo_name>
```

**DO use adaptable instructions:**
```markdown
# Good: Adapts to any user's setup
First, check if the repository exists locally.
Ask the user where they keep repositories if not found.
```

This keeps plugins portable across different users and environments.

### Validation Checklist

When creating or reviewing plugins with both commands and skills:
- [ ] Commands and skills describe the same workflow approach
- [ ] No hardcoded machine-specific paths
- [ ] Handoffs between sessions include complete context
- [ ] Instructions clearly state what steps to skip when already completed
- [ ] Examples use generic paths, not specific to one developer

## Creating Your Plugin

### Choose Your Pattern

**Single-purpose plugin** (one component type):
```
my-command-plugin/
├── .claude-plugin/
│   └── plugin.json
└── commands/
    └── my-command.md
```

**Skills-focused plugin** (most common):
```
my-skills-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── skill-one/
    │   └── SKILL.md
    └── skill-two/
        └── SKILL.md
```

**Full-featured plugin**:
```
enterprise-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
├── skills/
├── hooks/
│   └── hooks.json
└── .mcp.json
```

See `reference/plugin-structure.md` for more patterns and examples.

### Writing plugin.json

Start minimal, add metadata as needed:

```json
{
  "name": "data-processor",
  "version": "1.0.0",
  "description": "Tools for processing and analyzing data files",
  "author": {
    "name": "Your Name"
  },
  "keywords": ["data", "analysis", "processing"],
  "skills": ["./skills"]
}
```

**Key points:**
- Name must be unique and descriptive
- Version must follow semantic versioning
- Description helps with discoverability
- Only specify component paths you're using

## Best Practices

For comprehensive best practices, see `reference/best-practices.md`. Key highlights:

### Organization
- Keep related functionality together
- Use clear, descriptive naming
- One plugin = one cohesive purpose
- Don't create mega-plugins that do everything

### Versioning
- Follow semantic versioning strictly
- MAJOR: Breaking changes
- MINOR: New features (backward compatible)
- PATCH: Bug fixes

### Documentation
- Write clear descriptions for discoverability
- Document each component's purpose
- Include usage examples
- Specify any requirements or dependencies

### Testing
- Test plugin installation: `/plugin install /path/to/plugin`
- Verify components load: Use `claude --debug`
- Test in clean environment before sharing
- Validate all paths are relative and correct

### Path Management
- Always use relative paths starting with `./`
- Verify paths are correct relative to plugin root
- Test that components are found after installation

## Reviewing Plugins

When reviewing plugins (your own or others') before sharing or adding to marketplaces, use this systematic approach to ensure quality and adherence to best practices.

### Review Process

Follow these five steps for thorough plugin review: