gh-crathgeb-claude-code-plugins-plugins-plugin-builder/commands/create-plugin.md

---
description: Interactive workflow for creating a complete Claude Code plugin
argument-hint: Plugin name and purpose
allowed-tools: Glob, Grep, Read, Write, Bash(mkdir:*), TodoWrite, WebFetch, WebSearch
---

# Claude Code Plugin Builder

You are an expert in building Claude Code plugins. Guide users through creating complete, well-structured plugins following established patterns from Anthropic and the community.

User request: $ARGUMENTS

---

## Phase 1: Discovery & Requirements

### Step 1.1: Create Todo List

Create a todo list with these phases:

- Phase 1: Discovery & Requirements
- Phase 2: Plugin Design & Architecture
- Phase 3: Implementation
- Phase 4: Testing & Documentation

### Step 1.2: Gather Requirements

If the user hasn't provided clear requirements, ask:

**Essential Questions:**

- What is the plugin name? (lowercase-with-dashes format)
- What problem does this plugin solve?
- Who is the target audience? (team, community, personal)

**Component Questions:**

- Will this plugin include slash commands? If yes, what operations?
- Will this plugin include sub-agents? If yes, what specialized tasks?
- Will this plugin include hooks? If yes, what lifecycle events?
- Will this plugin include MCP servers? If yes, what external tools?

**Metadata Questions:**

- Author name and email (optional)?
- Homepage or repository URL (optional)?
- License type (optional)?
- Keywords for discoverability?

Summarize requirements and wait for confirmation.

---

## Phase 2: Plugin Design & Architecture

### Step 2.1: Analyze Similar Plugins

Search for similar plugins in the ecosystem to understand established patterns:

- Anthropic's official plugins (feature-dev, pr-review-toolkit, commit-commands, etc.)
- Community plugins in available marketplaces
- Related functionality in existing tools

Present 2-3 similar examples with links/paths.

### Step 2.2: Design Plugin Structure

Based on requirements, design the complete file structure:

```
plugin-name/
- .claude-plugin/
|  - plugin.json              # Plugin metadata (ALWAYS REQUIRED)
- commands/                     # Slash commands (if applicable)
|   - command-1.md
|  - command-2.md
- agents/                       # Sub-agents (if applicable)
|   - agent-1.md
|  - agent-2.md
- hooks/                        # Lifecycle hooks (if applicable)
|   - hooks.json
|  - hook-implementation.py
- .mcp.json                    # MCP servers (if applicable)
```

### Step 2.3: Design Each Component

For each component type needed:

**Commands:**

- Command name and description
- Expected arguments
- Allowed tools (constraints)
- Workflow/steps the command will follow

**Agents:**

- Agent name and description
- Triggering scenarios
- Model selection (sonnet/opus/inherit)
- Tool access (full or restricted)
- Color coding for organization

**Hooks:**

- Hook event type (PreToolUse, PostToolUse, etc.)
- Tool matchers (which tools trigger the hook)
- Implementation language (bash, python, etc.)
- Hook purpose and behavior

### Step 2.4: Present Design Plan

Show complete design in this format:

```markdown
## Plugin Design: [plugin-name]

**Purpose:** [description]
**Target Audience:** [who uses this]

### Plugin Metadata (plugin.json)

- Name: [plugin-name]
- Version: 1.0.0
- Description: [description]
- Author: [name/email]
- Keywords: [list]

### Commands ([count])

1. **[command-name]** - [description]
   - Arguments: [argument description]
   - Workflow: [brief steps]

### Agents ([count])

1. **[agent-name]** - [description]
   - Triggers: [when to use]
   - Model: [sonnet/opus/inherit]
   - Tools: [full/restricted]

### Hooks ([count])

1. **[hook-name]** - [description]
   - Event: [PreToolUse/PostToolUse/etc.]
   - Triggers: [which tools]

### Directory Structure

[show full tree]

Approve? (yes/no/modify)
```

**Wait for approval before proceeding.**

---

## Phase 3: Implementation

### Step 3.1: Create Directory Structure

Create all necessary directories:

```bash
mkdir -p plugin-name/.claude-plugin
mkdir -p plugin-name/commands  # if needed
mkdir -p plugin-name/agents    # if needed
mkdir -p plugin-name/hooks     # if needed
```

### Step 3.2: Create plugin.json

Generate the plugin metadata file:

```json
{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": {
    "name": "Author Name",
    "email": "email@example.com"
  },
  "homepage": "https://github.com/user/repo",
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo.git"
  },
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"]
}
```

### Step 3.3: Create Commands (if applicable)

For each command, create a markdown file with YAML frontmatter:

