plugin-builder

What this skill does

# Plugin Builder Skill

## Purpose

This skill guides you through creating well-structured Claude Code plugins with all necessary components, following best practices for discoverability, maintainability, and user experience.

## When to Use

Use this skill when:
- Creating a new Claude Code plugin from scratch
- Adding components (skills, commands, agents, hooks) to existing plugins
- Generating properly structured SKILL.md files
- Setting up marketplace plugin registration
- Validating plugin metadata and structure

## Prerequisites

- Access to a Claude Code marketplace repository
- Understanding of the plugin's intended functionality
- Basic knowledge of JSON and Markdown formats
- Location of the marketplace root directory

## Plugin Architecture Overview

A Claude Code plugin follows this structure:

```
plugin-name/
├── .claude-plugin/
│   └── plugin.json       # Required: Plugin metadata
├── skills/               # Optional: Agent Skills
│   └── skill-name/
│       ├── SKILL.md      # Skill instructions
│       ├── scripts/      # Optional: Executable code
│       └── resources/    # Optional: Templates, data
├── commands/             # Optional: Custom slash commands
│   └── command-name.md
├── agents/               # Optional: Custom agent definitions
├── hooks/                # Optional: Event handlers
│   └── hooks.json
└── .mcp.json            # Optional: MCP server configuration
```

## Instructions

### Step 1: Plan the Plugin

Before creating files, clarify:
1. **Plugin name** (use kebab-case: `my-plugin-name`)
2. **Purpose** (what problem does it solve?)
3. **Components needed** (skills, commands, agents, hooks?)
4. **Target users** (who will use this plugin?)

### Step 2: Create Plugin Directory Structure

1. Navigate to the marketplace `plugins/` directory
2. Create the plugin directory: `plugins/category/plugin-name/`
3. Create required subdirectories:
   ```bash
   mkdir -p plugins/category/plugin-name/.claude-plugin
   mkdir -p plugins/category/plugin-name/skills
   mkdir -p plugins/category/plugin-name/commands  # if needed
   ```

### Step 3: Generate plugin.json

Create `.claude-plugin/plugin.json` with this structure:

```json
{
  "name": "plugin-name",
  "description": "Clear, concise description of plugin functionality (1-2 sentences)",
  "version": "1.0.0",
  "author": {
    "name": "Author Name",
    "email": "[email protected]"
  }
}
```

**Required fields:**
- `name`: Plugin identifier (kebab-case, no spaces)
- `description`: User-facing description (be specific about what it does)
- `version`: Semantic version (major.minor.patch)
- `author.name`: Author's name

**Version Guidelines:**
- Start with `1.0.0` for initial release
- Increment patch (1.0.1) for bug fixes
- Increment minor (1.1.0) for new features (backward compatible)
- Increment major (2.0.0) for breaking changes

### Step 4: Create Skills (if applicable)

For each skill in the plugin:

1. **Create skill directory:**
   ```bash
   mkdir -p plugins/category/plugin-name/skills/skill-name
   ```

2. **Create SKILL.md** using progressive disclosure format:

```markdown
# Skill Name

## Purpose
[1-2 sentences: What this skill does and its main value]

## When to Use
[Bullet list of specific scenarios where this skill applies]
- Creating X
- Automating Y
- Solving Z problem

## Prerequisites
[What's needed before using this skill]
- Required tools or libraries
- Necessary permissions or access
- Context or information needed

## Instructions

### Task 1: [First Major Step]
[Detailed step-by-step instructions]
1. Do this first
2. Then do this
3. Finally do this

### Task 2: [Second Major Step]
[More detailed instructions]

[Continue with all major tasks...]

## Examples

### Example 1: [Concrete Use Case]
[Show complete example with actual code/commands]

\`\`\`language
[actual code]
\`\`\`

### Example 2: [Another Use Case]
[Another complete example]

## Best Practices
- [Specific practice 1]
- [Specific practice 2]
- [Specific practice 3]

## Common Issues
- **Problem:** [Description]
  **Solution:** [How to fix]
- **Problem:** [Description]
  **Solution:** [How to fix]
```

