---
name: plugin-builder
description: Create Claude Code plugins with proper structure, plugin.json manifest, and component organization. Use when building new plugins, organizing skills/commands/hooks, or preparing for marketplace distribution. References complete Anthropic documentation.
---

# Plugin Builder

Build plugins that bundle skills, commands, hooks, and MCP servers for team distribution via marketplaces.

## When to Use

- Creating new plugins to organize related functionality
- Bundling skills, commands, and hooks for distribution
- Preparing plugins for marketplace publication
- Structuring multi-component Claude Code extensions
- Converting standalone components into distributable plugins

## What Are Plugins?

Plugins extend Claude Code with custom components that can be shared across projects and teams:

- **Skills**: Model-invoked capabilities (Claude decides when to use)
- **Slash Commands**: User-invoked prompts (`/command`)
- **Hooks**: Automated lifecycle event handlers
- **Agents**: Specialized AI subagents
- **MCP Servers**: External tool integrations

**Distribution**: Plugins are distributed via marketplaces (local, GitHub, or git repositories).

## Quick Start Workflow

### 1. Design Plugin Structure

```
my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Metadata (required)
├── skills/                  # Agent Skills (optional)
│   └── my-skill/
│       └── SKILL.md
├── commands/                # Slash commands (optional)
│   └── my-command.md
├── agents/                  # Custom agents (optional)
│   └── helper.md
└── hooks/                   # Event handlers (optional)
    └── hooks.json
```

**Critical**: Components belong at plugin root, NOT inside `.claude-plugin/`.

### 2. Create plugin.json Manifest

```json
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Brief description of what plugin provides",
  "author": {
    "name": "Your Name",
    "email": "your@email.com"
  },
  "license": "MIT",
  "keywords": ["relevant", "tags"],
  "skills": "./skills/",
  "commands": "./commands/",
  "agents": "./agents/",
  "hooks": "./hooks/"
}
```

**Required fields**: `name`, `version`, `description`, `author`

### 3. Add Components

**Skills** (place in `skills/`):
- Each skill in own directory
- `SKILL.md` with frontmatter
- Optional `references/`, `scripts/`, `assets/`

**Commands** (place in `commands/`):
- Markdown files with YAML frontmatter
- Use `$ARGUMENTS` for parameters
- See slash-command-builder skill for patterns

**Hooks** (place in `hooks/`):
- `hooks.json` configuration
- Hook scripts referenced via `${CLAUDE_PLUGIN_ROOT}`
- See hook-builder skill for patterns

### 4. Test Locally

Create local marketplace for testing:

```bash
cd ~/test-marketplace
mkdir -p .claude-plugin
```

Create `marketplace.json`:
```json
{
  "name": "test-marketplace",
  "owner": {"name": "Your Name"},
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./path/to/my-plugin",
      "description": "Plugin description"
    }
  ]
}
```

Add marketplace and install:
```bash
/plugin marketplace add ./test-marketplace
/plugin install my-plugin@test-marketplace
```

Restart Claude Code to load plugin.

### 5. Verify Installation

```bash
/help          # Check commands appear
/agents        # Check agents appear (if any)
```

Test each component:
- Invoke commands with `/command-name`
- Verify skills trigger on relevant tasks
- Check hooks execute on events

## Essential Patterns

### Pattern 1: Single-Skill Plugin

Simplest plugin structure:

```
simple-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md
```

**plugin.json**:
```json
{
  "name": "simple-plugin",
  "version": "1.0.0",
  "description": "Single focused skill",
  "author": {"name": "Your Name"},
  "skills": "./skills/"
}
```

**Use when**: Single focused capability, no commands or hooks needed.

### Pattern 2: Multi-Component Plugin

Complex plugin with all component types:

```
full-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   ├── skill-one/
│   │   └── SKILL.md
│   └── skill-two/
│       └── SKILL.md
├── commands/
│   ├── cmd-one.md
│   └── cmd-two.md
├── agents/
│   └── helper-agent.md
└── hooks/
    ├── hooks.json
    └── scripts/
        └── validate.sh
```

**plugin.json**:
```json
{
  "name": "full-plugin",
  "version": "1.0.0",
  "description": "Complete workflow automation",
  "author": {"name": "Your Name"},
  "skills": "./skills/",
  "commands": "./commands/",
  "agents": "./agents/",
  "hooks": "./hooks/"
}
```

**Use when**: Complex workflow needs multiple entry points (commands, skills, hooks).

### Pattern 3: Plugin with Hooks

Plugin providing automated validation:

**hooks/hooks.json**:
```json
{
  "description": "Auto-validate TypeScript files",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/typecheck.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

**Key**: Use `${CLAUDE_PLUGIN_ROOT}` to reference plugin files.

### Pattern 4: Missing Manual plugin (Production Example)

Study the marketplace you are building:

```
surf-market/plugins/claude-code-meta/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── claude-code-meta/
        ├── SKILL.md
        └── references/
            ├── plugin-builder.md
            ├── marketplace-builder.md
            ├── hook-builder.md
            ├── slash-command-builder.md
            ├── agent-builder.md
            ├── creating-components.md
            ├── plugin-updates.md
            ├── docs-plugin-builder.md
            ├── skill-examples/
            └── cc-docs-toc.md