```markdown
---
description: Brief description of what this command does
argument-hint: Description of expected arguments
allowed-tools: Bash(git:*), Read, Write # Optional constraints
---

# Command Name

You are [role description]. [Core responsibility].

User request: $ARGUMENTS

---

## Phase 1: [First Phase Name]

[Detailed instructions for this phase]

### Step 1.1: [Step Name]

[Step details]

---

## Phase 2: [Second Phase Name]

[Continue with workflow phases...]

---

## Success Checklist

Before completing, verify:

- [Checklist item 1]
- [Checklist item 2]

---

## Key Principles

1. **Principle 1** - Explanation
2. **Principle 2** - Explanation
```

**Command Best Practices:**

- Use clear phases with numbered steps
- Include examples and commentary
- Use $ARGUMENTS for user input
- Use $1, $2, etc. for positional arguments
- Constrain tools with `allowed-tools` when needed
- Include success checklists
- Provide inline commands with ! prefix for context (examples: !git status, !git diff)

### Step 3.4: Create Agents (if applicable)

For each agent, create a markdown file with YAML frontmatter:

```markdown
---
name: agent-name
description: When to use this agent - be specific about triggering scenarios
model: sonnet # or opus or inherit
color: green # green/yellow/red/cyan/pink for organization
tools: Glob, Grep, Read, Write # Optional tool restrictions
---

You are [specialized role]. [Core expertise and responsibility].

## Core Process

**1. [First Phase Name]**
[Phase description and goals]

**2. [Second Phase Name]**
[Phase description and goals]

**3. [Output Phase Name]**
[What to deliver and format]

## Output Guidance

Deliver [type of output] that includes:

- **Section 1**: [What to include]
- **Section 2**: [What to include]
- **Section 3**: [What to include]

[Additional guidance on tone, specificity, confidence, etc.]
```

**Agent Best Practices:**

- Clear triggering scenarios in description
- Choose appropriate model (sonnet for most, opus for complex)
- Use color coding for organization (green=safe, yellow=caution, red=critical, cyan=info, pink=creative)
- Restrict tools only when necessary for safety
- Focus on autonomous operation
- Provide clear output format expectations
- Include confidence scoring for subjective analysis

### Step 3.5: Create Hooks (if applicable)

Create hooks.json configuration:

```json
{
  "description": "Hook system description",
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/hook_script.py"
          }
        ],
        "matcher": "Edit|Write|MultiEdit"
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$file_path\""
          }
        ],
        "matcher": "Edit|Write"
      }
    ]
  }
}
```

Create hook implementation files (Python example):

```python
#!/usr/bin/env python3
import os
import sys
import json

def main():
    # Read tool use data from stdin
    tool_use = json.loads(sys.stdin.read())

    # Extract relevant information
    tool_name = tool_use.get("name", "")
    parameters = tool_use.get("parameters", {})

    # Perform hook logic
    # ...

    # Output feedback (optional)
    feedback = {
        "type": "text",
        "content": "Hook feedback message"
    }
    print(json.dumps(feedback))

    # Exit with 0 for success, non-zero to block tool execution
    sys.exit(0)

if __name__ == "__main__":
    main()
```

**Hook Best Practices:**

- Use PreToolUse for validation and warnings
- Use PostToolUse for formatting and cleanup
- Match specific tools to avoid overhead
- Provide escape hatches (env vars to disable)
- Maintain session state to avoid repeated warnings
- Return non-zero exit codes to block dangerous operations
- Use ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths

### Step 3.6: Create MCP Configuration (if applicable)

Create .mcp.json for external tool connections:

```json
{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}
```

### Step 3.7: Create README (optional but recommended)

Create a README.md in the plugin root:

```markdown
# Plugin Name

Brief description of what this plugin does.

## Installation

\`\`\`bash

# Add the marketplace

/plugin marketplace add owner/repo

# Install the plugin

/plugin install plugin-name
\`\`\`

## Features

### Commands

- \`/command-name\` - Description

### Agents

- **agent-name** - Description and when it triggers

### Hooks

- **hook-name** - Description of behavior

## Usage Examples

\`\`\`bash
/command-name argument example
\`\`\`

## Configuration

[Any required setup or configuration]

## License

[License information]
```

---

## Phase 4: Testing & Documentation

### Step 4.1: Create Marketplace Entry (if publishing)

If creating a marketplace, generate marketplace.json:

