claude-plugins/claude-code/skills/claude-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 PROACTIVELY when users package multiple related features, mention "create a plugin", "package for distribution", "plugin marketplace", or have 3+ commands/skills to organize. NOT for creating individual components in isolation.

Claude Code Plugin Development

When to Use This Skill

Use this skill when:

• Creating a new plugin from scratch
• Adding components to existing plugin
• Configuring plugin manifests
• Setting up distribution/marketplaces
• Packaging 3+ related commands/skills/agents

Do NOT use this skill for:

• Creating standalone MCP servers
• Single commands (use claude-commands skill)
• General Claude Code usage

Quick Start

1. Basic Plugin Structure

mkdir my-plugin && cd my-plugin
mkdir -p .claude-plugin

cat > .claude-plugin/plugin.json << 'EOF'
{
  "name": "my-plugin",
  "description": "What your plugin does",
  "version": "1.0.0",
  "author": {"name": "Your Name"}
}
EOF

# Add component directories
mkdir -p commands agents skills hooks

2. Test Installation

/plugin install /path/to/my-plugin@local
/plugin list

Plugin Manifest (plugin.json)

Required Fields

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

Optional Fields

{
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo"
  },
  "license": "MIT",
  "keywords": ["productivity", "automation"]
}

Plugin Components

1. Commands (commands/)

→ See claude-commands skill for full guide

# commands/review.md
---
description: Review code for issues
---

Review $ARGUMENTS for:
- Logic errors
- Style issues

Usage: /review @file.js

2. Agents (agents/)

→ See claude-subagents skill for full guide

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

You are a code review specialist...

3. Skills (skills/)

→ See claude-skills skill for full guide

skills/
└── my-skill/
    └── skill.md    # With frontmatter

4. Hooks (hooks/hooks.json)

→ See claude-hooks skill for full guide

{
  "PostToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "npx prettier --write $TOOL_ARGS"
    }]
  }]
}

5. MCP Servers (.mcp.json)

→ See mcp-config skill for full guide

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

Directory Organization

IMPORTANT: Components at plugin root, NOT in .claude-plugin/

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

Distribution

Local Testing

/plugin install /path/to/plugin@local

Team Marketplace

// .claude/settings.json
{
  "plugin-marketplaces": {
    "team": {
      "url": "file:///path/to/marketplace"
    }
  },
  "plugins": ["my-plugin@team"]
}

Marketplace Structure

marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugin-name/
    ├── .claude-plugin/plugin.json
    └── [components]

Common Patterns

Multi-Command Plugin

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

Agent + Skill Combo

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

Hook-Based Automation

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

Testing Checklist

• plugin.json valid JSON
• All required fields present
• Components at plugin root
• Commands have frontmatter
• Local installation works
• No sensitive data
• README documents features

Troubleshooting

Problem	Solution
Plugin not found	Check plugin.json in .claude-plugin/
Commands unavailable	Verify commands/ at root, restart
Invalid structure	Move components to root, not .claude-plugin/

Security

Never include:

• API keys or credentials
• Hardcoded secrets
• Personal paths

Use environment variables:

{
  "mcpServers": {
    "api": {
      "env": {"API_KEY": "env:MY_API_KEY"}
    }
  }
}

Version Management

{
  "version": "1.1.0"  // Semantic versioning
}

// Breaking: 2.0.0
// Features: 1.1.0
// Fixes: 1.0.1

Additional Resources

Component Skills:

• Commands Guide - Create slash commands
• Subagents Guide - Configure specialized agents
• Skills Guide - Build contextual knowledge skills
• Hooks Guide - Automate with event-driven hooks
• MCP Config Guide - Integrate MCP servers
• Memory Guide - Manage persistent memory

External Resources:

• Official Docs
• MCP Protocol

💡 Tip: Start with one component type, test thoroughly, then expand. Plugins organize related functionality.

---

Remember: Plugins package related features. Components go at root. Test locally first. Use semantic versioning.