claude-plugins/claude-code/skills/claude-code-plugins/SKILL.md

name, description

name	description
Claude Code Plugin Developer	Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers. Use when building plugins for Claude Code, setting up plugin structure, or configuring plugin manifests.

Claude Code Plugin Development

When to Use This Skill

Use this skill when:

• Creating a new Claude Code plugin from scratch
• Adding components to an existing plugin (commands, agents, skills, hooks)
• Configuring plugin manifests and metadata
• Setting up plugin distribution and marketplaces
• Troubleshooting plugin structure or installation issues

Do NOT use this skill for:

• Creating standalone MCP servers (use MCP-specific documentation)
• General Claude Code usage (not plugin development)
• Creating individual skills without plugin context

Quick Start: Creating a Plugin

1. Basic Plugin Structure

# Create plugin directory
mkdir my-plugin
cd my-plugin

# Create required manifest directory
mkdir -p .claude-plugin

# Create plugin.json manifest
cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "my-plugin",
  "description": "Description of what your plugin does",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}
EOF

2. Add Component Directories

# Create directories for plugin components
mkdir -p commands     # Slash commands
mkdir -p agents       # Custom agents
mkdir -p skills       # Agent Skills
mkdir -p hooks        # Event handlers

Result: Basic plugin structure ready for adding components.

Plugin Manifest (plugin.json)

Required Fields

{
  "name": "plugin-name",           // Lowercase, kebab-case
  "description": "What it does",   // Clear, concise description
  "version": "1.0.0",              // Semantic versioning
  "author": {
    "name": "Author Name"          // Your name or organization
  }
}

Optional Fields

{
  "name": "my-plugin",
  "description": "Advanced features",
  "version": "1.2.0",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "https://yoursite.com"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo"
  },
  "license": "MIT",
  "keywords": ["productivity", "automation"]
}

Plugin Components

1. Commands (Slash Commands)

Create markdown files in commands/ directory:

# commands/review-security.md
---
description: Review code for security vulnerabilities
allowed-tools: Read(*), Grep(*)
---

Review the following files for common security issues:
- SQL injection vulnerabilities
- XSS vulnerabilities
- Hardcoded credentials
- Unsafe deserialization

$ARGUMENTS

Usage: /review-security @src/auth.js

2. Agents

Create agent configurations in agents/ directory:

# agents/code-reviewer.md
---
description: Reviews code for best practices
tools: [Read, Grep, Bash]
model: claude-sonnet-4
---

You are a code review specialist. When reviewing code:
1. Check for common patterns and anti-patterns
2. Verify error handling
3. Look for security issues
4. Suggest improvements

3. Skills

Create skill directories in skills/:

mkdir -p skills/my-skill
# Then create skills/my-skill/SKILL.md with proper frontmatter

See the claude-skills skill for comprehensive skill creation guidance.

4. Hooks

Create hooks/hooks.json to define event handlers:

{
  "PostToolUse": [
    {
      "matcher": "Edit|Write",
      "hooks": [
        {
          "type": "command",
          "command": "echo 'File modified: $TOOL_ARGS' >> .claude/activity.log"
        }
      ]
    }
  ]
}

5. MCP Servers

Create .mcp.json for external tools:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "env:MY_API_KEY"
      }
    }
  }
}

Complete Plugin Example

File Structure

weather-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── weather.md
├── agents/
│   └── forecast-analyst.md
├── skills/
│   └── weather-api/
│       └── SKILL.md
└── README.md

plugin.json

{
  "name": "weather-plugin",
  "description": "Weather forecasting and analysis tools",
  "version": "1.0.0",
  "author": {
    "name": "Weather Team"
  }
}

commands/weather.md

---
description: Get current weather for a location
argument-hint: <location>
---

Get the current weather conditions for: $ARGUMENTS

Include:
- Temperature
- Conditions
- Humidity
- Wind speed

agents/forecast-analyst.md

---
description: Analyzes weather patterns and forecasts
tools: [WebFetch, Read]
---

You are a weather analysis specialist. When asked about weather:
1. Gather current conditions
2. Analyze patterns
3. Provide forecast insights
4. Suggest appropriate actions

Distribution & Installation

Local Development

Test your plugin locally:

# Install from local directory
/plugin install /path/to/my-plugin@local

# Verify installation
/plugin list

Development Marketplace

Create a development marketplace for testing:

// ~/.claude/settings.json
{
  "plugin-marketplaces": {
    "dev": {
      "url": "file:///path/to/marketplace-dir"
    }
  }
}

Team Distribution

Add to project settings for automatic installation:

// .claude/settings.json
{
  "plugins": [
    "my-plugin@company-marketplace"
  ],
  "plugin-marketplaces": {
    "company-marketplace": {
      "url": "https://plugins.company.com"
    }
  }
}

Best Practices

Plugin Design

1. Single responsibility: Each plugin should have a focused purpose
2. Clear naming: Use descriptive, kebab-case names
3. Semantic versioning: Follow SemVer for version numbers
4. Documentation: Include comprehensive README.md

Directory Organization

my-plugin/
├── .claude-plugin/        # Manifest only
│   └── plugin.json
├── commands/              # At plugin root, not in .claude-plugin/
├── agents/               # At plugin root
├── skills/               # At plugin root
└── README.md             # Usage documentation

IMPORTANT: Component directories go at the plugin root, NOT inside .claude-plugin/

Testing Checklist

• Plugin.json is valid JSON
• All required fields present
• Component directories at plugin root
• Commands have valid frontmatter
• Skills follow proper structure
• Local installation works
• No sensitive data in files
• README documents all features

Version Management

# Update version in plugin.json
{
  "version": "1.1.0"  // Increment for changes
}

# Breaking changes: 2.0.0
# New features: 1.1.0
# Bug fixes: 1.0.1

Common Patterns

Multi-Command Plugin

For related commands, use subdirectories:

git-tools/
├── .claude-plugin/plugin.json
└── commands/
    ├── commit.md
    ├── pr.md
    └── review.md

Usage: /commit, /pr, /review

Agent + Skill Combination

Combine agents with specialized skills:

api-plugin/
├── .claude-plugin/plugin.json
├── agents/
│   └── api-specialist.md
└── skills/
    └── rest-api/
        └── SKILL.md

The agent can leverage the skill for specialized knowledge.

Hook-Based Automation

Use hooks for workflow automation:

{
  "PostToolUse": [
    {
      "matcher": "Write",
      "hooks": [
        {
          "type": "command",
          "command": "npm run format $TOOL_ARGS"
        }
      ]
    }
  ]
}

Troubleshooting

Plugin Not Found

Issue: /plugin install can't find plugin

Solutions:

1. Check marketplace configuration in settings.json
2. Verify plugin name matches directory name
3. Ensure plugin.json exists in .claude-plugin/

Commands Not Available

Issue: Slash commands don't appear

Solutions:

1. Verify commands are in commands/ at plugin root
2. Check markdown files have .md extension
3. Restart Claude Code to refresh

Invalid Structure Error

Issue: Plugin fails to load

Solutions:

1. Ensure .claude-plugin/plugin.json exists
2. Validate JSON syntax
3. Move component directories to plugin root (not in .claude-plugin/)

Security Considerations

Never Include

• API keys or credentials in plugin files
• Personal identifying information
• Proprietary code without permission
• Hardcoded paths to user-specific locations

Use Environment Variables

// .mcp.json
{
  "mcpServers": {
    "api-server": {
      "env": {
        "API_KEY": "env:MY_API_KEY"  // Reference env var
      }
    }
  }
}

Command Permissions

Limit tool access in command frontmatter:

---
allowed-tools: Read(src/**), Grep(src/**)
---

Plugin Template

Use this as a starting point:

#!/bin/bash
# create-plugin.sh <plugin-name>

PLUGIN_NAME=$1

mkdir -p "$PLUGIN_NAME"/{.claude-plugin,commands,agents,skills,hooks}

cat > "$PLUGIN_NAME/.claude-plugin/plugin.json" << EOF
{
  "name": "$PLUGIN_NAME",
  "description": "TODO: Add description",
  "version": "0.1.0",
  "author": {
    "name": "TODO: Add author"
  }
}
EOF

cat > "$PLUGIN_NAME/README.md" << EOF
# $PLUGIN_NAME

TODO: Add plugin description

## Installation

\`\`\`
/plugin install $PLUGIN_NAME@marketplace
\`\`\`

## Features

TODO: List features

## Usage

TODO: Add usage examples
EOF

echo "Plugin structure created in $PLUGIN_NAME/"

Resources

• Official Plugin Documentation
• Slash Commands Guide
• Hooks Guide
• Agent Skills Guide

Quick Reference

Required Structure

plugin-name/
└── .claude-plugin/
    └── plugin.json

Common Commands

# Install
/plugin install plugin-name@marketplace

# List installed
/plugin list

# Uninstall
/plugin uninstall plugin-name

Manifest Template

{
  "name": "plugin-name",
  "description": "What it does",
  "version": "1.0.0",
  "author": {"name": "Your Name"}
}

---

Remember: Plugins extend Claude Code with persistent, reusable functionality. Start simple with one or two components, test thoroughly, then expand based on actual needs.