# Creating Plugins

> Create custom plugins to extend Claude Code with skills, agents, hooks, and MCP servers.

Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams.

## When to Use Plugins vs Standalone Configuration

| Approach                                                    | Skill names          | Best for                                                                                        |
| :---------------------------------------------------------- | :------------------- | :---------------------------------------------------------------------------------------------- |
| **Standalone** (`.claude/` directory)                       | `/hello`             | Personal workflows, project-specific customizations, quick experiments                          |
| **Plugins** (directories with `.claude-plugin/plugin.json`) | `/plugin-name:hello` | Sharing with teammates, distributing to community, versioned releases, reusable across projects |

**Use standalone configuration when**:
- You're customizing Claude Code for a single project
- The configuration is personal and doesn't need to be shared
- You're experimenting with skills or hooks before packaging them
- You want short skill names like `/hello` or `/review`

**Use plugins when**:
- You want to share functionality with your team or community
- You need the same skills/agents across multiple projects
- You want version control and easy updates for your extensions
- You're distributing through a marketplace
- You're okay with namespaced skills like `/my-plugin:hello`

## Quickstart

### Prerequisites
- Claude Code installed and authenticated
- Claude Code version 1.0.33 or later (run `claude --version` to check)

### Create Your First Plugin

#### 1. Create the Plugin Directory
```bash
mkdir my-first-plugin
```

#### 2. Create the Plugin Manifest
The manifest file at `.claude-plugin/plugin.json` defines your plugin's identity.

```bash
mkdir my-first-plugin/.claude-plugin
```

Create `my-first-plugin/.claude-plugin/plugin.json`:
```json
{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}
```

| Field         | Purpose                                                                                |
| :------------ | :------------------------------------------------------------------------------------- |
| `name`        | Unique identifier and skill namespace. Skills are prefixed with this.                  |
| `description` | Shown in the plugin manager when browsing or installing plugins.                       |
| `version`     | Track releases using semantic versioning.                                              |
| `author`      | Optional. Helpful for attribution.                                                     |

#### 3. Add a Skill
Skills live in the `skills/` directory. Each skill is a folder containing a `SKILL.md` file.

```bash
mkdir -p my-first-plugin/skills/hello
```

Create `my-first-plugin/skills/hello/SKILL.md`:
```markdown
---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.
```

#### 4. Test Your Plugin
```bash
claude --plugin-dir ./my-first-plugin
```

Then try:
```shell
/my-first-plugin:hello
```

#### 5. Add Skill Arguments
Make your skill dynamic by accepting user input with `$ARGUMENTS`:

```markdown
---
description: Greet the user with a personalized message
---

# Hello Command

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today.
```

## Plugin Structure Overview

**IMPORTANT**: Don't put `commands/`, `agents/`, `skills/`, or `hooks/` inside the `.claude-plugin/` directory. Only `plugin.json` goes inside `.claude-plugin/`.

| Directory         | Location    | Purpose                                         |
| :---------------- | :---------- | :---------------------------------------------- |
| `.claude-plugin/` | Plugin root | Contains only `plugin.json` manifest (required) |
| `commands/`       | Plugin root | Skills as Markdown files                        |
| `agents/`         | Plugin root | Custom agent definitions                        |
| `skills/`         | Plugin root | Agent Skills with `SKILL.md` files              |
| `hooks/`          | Plugin root | Event handlers in `hooks.json`                  |
| `.mcp.json`       | Plugin root | MCP server configurations                       |
| `.lsp.json`       | Plugin root | LSP server configurations for code intelligence |

## Adding Skills to Your Plugin

Add a `skills/` directory at your plugin root with Skill folders containing `SKILL.md` files:

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md
```

Each `SKILL.md` needs frontmatter with `name` and `description` fields:

```yaml
---
name: code-review
description: Reviews code for best practices and potential issues.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage
```

## Adding LSP Servers to Your Plugin

LSP plugins give Claude real-time code intelligence:

```json
{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}
```

Users installing your plugin must have the language server binary installed on their machine.

## Testing Plugins Locally

Use the `--plugin-dir` flag to test plugins during development:

```bash
claude --plugin-dir ./my-plugin
```

Load multiple plugins:
```bash
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two
```

### Debug Plugin Issues

1. **Check the structure**: Ensure directories are at the plugin root, not inside `.claude-plugin/`
2. **Test components individually**: Check each command, agent, and hook separately
3. **Use validation tools**: See debugging CLI commands

## Converting Existing Configurations to Plugins

### Migration Steps

#### 1. Create the Plugin Structure
```bash
mkdir -p my-plugin/.claude-plugin
```

Create `my-plugin/.claude-plugin/plugin.json`:
```json
{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}
```

#### 2. Copy Your Existing Files
```bash
# Copy commands
cp -r .claude/commands my-plugin/

# Copy agents (if any)
cp -r .claude/agents my-plugin/

# Copy skills (if any)
cp -r .claude/skills my-plugin/
```

#### 3. Migrate Hooks
Create `my-plugin/hooks/hooks.json`:
```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "npm run lint:fix $FILE" }]
      }
    ]
  }
}
```

### What Changes When Migrating

| Standalone (`.claude/`)       | Plugin                           |
| :---------------------------- | :------------------------------- |
| Only available in one project | Can be shared via marketplaces   |
| Files in `.claude/commands/`  | Files in `plugin-name/commands/` |
| Hooks in `settings.json`      | Hooks in `hooks/hooks.json`      |
| Must manually copy to share   | Install with `/plugin install`   |

## Sharing Your Plugins

When your plugin is ready to share:

1. **Add documentation**: Include a `README.md` with installation and usage instructions
2. **Version your plugin**: Use semantic versioning in your `plugin.json`
3. **Create or use a marketplace**: Distribute through plugin marketplaces
4. **Test with others**: Have team members test the plugin before wider distribution

## CLI-Defined Subagents

For quick testing or automation, pass subagents as JSON when launching:

```bash
claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
```

## Grid Integration Opportunities

<!-- Placeholder for Grid-specific integration notes -->