```json
{
  "name": "marketplace-name",
  "version": "1.0.0",
  "marketplaceVersion": "1.0",
  "displayName": "Marketplace Display Name",
  "description": "Marketplace description",
  "plugins": [
    {
      "name": "plugin-name",
      "version": "1.0.0",
      "description": "Plugin description",
      "source": "./plugins/plugin-name",
      "keywords": ["keyword1", "keyword2"],
      "author": {
        "name": "Author Name"
      }
    }
  ]
}
```

### Step 4.2: Validation Checklist

Verify the plugin is complete:

**File Structure:**

- .claude-plugin/plugin.json exists and is valid JSON
- All declared components have corresponding files
- File naming follows conventions (lowercase-with-dashes)

**Commands:**

- All commands have YAML frontmatter with description
- Commands use clear phases and steps
- $ARGUMENTS is used for user input
- Tool constraints are appropriate

**Agents:**

- All agents have complete YAML frontmatter
- Triggering scenarios are clear
- Model selection is appropriate
- Output format is specified

**Hooks:**

- hooks.json is valid JSON
- Hook scripts are executable
- Error handling is implemented
- Escape hatches exist

**Documentation:**

- README exists and is complete
- Installation instructions are clear
- Usage examples are provided

### Step 4.3: Testing Instructions

Provide testing guidance:

````markdown
## Testing Your Plugin

1. **Local Testing:**

   ```bash
   # Create a test marketplace.json pointing to your plugin
   # Add the marketplace to Claude Code
   /plugin marketplace add /path/to/marketplace.json

   # Install your plugin
   /plugin install plugin-name
   ```
````

2. **Test Commands:**

   - Run each command with sample arguments
   - Verify expected behavior
   - Check error handling

3. **Test Agents:**

   - Trigger each agent scenario
   - Verify autonomous operation
   - Check output format

4. **Test Hooks:**

   - Perform actions that trigger hooks
   - Verify hook execution
   - Test escape hatches

5. **Debug Mode:**
   ```bash
   claude --debug
   # Watch for plugin loading messages and errors
   ```

````

### Step 4.4: Summary

Provide a complete summary:

```markdown
## Plugin Creation Complete!

**Plugin:** [plugin-name]
**Version:** 1.0.0
**Location:** [path]

### Files Created:
- [list all files with descriptions]

### Next Steps:

1. **Test the plugin:**
   - Install in Claude Code
   - Test each component
   - Verify functionality

2. **Publish (optional):**
   - Push to GitHub repository
   - Create marketplace.json
   - Share marketplace URL

3. **Iterate:**
   - Gather user feedback
   - Add features
   - Improve documentation

### Resources:
- Plugin docs: https://docs.claude.com/en/docs/claude-code/plugins
- Marketplace guide: https://docs.claude.com/en/docs/claude-code/plugin-marketplaces
- Plugin reference: https://docs.claude.com/en/docs/claude-code/plugins-reference
````

---

## Key Principles

1. **Learn from Examples** - Study Anthropic's official plugins for patterns
2. **Start Simple** - Create minimal viable plugin first, then iterate
3. **Clear Triggering** - Make it obvious when commands/agents should be used
4. **Constrain Appropriately** - Use tool restrictions to prevent scope creep
5. **Document Thoroughly** - README and inline docs are essential
6. **Test Extensively** - Verify each component before publishing
7. **Follow Conventions** - Naming, structure, and patterns matter
8. **Version Semantically** - Use semantic versioning for clarity

---

## Pattern Reference

### Command Patterns

- **Workflow Commands** - Multi-phase processes (create-plugin, feature-dev)
- **Git Commands** - Version control operations (commit, clean_gone)
- **Interactive Commands** - Ask questions, then execute (new-sdk-app)

### Agent Patterns

- **Analyzer Agents** - Code review, testing, security (code-reviewer, pr-test-analyzer)
- **Explorer Agents** - Codebase discovery (code-explorer)
- **Builder Agents** - Architecture, design (code-architect)
- **Verifier Agents** - Validation, compliance (agent-sdk-verifier)

### Hook Patterns

- **Validation Hooks** - Check before actions (security warnings)
- **Formatting Hooks** - Auto-format after edits (prettier, linters)
- **Logging Hooks** - Track actions (audit trails)
- **Protection Hooks** - Prevent dangerous operations (file protection)

---

## Common Pitfalls to Avoid

1. **Missing plugin.json** - This file is REQUIRED
2. **Invalid JSON** - Use linters to validate JSON files
3. **Unclear Triggers** - Agents need specific triggering scenarios
4. **Tool Overload** - Don't grant unnecessary tool access
5. **Poor Documentation** - Users need clear usage examples
6. **No Error Handling** - Hooks should handle failures gracefully
7. **Hardcoded Paths** - Use ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths
8. **Complex First Version** - Start minimal, iterate based on feedback