# Plugin System

The Claude Code plugin system allows you to extend Claude's capabilities by creating custom slash commands, specialized agents, reusable skills, and automation hooks. With plugins, you can codify your team's best practices and workflows.

## What are Plugins?

### Core Concepts

A Claude Code plugin is a directory with a specific file structure that can add the following components:

| Component | Description | File Format |
|-----------|-------------|-------------|
| **Commands** | Custom slash commands | `.md` files |
| **Agents** | Specialized task subagents | `.md` files |
| **Skills** | Reusable knowledge and capabilities | Directory + `SKILL.md` |
| **Hooks** | Event-triggered automation | `hooks.json` |

### Why Plugins?

- **Team standardization**: Encode coding standards and review criteria as executable commands

- **Workflow automation**: Automate repetitive tasks like commits, deployments, reviews

- **Knowledge sharing**: Share best practices and expertise across team members

- **Custom experience**: Customize Claude's behavior for project needs

## Plugin Directory Structure

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Slash commands (.md files)
│   ├── review.md
│   └── deploy.md
├── agents/                   # Subagent definitions (.md files)
│   └── code-reviewer.md
├── skills/                   # Agent skills (subdirectories)
│   └── coding-standards/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # Event handler configuration
├── .mcp.json                # MCP server definitions (optional)
└── scripts/                 # Helper scripts (optional)
```

## Quick Start

### Install Plugins

```bash
# Install from marketplace
/plugin install plugin-name@claude-code-marketplace

# Install from local directory
claude --plugin-dir /path/to/my-plugin
```

### Use Plugin Creation Wizard

```bash
/plugin-dev:create-plugin
```

This command guides you through 8 phases to create a complete plugin.

## Creating Custom Commands

### Basic Command Format

Create `.md` files in the `commands/` directory:

```markdown
---
description: Perform code review
argument-hint: [file-path]
allowed-tools: Read, Bash(git:*)
---

Please review the code quality of: @$1

Focus on:
1. Code readability
2. Potential bugs
3. Performance issues
4. Security vulnerabilities
```

### YAML Frontmatter Configuration

| Field | Description | Example |
|-------|-------------|---------|
| `description` | Command description (shown in /help) | `Perform code review` |
| `argument-hint` | Parameter hints | `[file-path] [options]` |
| `allowed-tools` | Permitted tools | `Read, Bash(git:*)` |
| `model` | Specify model | `opus` or `sonnet` |

### Using Dynamic Arguments

- `$1`, `$2`, `$3`... - Positional arguments

- `$ARGUMENTS` - All arguments

- `@path/to/file` - File reference

- `!`command`` - Execute Bash command

### Command Examples

**Code Review Command** (`commands/review.md`):

```markdown
---
description: Comprehensive code review
argument-hint: [file-or-directory]
allowed-tools: Read, Grep, Glob
model: opus
---

Perform a comprehensive code review of @$1.

Checklist:
- [ ] Code style follows project standards
- [ ] No potential security issues
- [ ] Error handling is complete
- [ ] Tests are needed

If it's a directory, first use Glob tool to find all relevant files.
```

**Smart Commit Command** (`commands/commit.md`):

```markdown
---
description: Smart commit with generated message
allowed-tools: Bash(git:*)
---

1. Run `git status` to see changes
2. Run `git diff --staged` to analyze staged changes
3. Generate a conventional commit message based on changes
4. Execute `git commit`

Commit message format:
- feat: New feature
- fix: Bug fix
- docs: Documentation update
- refactor: Refactoring
- test: Test related
```

## Creating Custom Agents

### Agent Definition Format

Create `.md` files in the `agents/` directory:

```markdown
---
description: Specialized code review agent
model: opus
tools: Read, Grep, Glob
---

You are a professional code review agent. Your task is to:

1. Carefully read the provided code
2. Identify potential issues
3. Provide specific improvement suggestions
4. Focus on security and performance