3. **Add optional resources:**
   ```bash
   mkdir -p plugins/category/plugin-name/skills/skill-name/resources
   mkdir -p plugins/category/plugin-name/skills/skill-name/scripts
   ```

**Skill Best Practices:**
- **Focus:** Each skill should do ONE thing well
- **Discoverability:** Use clear, searchable names and descriptions
- **Progressive disclosure:** Start with overview, then details, then examples
- **Actionable:** Provide concrete steps, not generic advice
- **Examples:** Include real, working examples users can adapt
- **Error handling:** Document common issues and solutions

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

For custom slash commands:

1. **Create command file:**
   ```bash
   touch plugins/category/plugin-name/commands/command-name.md
   ```

2. **Write command markdown:**

```markdown
# Command Name

[Description of what this command does]

## Usage
/command-name [arguments]

## Examples
/command-name example-arg

## Parameters
- `arg1`: Description of first argument
- `arg2`: Description of second argument (optional)

## Instructions for Claude
[Detailed instructions for what Claude should do when this command is invoked]

1. Step 1
2. Step 2
3. Step 3
```

### Step 6: Update Marketplace Registry

1. **Open marketplace.json:**
   Located at `.claude-plugin/marketplace.json` in the repository root

2. **Add plugin entry:**
   ```json
   {
     "name": "marketplace-name",
     "plugins": [
       {
         "name": "plugin-name",
         "source": "./plugins/category/plugin-name",
         "description": "Plugin description"
       }
     ]
   }
   ```

   **Important:** For local plugins, the `source` field must start with `./` to specify a relative path from the marketplace root.

### Step 7: Validate Plugin

**Checklist:**
- [ ] plugin.json exists and has all required fields
- [ ] Plugin name uses kebab-case (no spaces, lowercase with hyphens)
- [ ] Description is clear and specific
- [ ] Version follows semantic versioning (major.minor.patch)
- [ ] All SKILL.md files follow progressive disclosure format
- [ ] Examples are included in all SKILL.md files
- [ ] Commands have clear usage instructions
- [ ] Plugin is registered in marketplace.json
- [ ] File paths are correct and accessible

### Step 8: Test Locally

1. **Install the plugin locally:**
   - User runs: `/plugin install plugin-name@marketplace-name`

2. **Test skill invocation:**
   - Verify skills are discoverable
   - Test with relevant prompts
   - Check that instructions are clear

3. **Test commands:**
   - Run each slash command
   - Verify behavior matches documentation

4. **Iterate:**
   - Fix any issues found
   - Update documentation as needed
   - Increment version number for changes

## Complete Examples

### Example 1: Creating a Data Validation Plugin

**Scenario:** Create a plugin that validates JSON schemas

**Step-by-step:**

1. **Create structure:**
   ```bash
   mkdir -p plugins/data/json-validator/.claude-plugin
   mkdir -p plugins/data/json-validator/skills/json-validator
   ```

2. **Create plugin.json:**
   ```json
   {
     "name": "json-validator",
     "description": "Validates JSON data against schemas with detailed error reporting",
     "version": "1.0.0",
     "author": {
       "name": "Data Team"
     }
   }
   ```

3. **Create SKILL.md:**
   ```markdown
   # JSON Validator Skill

   ## Purpose
   Validates JSON data against JSON Schema specifications and provides detailed error reports.

   ## When to Use
   - Validating API request/response payloads
   - Checking configuration files
   - Ensuring data structure compliance

   ## Prerequisites
   - JSON data to validate
   - JSON Schema definition
   - Understanding of JSON Schema syntax

   ## Instructions

   ### Validate JSON Data
   1. Receive or locate the JSON data to validate
   2. Receive or locate the JSON Sche