building-plugins

Building Plugins Skill

You are an expert at creating Claude Code plugins. Plugins are bundled packages that combine agents, skills, commands, and hooks into cohesive, distributable units.

What is a Plugin?

A plugin is a package that bundles related Claude Code components:

• Agents: Specialized subagents for delegated tasks
• Skills: Auto-invoked expertise modules
• Commands: User-triggered slash commands
• Hooks: Event-driven automation

Plugins enable users to install complete functionality with a single command.

When to Create a Plugin vs Individual Components

Use a PLUGIN when:

• You want to distribute multiple related components together
• You're building a cohesive feature set or domain expertise
• You want users to install everything with one command
• You need to maintain version compatibility across components
• You're creating a reusable toolkit for a specific domain

Use INDIVIDUAL COMPONENTS when:

• You only need a single agent, skill, or command
• Components are unrelated and can be used independently
• You're customizing for a specific project
• You don't plan to distribute or share

Plugin Creation Process

Creating a plugin involves:

1. Gathering requirements (name, components, metadata)
2. Creating the directory structure
3. Writing the plugin.json manifest
4. Creating each component (agents, skills, commands, hooks)
5. Writing comprehensive README.md
6. Validating the complete plugin

Component Creation: Each component type (agents, skills, commands, hooks) should follow its respective best practices. Use the corresponding building-* skills for expertise on creating each type.

Plugin Structure & Schema

Directory Structure

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── agents/                  # Optional: Agent definitions
│   ├── agent1.md
│   └── agent2.md
├── skills/                  # Optional: Skill directories
│   ├── skill1/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   ├── references/
│   │   └── assets/
│   └── skill2/
│       └── SKILL.md
├── commands/                # Optional: Slash commands
│   ├── command1.md
│   └── command2.md
├── hooks/                   # Optional: Event hooks
│   ├── hooks.json
│   └── scripts/
├── scripts/                 # Optional: Helper scripts
│   └── setup.sh
├── .mcp.json               # Optional: MCP server configuration
└── README.md               # Required: Documentation

Minimal Plugin Structure

The absolute minimum for a valid plugin:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── README.md

plugin.json Schema

Required Fields

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "What the plugin does"
}

Recommended Fields

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Comprehensive description of plugin functionality",
  "author": {
    "name": "Your Name",
    "email": "your.email@example.com",
    "url": "https://github.com/yourname"
  },
  "homepage": "https://github.com/yourname/plugin-name",
  "repository": "https://github.com/yourname/plugin-name",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2", "keyword3"]
}

Component Registration

{
  "commands": "./commands/",
  "agents": ["./agents/agent1.md", "./agents/agent2.md"],
  "skills": "./skills/",
  "hooks": ["./hooks/hooks.json"]
}

Notes:

• Use directory paths ("./commands/") to include all files in a directory
• Use file arrays (["file1.md", "file2.md"]) to list specific files
• Paths are relative to plugin root directory

⚠️ CRITICAL FORMAT WARNING

Arrays MUST contain simple path strings, NOT objects!

❌ WRONG (will silently fail to load):

```json

"commands": [

{"name": "init", "path": "./commands/init.md", "description": "..."},

{"name": "status", "path": "./commands/status.md"}

]

```

✅ CORRECT:

```json

"commands": [

"./commands/init.md",

"./commands/status.md"

]

```

This applies to all component arrays: agents, skills, commands, and hooks.

Also note: Single-item arrays must still be arrays, not strings:

- ❌ "agents": "./agents/my-agent.md" (string - won't load)

- ✅ "agents": ["./agents/my-agent.md"] (array - correct)

Optional: MCP Servers

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-name"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Naming Conventions

Plugin Name:

• Lowercase letters, numbers, and hyphens only (no underscores!)
• Max 64 characters
• Descriptive and domain-specific
• Examples: code-review-suite, data-analytics-tools, git-workflow-automation

Component Names:

• Follow individual component naming rules
• Agents: Action-oriented (code-reviewer, test-generator)
• Skills: Gerund form preferred (analyzing-data, reviewing-code)
• Commands: Verb-first (new-feature, run-tests)
• Consistency: Use similar naming patterns within a plugin

Semantic Versioning

Plugins must follow semantic versioning: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes (e.g., removed components, changed interfaces)
• MINOR: New features (e.g., new commands, enhanced capabilities)
• PATCH: Bug fixes and minor improvements

Examples:

• 1.0.0 → Initial release
• 1.1.0 → Added new command
• 1.1.1 → Fixed bug in existing command
• 2.0.0 → Removed deprecated agent (breaking change)

Creating a Plugin

Follow these steps to create a well-structured plugin:

Step 1: Gather Requirements

Ask the user:

1. Plugin name and purpose: What will this plugin do?
2. Target domain: What problem does it solve?
3. Components needed:
4. How many agents? What tasks?
5. How many skills? What expertise?
6. How many commands? What workflows?
7. Any hooks? What events?
8. Metadata:
9. Author information
10. License type (MIT, Apache 2.0, etc.)
11. Repository URL
12. Keywords for searchability

Step 2: Design Plugin Architecture

Plan the component structure:

Example: Code Review Plugin

code-review-suite/
├── agents/
│   ├── code-reviewer.md          # Deep code analysis
│   └── security-auditor.md       # Security scanning
├── skills/
│   ├── reviewing-code/           # Always-on review expertise
│   └── detecting-vulnerabilities/ # Security pattern matching
├── commands/
│   ├── review.md                 # /review [file]
│   ├── security-scan.md          # /security-scan
│   └── suggest-improvements.md   # /suggest-improvements
└── hooks/
    └── hooks.json                # Pre-commit validation

Design Principles:

• Cohesion: Components should work together toward a common goal
• Single Responsibility: Each component has a clear, focused purpose
• Minimal Overlap: Avoid duplicating functionality
• Progressive Complexity: Start simple, add features iteratively

Step 3: Create Directory Structure

mkdir -p plugin-name/.claude-plugin
mkdir -p plugin-name/agents
mkdir -p plugin-name/skills
mkdir -p plugin-name/commands
mkdir -p plugin-name/hooks
mkdir -p plugin-name/scripts

Step 4: Create plugin.json Manifest

Use the plugin.json schema template and populate all fields:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Detailed description of what this plugin provides",
  "author": {
    "name": "Author Name",
    "email": "email@example.com",
    "url": "https://github.com/username"
  },
  "homepage": "https://github.com/username/plugin-name",
  "repository": "https://github.com/username/plugin-name",
  "license": "MIT",
  "keywords": ["domain", "automation", "tools"],
  "commands": "./commands/",
  "agents": "./agents/",
  "skills": "./skills/",
  "hooks": ["./hooks/hooks.json"]
}

Critical Validation:

• Valid