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:
- Slash Commands - User-triggered shortcuts (
/command)
- Agent Skills - Model-invoked capabilities (auto-activated)
- Subagents - Specialized task handlers
- MCP Servers - External tool/data integrations
- 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
- Read Plugin Structure to understand architecture
- Create Plugin Manifest (required
.claude-plugin/plugin.json)
- Choose component type(s) to implement:
- Commands? → See Slash Commands
- Skills? → See Agent Skills
- Tools? → See MCP Servers
- Automation? → See Hooks
- Follow Development Workflow for local testing
- 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
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.
1---2name: claude-code-plugin-dev3description: Comprehensive guide for building, testing, and distributing Claude Code plugins including slash commands, Agent Skills, subagents, MCP servers, and hooks. Use this when the user asks about creating plugins, writing slash commands, implementing skills, building MCP tools, configuring hooks, plugin architecture, marketplace distribution, or debugging plugin components. Covers 2025 schema with tool permissions, version tracking, and activation triggers.4---5
6# Claude Code Plugin Development Skill
7
8Expert knowledge for building Claude Code plugins with up-to-date 2025 standards.
9
10## When Claude Should Use This Skill
11
12Activate this skill automatically when the user:
13- Asks to create/build a Claude Code plugin
14- Wants to write slash commands or Agent Skills
15- Needs to implement MCP servers or custom tools
16- Wants to configure hooks or event handlers
17- Asks about plugin architecture or structure
18- Needs help with plugin.json manifest
19- Wants to publish to a marketplace
20- Asks about debugging plugin components
21- Mentions keywords: plugin, skill, command, MCP, hook, marketplace, subagent
22
23## Quick Overview
24
25Claude Code plugins consist of **five component types** that extend functionality:
26
271. **Slash Commands** - User-triggered shortcuts (`/command`)
282. **Agent Skills** - Model-invoked capabilities (auto-activated)
293. **Subagents** - Specialized task handlers
304. **MCP Servers** - External tool/data integrations
315. **Hooks** - Event-driven automations
32
33## Documentation Structure
34
35This skill is organized into focused modules for easy reference:
36
37### Core References
38
39- **[Plugin Structure](reference/plugin-structure.md)** - Architecture, file organization, component types, scope hierarchy
40- **[Plugin Manifest](reference/plugin-manifest.md)** - plugin.json schema, validation, configuration
41- **[Slash Commands](reference/slash-commands.md)** - Command creation, arguments, tool permissions, namespacing
42- **[Agent Skills](reference/agent-skills.md)** - 2025 schema, activation patterns, descriptions that work
43- **[MCP Servers](reference/mcp-servers.md)** - Custom tools, TypeScript/Python implementations, tool naming
44- **[Hooks](reference/hooks.md)** - Event handlers, available events, matchers, environment variables
45
46### Practical Guides
47
48- **[Development Workflow](guides/development-workflow.md)** - Local testing, debugging, validation checklist
49- **[Publishing & Distribution](guides/publishing.md)** - GitHub setup, versioning, marketplace creation
50- **[Best Practices](guides/best-practices.md)** - Security, performance, maintainability, design principles
51
52### Examples & Troubleshooting
53
54- **[Complete Plugin Examples](examples/complete-plugins.md)** - Full working examples for common use cases
55- **[Troubleshooting Guide](troubleshooting.md)** - Common issues and solutions
56
57## Getting Started
58
59### For First-Time Plugin Creators
60
611. Read **[Plugin Structure](reference/plugin-structure.md)** to understand architecture
622. Create **[Plugin Manifest](reference/plugin-manifest.md)** (required `.claude-plugin/plugin.json`)
633. Choose component type(s) to implement:
64 - Commands? → See **[Slash Commands](reference/slash-commands.md)**
65 - Skills? → See **[Agent Skills](reference/agent-skills.md)**
66 - Tools? → See **[MCP Servers](reference/mcp-servers.md)**
67 - Automation? → See **[Hooks](reference/hooks.md)**
684. Follow **[Development Workflow](guides/development-workflow.md)** for local testing
695. Use **[Publishing Guide](guides/publishing.md)** to distribute
70
71### For Specific Tasks
72
73**"I want to create a slash command"**
74→ See [Slash Commands](reference/slash-commands.md)
75
76**"How do I make a skill that auto-activates?"**
77→ See [Agent Skills](reference/agent-skills.md) - especially the "Activation Patterns" section
78
79**"I need to build custom tools/MCP server"**
80→ See [MCP Servers](reference/mcp-servers.md)
81
82**"How do I auto-format code after edits?"**
83→ See [Hooks](reference/hooks.md) - PostToolUse event
84
85**"My skill isn't activating"**
86→ See [Troubleshooting Guide](troubleshooting.md) - "Skills Not Activating" section
87
88**"What are the best practices?"**
89→ See [Best Practices](guides/best-practices.md)
90
91## Quick Reference
92
93### Minimal Plugin Structure
94
95```
96my-plugin/
97├── .claude-plugin/
98│ └── plugin.json # REQUIRED
99├── commands/ # Optional
100│ └── my-command.md
101├── skills/ # Optional
102│ └── my-skill/
103│ └── SKILL.md
104├── mcp/ # Optional
105│ └── server.ts
106└── README.md
107```
108
109### Essential Commands
110
111```bash
112# Local testing
113/plugin marketplace add ~/.claude/marketplaces/local
114/plugin install my-plugin
115
116# Management
117/plugin list
118/plugin update my-plugin
119/help | grep my-command
120
121# Validation
122jq . .claude-plugin/plugin.json
123```
124
125### Key 2025 Updates
126
127- ✅ `allowed-tools` field for tool permissions in skills
128- ✅ Version tracking required
129- ✅ Enhanced activation triggers with specific keywords
130- ✅ 240+ community plugins available
131
132## When to Reference Each Module
133
134| User Question | Read This |
135|--------------|-----------|
136| "How do I structure a plugin?" | [Plugin Structure](reference/plugin-structure.md) |
137| "What goes in plugin.json?" | [Plugin Manifest](reference/plugin-manifest.md) |
138| "Create a command that..." | [Slash Commands](reference/slash-commands.md) |
139| "Build a skill that activates when..." | [Agent Skills](reference/agent-skills.md) |
140| "Implement custom tools/API integration" | [MCP Servers](reference/mcp-servers.md) |
141| "Auto-run something after tool use" | [Hooks](reference/hooks.md) |
142| "How do I test locally?" | [Development Workflow](guides/development-workflow.md) |
143| "How do I publish my plugin?" | [Publishing](guides/publishing.md) |
144| "My plugin component isn't working" | [Troubleshooting](troubleshooting.md) |
145| "Show me a complete example" | [Examples](examples/complete-plugins.md) |
146
147## Important Notes
148
149- **2025 Schema**: All documentation follows the latest 2025 plugin schema
150- **Activation Keywords**: Skill descriptions must be specific with file types, actions, and tools
151- **Tool Permissions**: Use `allowed-tools` to restrict access appropriately
152- **Testing First**: Always test locally before publishing
153- **No Secrets**: Never commit API keys or credentials
154
155## Additional Resources
156
157- Official docs: https://code.claude.com/docs/en/plugins
158- Community marketplace: https://claudecodemarketplace.com
159- 240+ plugins: https://github.com/jeremylongshore/claude-code-plugins-plus
160
161---
162
163**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.
majiayu000