Claude Code Plugin Development Skill

Expert knowledge for building Claude Code plugins with up-to-date 2025 standards.

When Claude Should Use This Skill

Activate this skill automatically when the user:

• Asks to create/build a Claude Code plugin
• Wants to write slash commands or Agent Skills
• Needs to implement MCP servers or custom tools
• Wants to configure hooks or event handlers
• Asks about plugin architecture or structure
• Needs help with plugin.json manifest
• Wants to publish to a marketplace
• Asks about debugging plugin components
• Mentions keywords: plugin, skill, command, MCP, hook, marketplace, subagent

Quick Overview

Claude Code plugins consist of five component types that extend functionality:

1. Slash Commands - User-triggered shortcuts (/command)
2. Agent Skills - Model-invoked capabilities (auto-activated)
3. Subagents - Specialized task handlers
4. MCP Servers - External tool/data integrations
5. Hooks - Event-driven automations

Documentation Structure

This skill is organized into focused modules for easy reference:

Core References

• Plugin Structure - Architecture, file organization, component types, scope hierarchy
• Plugin Manifest - plugin.json schema, validation, configuration
• Slash Commands - Command creation, arguments, tool permissions, namespacing
• Agent Skills - 2025 schema, activation patterns, descriptions that work
• MCP Servers - Custom tools, TypeScript/Python implementations, tool naming
• Hooks - Event handlers, available events, matchers, environment variables

Practical Guides

• Development Workflow - Local testing, debugging, validation checklist
• Publishing & Distribution - GitHub setup, versioning, marketplace creation
• Best Practices - Security, performance, maintainability, design principles

Examples & Troubleshooting

• Complete Plugin Examples - Full working examples for common use cases
• Troubleshooting Guide - Common issues and solutions

Getting Started

For First-Time Plugin Creators

1. Read Plugin Structure to understand architecture
2. Create Plugin Manifest (required .claude-plugin/plugin.json)
3. Choose component type(s) to implement:
   • Commands? → See Slash Commands
   • Skills? → See Agent Skills
   • Tools? → See MCP Servers
   • Automation? → See Hooks
4. Follow Development Workflow for local testing
5. Use Publishing Guide to distribute

For Specific Tasks

"I want to create a slash command" → See Slash Commands

"How do I make a skill that auto-activates?" → See Agent Skills - especially the "Activation Patterns" section

"I need to build custom tools/MCP server" → See MCP Servers

"How do I auto-format code after edits?" → See Hooks - PostToolUse event

"My skill isn't activating" → See Troubleshooting Guide - "Skills Not Activating" section

"What are the best practices?" → See Best Practices

Quick Reference

Minimal Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json              # REQUIRED
├── commands/                    # Optional
│   └── my-command.md
├── skills/                      # Optional
│   └── my-skill/
│       └── SKILL.md
├── mcp/                         # Optional
│   └── server.ts
└── README.md

Essential Commands

# Local testing
/plugin marketplace add ~/.claude/marketplaces/local
/plugin install my-plugin

# Management
/plugin list
/plugin update my-plugin
/help | grep my-command

# Validation
jq . .claude-plugin/plugin.json

Key 2025 Updates

• ✅ allowed-tools field for tool permissions in skills
• ✅ Version tracking required
• ✅ Enhanced activation triggers with specific keywords
• ✅ 240+ community plugins available

When to Reference Each Module

| User Question | Read This | |--------------|-----------| | "How do I structure a plugin?" | Plugin Structure | | "What goes in plugin.json?" | Plugin Manifest | | "Create a command that..." | Slash Commands | | "Build a skill that activates when..." | Agent Skills | | "Implement custom tools/API integration" | MCP Servers | | "Auto-run something after tool use" | Hooks | | "How do I test locally?" | Development Workflow | | "How do I publish my plugin?" | Publishing | | "My plugin component isn't working" | Troubleshooting | | "Show me a complete example" | Examples |

Important Notes

• 2025 Schema: All documentation follows the latest 2025 plugin schema
• Activation Keywords: Skill descriptions must be specific with file types, actions, and tools
• Tool Permissions: Use allowed-tools to restrict access appropriately
• Testing First: Always test locally before publishing
• No Secrets: Never commit API keys or credentials

Additional Resources

• Official docs: https://code.claude.com/docs/en/plugins
• Community marketplace: https://claudecodemarketplace.com
• 240+ plugins: https://github.com/jeremylongshore/claude-code-plugins-plus

---

Next Steps: Based on what the user is trying to build, direct them to the appropriate reference guide above. For comprehensive understanding, recommend reading in this order: Plugin Structure → Plugin Manifest → specific component type → Development Workflow → Publishing.