```

**Lessons**:
- Maintain a focused plugin scope with one master skill and a reference library.
- Keep metadata (plugin.json, CHANGELOG, README) close to the components that rely on it.
- Bundle example artifacts and core references together so builders can reach them without leaving the repo.

## Plugin Component Paths

**Default component locations**:
- Skills: `./skills/` (each skill in own directory)
- Commands: `./commands/` (markdown files)
- Agents: `./agents/` (agent definitions)
- Hooks: `./hooks/` (hooks.json + scripts)
- MCP Servers: `.mcp.json` (MCP config)

**Custom paths** (plugin.json):
```json
{
  "skills": "./my-custom-skills-dir/",
  "commands": "./cmd/",
  "hooks": "./automation/"
}
```

## Plugin Metadata Best Practices

**Name**: Lowercase, hyphens only, max 64 characters
```json
"name": "my-awesome-plugin"
```

**Version**: Semantic versioning (major.minor.patch)
```json
"version": "1.2.3"
```

**Description**: Clear, specific, 1-2 sentences
```json
"description": "Automates TypeScript validation with Effect-idiomatic patterns. Use for type checking after file edits."
```

**Keywords**: Searchable tags for discovery
```json
"keywords": ["typescript", "validation", "effect", "testing"]
```

**Author**: Full contact info
```json
"author": {
  "name": "Your Name",
  "email": "you@example.com",
  "url": "https://github.com/yourusername"
}
```

**License**: Standard SPDX identifier
```json
"license": "MIT"
```

**Homepage** (optional):
```json
"homepage": "https://github.com/org/plugin-name",
"repository": {
  "type": "git",
  "url": "https://github.com/org/plugin-name.git"
}
```

## Marketplace Registration

After creating plugin, register in marketplace:

**marketplace.json**:
```json
{
  "name": "my-marketplace",
  "owner": {"name": "Your Name", "email": "you@example.com"},
  "metadata": {
    "description": "Marketplace description",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "description": "Plugin description",
      "version": "1.0.0",
      "keywords": ["tags"],
      "source": "./plugins/my-plugin",
      "strict": true
    }
  ]
}
```

**strict: true** (default): Plugin must have `plugin.json`
**strict: false**: Marketplace entry is complete manifest

## Team Distribution

**Option 1: Project settings** (`.claude/settings.json`):
```json
{
  "extraKnownMarketplaces": {
    "team-marketplace": {
      "source": {"source": "github", "repo": "org/claude-plugins"}
    }
  }
}
```

Team members trust folder → plugins auto-install.

**Option 2: User settings** (`~/.claude/settings.json`):
Users manually add marketplace and install plugins.

**Option 3: Local marketplace**:
Development teams share via local filesystem or network drive.

## Versioning & Updates

**Semantic versioning**:
- `1.0.0` → `1.0.1`: Bug fixes (patch)
- `1.0.0` → `1.1.0`: New features (minor)
- `1.0.0` → `2.0.0`: Breaking changes (major)

**Update workflow**:
1. Increment version in `plugin.json`
2. Update CHANGELOG.md with changes
3. Test all components
4. Commit and push to repository
5. Users reinstall for updates

## Plugin Lifecycle

1. **Create**: Structure + plugin.json + components
2. **Test**: Local marketplace + install
3. **Refine**: Iterate based on use
4. **Document**: README + CHANGELOG
5. **Publish**: Register in marketplace
6. **Distribute**: Share marketplace URL/path
7. **Maintain**: Version updates, changelog discipline

## Common Issues

**Plugin not appearing in `/plugin` list**:
- Check `plugin.json` exists in `.claude-plugin/`
- Verify marketplace.json has correct source path
- Restart Claude Code after adding marketplace

**Commands not showing in `/help`**:
- Ensure commands have frontmatter with `description`
- Check `commands` field in plugin.json points to correct directory
- Verify command files have `.md` extension

**Skills not triggering**:
- Check SKILL.md has frontmatter with `name` and `description`
- Verify description includes clear trigger keywords
- Test skill independently first

**Hooks not executing**:
- Check `hooks/hooks.json` syntax
- Verify hook scripts have execute permissions
- Use `${CLAUDE_PLUGIN_ROOT}` for plugin-relative paths
- Check matcher patterns

## Complete API Reference

For full plugin specification including:
- Complete plugin.json schema
- Component organization patterns
- MCP server integration
- Publishing workflows
- Team deployment strategies
- Version management

See [references/anthropic-plugins-docs.md](references/anthropic-plugins-docs.md)

## Related Skills

- **slash-command-builder**: Create commands for plugins
- **hook-builder**: Create hooks for plugins
- **skill-builder**: Create skills for plugins
- **marketplace-builder**: Distribute plugins

## Improving This Skill

Notice gaps, unclear instructions, or better patterns while using this skill?

Use the `continuous-improvement` skill to propose enhancements:
1. Detect the issue
2. Propose specific changes
3. Git branch → commit → surface for approval
4. Update changelog

This skill should evolve with every use.