Always be constructive and specific.
```

### Agent Types

| Type | Purpose | Example |
|------|---------|---------|
| Review Agent | Code review, PR review | `code-reviewer` |
| Test Agent | Generate and run tests | `test-generator` |
| Doc Agent | Generate documentation | `doc-writer` |
| Refactor Agent | Code refactoring | `refactorer` |

## Creating Skills

### Skill Directory Structure

```
skills/
└── coding-standards/
    ├── SKILL.md              # Required: Skill definition
    ├── references/           # Reference materials
    │   └── style-guide.md
    └── examples/             # Example code
        └── good-practices.md
```

### SKILL.md Format

```markdown
# Coding Standards Skill

## Overview
This skill contains team coding standards and best practices.

## Knowledge Content

### Naming Conventions
- Variables: camelCase
- Constants: UPPER_SNAKE_CASE
- Classes: PascalCase
- Files: kebab-case

### Code Style
- Use 2-space indentation
- Max line width 100 characters
- Use semicolons

### Error Handling
- Always use try-catch
- Log errors
- Provide meaningful error messages
```

## Creating Hooks

### hooks.json Format

```json
{
  "hooks": [
    {
      "event": "on_commit",
      "command": "npm run lint",
      "description": "Run lint check before commit"
    },
    {
      "event": "on_file_change",
      "pattern": "*.ts",
      "command": "npm run typecheck",
      "description": "Type check when TypeScript files change"
    }
  ]
}
```

### Supported Events

| Event | Triggered When |
|-------|----------------|
| `on_commit` | Committing code |
| `on_file_change` | File changes |
| `on_session_start` | Session starts |
| `on_command` | Command execution |

## Plugin Manifest

### plugin.json Format

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom plugin",
  "author": "Your Name",
  "components": {
    "commands": ["commands/*.md"],
    "agents": ["agents/*.md"],
    "skills": ["skills/*/SKILL.md"],
    "hooks": "hooks/hooks.json"
  },
  "mcpServers": ".mcp.json"
}
```

## Practical Examples

### Example 1: Team Code Review Plugin

```
team-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── review-pr.md          # PR review command
│   ├── security-check.md     # Security check command
│   └── perf-audit.md         # Performance audit command
├── agents/
│   ├── security-reviewer.md  # Security review agent
│   └── perf-analyzer.md      # Performance analysis agent
└── skills/
    └── team-standards/
        └── SKILL.md          # Team standards skill
```

### Example 2: Deployment Automation Plugin

```
deploy-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── deploy-staging.md     # Deploy to staging
│   ├── deploy-prod.md        # Deploy to production
│   └── rollback.md           # Rollback command
├── hooks/
│   └── hooks.json            # Pre-deploy check hooks
└── .mcp.json                 # Kubernetes MCP config
```

## Best Practices

### Command Design

1. **Single responsibility**: Each command does one thing

2. **Clear descriptions**: Keep description concise

3. **Document parameters**: Use argument-hint to explain parameters

4. **Minimal permissions**: Only include necessary tools in allowed-tools

5. **Error handling**: Consider failure scenarios

### Plugin Organization

1. **Modular**: Organize related functionality together

2. **Reusable**: Skills should be usable by multiple commands

3. **Documented**: Add README and usage instructions

4. **Versioned**: Use semantic versioning

### Security Considerations

1. **No hardcoded secrets**: Use environment variables

2. **Limit file access**: Only access necessary paths

3. **Validate input**: Validate parameters

4. **Audit logs**: Log sensitive operations

## Debugging Plugins

```bash
# View plugin load status
/plugin list

# View command details
/help my-command

# Test command
/my-command test-argument
```

## Next Steps

- Learn about [MCP Servers](/docs/advanced/mcp) to extend external integrations

- Check [CLI Tips](/docs/usage/cli-tips) to boost efficiency

- Explore [Workflow Tips](/docs/usage/workflow-tips) to optimize development flow