surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / plugin-dev / README.md

402 lines · 14.3 KBPreview CodeRaw

1	# Plugin Development Toolkit
2
3	A comprehensive toolkit for developing Claude Code plugins with expert guidance on hooks, MCP integration, plugin structure, and marketplace publishing.
4
5	## Overview
6
7	The plugin-dev toolkit provides seven specialized skills to help you build high-quality Claude Code plugins:
8
9	1. Hook Development - Advanced hooks API and event-driven automation
10	2. MCP Integration - Model Context Protocol server integration
11	3. Plugin Structure - Plugin organization and manifest configuration
12	4. Plugin Settings - Configuration patterns using .claude/plugin-name.local.md files
13	5. Command Development - Creating slash commands with frontmatter and arguments
14	6. Agent Development - Creating autonomous agents with AI-assisted generation
15	7. Skill Development - Creating skills with progressive disclosure and strong triggers
16
17	Each skill follows best practices with progressive disclosure: lean core documentation, detailed references, working examples, and utility scripts.
18
19	## Guided Workflow Command
20
21	### /plugin-dev:create-plugin
22
23	A comprehensive, end-to-end workflow command for creating plugins from scratch, similar to the feature-dev workflow.
24
25	8-Phase Process:
26	1. Discovery - Understand plugin purpose and requirements
27	2. Component Planning - Determine needed skills, commands, agents, hooks, MCP
28	3. Detailed Design - Specify each component and resolve ambiguities
29	4. Structure Creation - Set up directories and manifest
30	5. Component Implementation - Create each component using AI-assisted agents
31	6. Validation - Run plugin-validator and component-specific checks
32	7. Testing - Verify plugin works in Claude Code
33	8. Documentation - Finalize README and prepare for distribution
34
35	Features:
36	- Asks clarifying questions at each phase
37	- Loads relevant skills automatically
38	- Uses agent-creator for AI-assisted agent generation
39	- Runs validation utilities (validate-agent.sh, validate-hook-schema.sh, etc.)
40	- Follows plugin-dev's own proven patterns
41	- Guides through testing and verification
42
43	Usage:
44	```bash
45	/plugin-dev:create-plugin [optional description]
46
47	# Examples:
48	/plugin-dev:create-plugin
49	/plugin-dev:create-plugin A plugin for managing database migrations
50	```
51
52	Use this workflow for structured, high-quality plugin development from concept to completion.
53
54	## Skills
55
56	### 1. Hook Development
57
58	Trigger phrases: "create a hook", "add a PreToolUse hook", "validate tool use", "implement prompt-based hooks", "${CLAUDE_PLUGIN_ROOT}", "block dangerous commands"
59
60	What it covers:
61	- Prompt-based hooks (recommended) with LLM decision-making
62	- Command hooks for deterministic validation
63	- All hook events: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification
64	- Hook output formats and JSON schemas
65	- Security best practices and input validation
66	- ${CLAUDE_PLUGIN_ROOT} for portable paths
67
68	Resources:
69	- Core SKILL.md (1,619 words)
70	- 3 example hook scripts (validate-write, validate-bash, load-context)
71	- 3 reference docs: patterns, migration, advanced techniques
72	- 3 utility scripts: validate-hook-schema.sh, test-hook.sh, hook-linter.sh
73
74	Use when: Creating event-driven automation, validating operations, or enforcing policies in your plugin.
75
76	### 2. MCP Integration
77
78	Trigger phrases: "add MCP server", "integrate MCP", "configure .mcp.json", "Model Context Protocol", "stdio/SSE/HTTP server", "connect external service"
79
80	What it covers:
81	- MCP server configuration (.mcp.json vs plugin.json)
82	- All server types: stdio (local), SSE (hosted/OAuth), HTTP (REST), WebSocket (real-time)
83	- Environment variable expansion (${CLAUDE_PLUGIN_ROOT}, user vars)
84	- MCP tool naming and usage in commands/agents
85	- Authentication patterns: OAuth, tokens, env vars
86	- Integration patterns and performance optimization
87
88	Resources:
89	- Core SKILL.md (1,666 words)
90	- 3 example configurations (stdio, SSE, HTTP)
91	- 3 reference docs: server-types (~3,200w), authentication (~2,800w), tool-usage (~2,600w)
92
93	Use when: Integrating external services, APIs, databases, or tools into your plugin.
94
95	### 3. Plugin Structure
96
97	Trigger phrases: "plugin structure", "plugin.json manifest", "auto-discovery", "component organization", "plugin directory layout"
98
99	What it covers:
100	- Standard plugin directory structure and auto-discovery
101	- plugin.json manifest format and all fields
102	- Component organization (commands, agents, skills, hooks)
103	- ${CLAUDE_PLUGIN_ROOT} usage throughout
104	- File naming conventions and best practices
105	- Minimal, standard, and advanced plugin patterns
106
107	Resources:
108	- Core SKILL.md (1,619 words)
109	- 3 example structures (minimal, standard, advanced)
110	- 2 reference docs: component-patterns, manifest-reference
111
112	Use when: Starting a new plugin, organizing components, or configuring the plugin manifest.
113
114	### 4. Plugin Settings
115
116	Trigger phrases: "plugin settings", "store plugin configuration", ".local.md files", "plugin state files", "read YAML frontmatter", "per-project plugin settings"
117
118	What it covers:
119	- .claude/plugin-name.local.md pattern for configuration
120	- YAML frontmatter + markdown body structure
121	- Parsing techniques for bash scripts (sed, awk, grep patterns)
122	- Temporarily active hooks (flag files and quick-exit)
123	- Real-world examples from multi-agent-swarm and ralph-wiggum plugins
124	- Atomic file updates and validation
125	- Gitignore and lifecycle management
126
127	Resources:
128	- Core SKILL.md (1,623 words)
129	- 3 examples (read-settings hook, create-settings command, templates)
130	- 2 reference docs: parsing-techniques, real-world-examples
131	- 2 utility scripts: validate-settings.sh, parse-frontmatter.sh
132
133	Use when: Making plugins configurable, storing per-project state, or implementing user preferences.
134
135	### 5. Command Development
136
137	Trigger phrases: "create a slash command", "add a command", "command frontmatter", "define command arguments", "organize commands"
138
139	What it covers:
140	- Slash command structure and markdown format
141	- YAML frontmatter fields (description, argument-hint, allowed-tools)
142	- Dynamic arguments and file references
143	- Bash execution for context
144	- Command organization and namespacing
145	- Best practices for command development
146
147	Resources:
148	- Core SKILL.md (1,535 words)
149	- Examples and reference documentation
150	- Command organization patterns
151
152	Use when: Creating slash commands, defining command arguments, or organizing plugin commands.
153
154	### 6. Agent Development
155
156	Trigger phrases: "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "autonomous agent"
157
158	What it covers:
159	- Agent file structure (YAML frontmatter + system prompt)
160	- All frontmatter fields (name, description, model, color, tools)
161	- Description format with <example> blocks for reliable triggering
162	- System prompt design patterns (analysis, generation, validation, orchestration)
163	- AI-assisted agent generation using Claude Code's proven prompt
164	- Validation rules and best practices
165	- Complete production-ready agent examples
166
167	Resources:
168	- Core SKILL.md (1,438 words)
169	- 2 examples: agent-creation-prompt (AI-assisted workflow), complete-agent-examples (4 full agents)
170	- 3 reference docs: agent-creation-system-prompt (from Claude Code), system-prompt-design (~4,000w), triggering-examples (~2,500w)
171	- 1 utility script: validate-agent.sh
172
173	Use when: Creating autonomous agents, defining agent behavior, or implementing AI-assisted agent generation.
174
175	### 7. Skill Development
176
177	Trigger phrases: "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content"
178
179	What it covers:
180	- Skill structure (SKILL.md with YAML frontmatter)
181	- Progressive disclosure principle (metadata → SKILL.md → resources)
182	- Strong trigger descriptions with specific phrases
183	- Writing style (imperative/infinitive form, third person)
184	- Bundled resources organization (references/, examples/, scripts/)
185	- Skill creation workflow
186	- Based on skill-creator methodology adapted for Claude Code plugins
187
188	Resources:
189	- Core SKILL.md (1,232 words)
190	- References: skill-creator methodology, plugin-dev patterns
191	- Examples: Study plugin-dev's own skills as templates
192
193	Use when: Creating new skills for plugins or improving existing skill quality.
194
195
196	## Installation
197
198	Install from claude-code-marketplace:
199
200	```bash
201	/plugin install plugin-dev@claude-code-marketplace
202	```
203
204	Or for development, use directly:
205
206	```bash
207	cc --plugin-dir /path/to/plugin-dev
208	```
209
210	## Quick Start
211
212	### Creating Your First Plugin
213
214	1. Plan your plugin structure:
215	- Ask: "What's the best directory structure for a plugin with commands and MCP integration?"
216	- The plugin-structure skill will guide you
217
218	2. Add MCP integration (if needed):
219	- Ask: "How do I add an MCP server for database access?"
220	- The mcp-integration skill provides examples and patterns
221
222	3. Implement hooks (if needed):
223	- Ask: "Create a PreToolUse hook that validates file writes"
224	- The hook-development skill gives working examples and utilities
225
226
227	## Development Workflow
228
229	The plugin-dev toolkit supports your entire plugin development lifecycle:
230
231	```
232	┌─────────────────────┐
233	│ Design Structure │ → plugin-structure skill
234	│ (manifest, layout) │
235	└──────────┬──────────┘
236	│
237	┌──────────▼──────────┐
238	│ Add Components │
239	│ (commands, agents, │ → All skills provide guidance
240	│ skills, hooks) │
241	└──────────┬──────────┘
242	│
243	┌──────────▼──────────┐
244	│ Integrate Services │ → mcp-integration skill
245	│ (MCP servers) │
246	└──────────┬──────────┘
247	│
248	┌──────────▼──────────┐
249	│ Add Automation │ → hook-development skill
250	│ (hooks, validation)│ + utility scripts
251	└──────────┬──────────┘
252	│
253	┌──────────▼──────────┐
254	│ Test & Validate │ → hook-development utilities
255	│ │ validate-hook-schema.sh
256	└──────────┬──────────┘ test-hook.sh
257	│ hook-linter.sh
258	```
259
260	## Features
261
262	### Progressive Disclosure
263
264	Each skill uses a three-level disclosure system:
265	1. Metadata (always loaded): Concise descriptions with strong triggers
266	2. Core SKILL.md (when triggered): Essential API reference (~1,500-2,000 words)
267	3. References/Examples (as needed): Detailed guides, patterns, and working code
268
269	This keeps Claude Code's context focused while providing deep knowledge when needed.
270
271	### Utility Scripts
272
273	The hook-development skill includes production-ready utilities:
274
275	```bash
276	# Validate hooks.json structure
277	./validate-hook-schema.sh hooks/hooks.json
278
279	# Test hooks before deployment
280	./test-hook.sh my-hook.sh test-input.json
281
282	# Lint hook scripts for best practices
283	./hook-linter.sh my-hook.sh
284	```
285
286	### Working Examples
287
288	Every skill provides working examples:
289	- Hook Development: 3 complete hook scripts (bash, write validation, context loading)
290	- MCP Integration: 3 server configurations (stdio, SSE, HTTP)
291	- Plugin Structure: 3 plugin layouts (minimal, standard, advanced)
292	- Plugin Settings: 3 examples (read-settings hook, create-settings command, templates)
293	- Command Development: 10 complete command examples (review, test, deploy, docs, etc.)
294
295	## Documentation Standards
296
297	All skills follow consistent standards:
298	- Third-person descriptions ("This skill should be used when...")
299	- Strong trigger phrases for reliable loading
300	- Imperative/infinitive form throughout
301	- Based on official Claude Code documentation
302	- Security-first approach with best practices
303
304	## Total Content
305
306	- Core Skills: ~11,065 words across 7 SKILL.md files
307	- Reference Docs: ~10,000+ words of detailed guides
308	- Examples: 12+ working examples (hook scripts, MCP configs, plugin layouts, settings files)
309	- Utilities: 6 production-ready validation/testing/parsing scripts
310
311	## Use Cases
312
313	### Building a Database Plugin
314
315	```
316	1. "What's the structure for a plugin with MCP integration?"
317	→ plugin-structure skill provides layout
318
319	2. "How do I configure an stdio MCP server for PostgreSQL?"
320	→ mcp-integration skill shows configuration
321
322	3. "Add a Stop hook to ensure connections close properly"
323	→ hook-development skill provides pattern
324
325	```
326
327	### Creating a Validation Plugin
328
329	```
330	1. "Create hooks that validate all file writes for security"
331	→ hook-development skill with examples
332
333	2. "Test my hooks before deploying"
334	→ Use validate-hook-schema.sh and test-hook.sh
335
336	3. "Organize my hooks and configuration files"
337	→ plugin-structure skill shows best practices
338
339	```
340
341	### Integrating External Services
342
343	```
344	1. "Add Asana MCP server with OAuth"
345	→ mcp-integration skill covers SSE servers
346
347	2. "Use Asana tools in my commands"
348	→ mcp-integration tool-usage reference
349
350	3. "Structure my plugin with commands and MCP"
351	→ plugin-structure skill provides patterns
352	```
353
354	## Best Practices
355
356	All skills emphasize:
357
358	✅ Security First
359	- Input validation in hooks
360	- HTTPS/WSS for MCP servers
361	- Environment variables for credentials
362	- Principle of least privilege
363
364	✅ Portability
365	- Use ${CLAUDE_PLUGIN_ROOT} everywhere
366	- Relative paths only
367	- Environment variable substitution
368
369	✅ Testing
370	- Validate configurations before deployment
371	- Test hooks with sample inputs
372	- Use debug mode (`claude --debug`)
373
374	✅ Documentation
375	- Clear README files
376	- Documented environment variables
377	- Usage examples
378
379	## Contributing
380
381	This plugin is part of the claude-code-marketplace. To contribute improvements:
382
383	1. Fork the marketplace repository
384	2. Make changes to plugin-dev/
385	3. Test locally with `cc --plugin-dir`
386	4. Create PR following marketplace-publishing guidelines
387
388	## Version
389
390	0.1.0 - Initial release with seven comprehensive skills and three validation agents
391
392	## Author
393
394	Daisy Hollman (daisy@anthropic.com)
395
396	## License
397
398	MIT License - See repository for details
399
400	---
401
402	Note: This toolkit is designed to help you build high-quality plugins. The skills load automatically when you ask relevant questions, providing expert guidance exactly when you need it.