/plugin-creator

name: plugin-creator
description: Create comprehensive Claude Code plugins with proper structure, commands, agents, hooks, and marketplace configuration. Use when the user wants to build a new Claude Code plugin or asks how to create/structure a plugin.

Claude Code Plugin Creator

This skill helps you create well-structured Claude Code plugins following best practices from the official documentation and successful plugins like gemini-search.

When to Use This Skill

Invoke this skill when the user:

• Asks to create a new Claude Code plugin
• Wants to understand plugin structure and architecture
• Needs help with plugin.json, marketplace.json, or other config files
• Wants to add commands, agents, or hooks to their plugin
• Asks about plugin best practices or conventions

Plugin Architecture Overview

A Claude Code plugin consists of:

1. **Core Configuration** (`.claude-plugin/`)

• `plugin.json` - Plugin metadata and entry points
• `marketplace.json` - Marketplace listing information

2. **Commands** (`commands/`)

• Markdown files defining slash commands (e.g., `/search`, `/stats`)
• YAML frontmatter with name, description, usage, examples
• Command execution instructions

3. **Agents** (`agents/`)

• Markdown files defining subagents with isolated context
• YAML frontmatter with description and capabilities
• Agent-specific instructions and patterns

4. **Hooks** (`hooks/`)

• `hooks.json` - Hook configuration with matchers
• Bash scripts for PreToolUse, PostToolUse, UserPromptSubmit events
• Event-driven automation

5. **Scripts** (`scripts/`)

• Bash scripts for plugin functionality
• Use `${CLAUDE_PLUGIN_ROOT}` for portability

6. **Documentation**

• `README.md` - User-facing docs
• `CLAUDE.md` - Instructions for Claude Code
• `CHANGES.md` - Changelog
• `CONTRIBUTING.md`, `TESTING.md`, etc.

Step-by-Step Plugin Creation

Step 1: Initialize Plugin Structure

# Create directory structure
mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/commands
mkdir -p my-plugin/agents
mkdir -p my-plugin/hooks
mkdir -p my-plugin/scripts
mkdir -p my-plugin/tests

# Initialize git repository
cd my-plugin
git init
git checkout -b main

Step 2: Create plugin.json

Create `.claude-plugin/plugin.json`:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Brief description of what your plugin does",
  "author": "Your Name",
  "license": "MIT",
  "commands": "commands",
  "agents": "agents",
  "hooks": "hooks/hooks.json"
}

**Important fields:**

• `name`: kebab-case plugin identifier
• `version`: Semantic versioning (MAJOR.MINOR.PATCH)
• `commands`, `agents`, `hooks`: Relative paths to entry points

Step 3: Create marketplace.json

Create `.claude-plugin/marketplace.json`:

{
  "name": "my-plugin-marketplace",
  "owner": {
    "name": "Your Name",
    "email": "your.email@example.com"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "type": "github",
        "repo": "username/repo-name"
      },
      "description": "Detailed description for the marketplace",
      "version": "0.1.0",
      "author": {
        "name": "Your Name"
      },
      "license": "MIT",
      "homepage": "https://github.com/username/repo-name",
      "repository": {
        "type": "git",
        "url": "https://github.com/username/repo-name.git"
      },
      "keywords": [
        "keyword1",
        "keyword2",
        "keyword3"
      ],
      "category": "productivity",
      "commands": "./commands",
      "agents": "./agents",
      "hooks": "./hooks/hooks.json",
      "strict": true,
      "features": [
        "Feature 1 description",
        "Feature 2 description",
        "Feature 3 description"
      ],
      "requirements": {
        "dependencies": [
          {
            "name": "dependency-name",
            "description": "What this dependency does",
            "install": "npm install -g dependency-name",
            "required": true
          }
        ]
      }
    }
  ]
}

**Key sections:**

• `source.type`: "github" or "directory" for local testing
• `category`: "productivity", "development", "utilities", etc.
• `strict`: Set to true for production plugins
• `features`: User-facing feature list
• `requirements.dependencies`: External tools needed

Step 4: Create Commands

Create a command file in `commands/my-command.md`:

---
name: my-command
description: Brief description of what this command does
usage: /my-command [arguments]
examples:
  - /my-command example argument
  - /my-command "quoted argument"
---

You are the command handler for the my-command in the my-plugin plugin.

## Execution Instructions

When this command is invoked:

1. Parse the user's arguments
2. Execute the required logic (call scripts, process data, etc.)
3. Present results to the user

## Example: Calling a Script

Run the following command:
```bash
bash "${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh" arg1 "{{USER_ARG}}"

Where `{{USER_ARG}}` is the argument provided by the user.

Response Format

Present results with:

• Clear summary of what was done
• Formatted output (tables, lists, etc.)
• Any warnings or errors
• Next steps or suggestions

Error Handling

If the command fails:

• Display clear error messages
• Suggest troubleshooting steps
• Recommend related commands

**Command best practices:**
- Use YAML frontmatter with required fields
- Provide clear usage examples
- Use `${CLAUDE_PLUGIN_ROOT}` for script paths
- Define clear error handling

### Step 5: Create Agents (Optional)

Create an agent file in `agents/my-agent.md`:

```markdown
---
description: Agent description and purpose
capabilities:
  [
    "capability-1",
    "capability-2",
    "capability-3",
  ]
---

# My Agent Name

This agent provides [specific functionality] with [key features].

## Features

- Feature 1 with context isolation
- Feature 2 with specific behavior
- Fea