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 / commands / create-plugin.md

415 lines · 14.6 KBPreview CodeRaw

1	---
2	description: Guided end-to-end plugin creation workflow with component design, implementation, and validation
3	argument-hint: Optional plugin description
4	allowed-tools: ["Read", "Write", "Grep", "Glob", "Bash", "TodoWrite", "AskUserQuestion", "Skill", "Task"]
5	---
6
7	# Plugin Creation Workflow
8
9	Guide the user through creating a complete, high-quality Claude Code plugin from initial concept to tested implementation. Follow a systematic approach: understand requirements, design components, clarify details, implement following best practices, validate, and test.
10
11	## Core Principles
12
13	- Ask clarifying questions: Identify all ambiguities about plugin purpose, triggering, scope, and components. Ask specific, concrete questions rather than making assumptions. Wait for user answers before proceeding with implementation.
14	- Load relevant skills: Use the Skill tool to load plugin-dev skills when needed (plugin-structure, hook-development, agent-development, etc.)
15	- Use specialized agents: Leverage agent-creator, plugin-validator, and skill-reviewer agents for AI-assisted development
16	- Follow best practices: Apply patterns from plugin-dev's own implementation
17	- Progressive disclosure: Create lean skills with references/examples
18	- Use TodoWrite: Track all progress throughout all phases
19
20	Initial request: $ARGUMENTS
21
22	---
23
24	## Phase 1: Discovery
25
26	Goal: Understand what plugin needs to be built and what problem it solves
27
28	Actions:
29	1. Create todo list with all 7 phases
30	2. If plugin purpose is clear from arguments:
31	- Summarize understanding
32	- Identify plugin type (integration, workflow, analysis, toolkit, etc.)
33	3. If plugin purpose is unclear, ask user:
34	- What problem does this plugin solve?
35	- Who will use it and when?
36	- What should it do?
37	- Any similar plugins to reference?
38	4. Summarize understanding and confirm with user before proceeding
39
40	Output: Clear statement of plugin purpose and target users
41
42	---
43
44	## Phase 2: Component Planning
45
46	Goal: Determine what plugin components are needed
47
48	MUST load plugin-structure skill using Skill tool before this phase.
49
50	Actions:
51	1. Load plugin-structure skill to understand component types
52	2. Analyze plugin requirements and determine needed components:
53	- Skills: Does it need specialized knowledge? (hooks API, MCP patterns, etc.)
54	- Commands: User-initiated actions? (deploy, configure, analyze)
55	- Agents: Autonomous tasks? (validation, generation, analysis)
56	- Hooks: Event-driven automation? (validation, notifications)
57	- MCP: External service integration? (databases, APIs)
58	- Settings: User configuration? (.local.md files)
59	3. For each component type needed, identify:
60	- How many of each type
61	- What each one does
62	- Rough triggering/usage patterns
63	4. Present component plan to user as table:
64	```
65	\| Component Type \| Count \| Purpose \|
66	\|----------------\|-------\|---------\|
67	\| Skills \| 2 \| Hook patterns, MCP usage \|
68	\| Commands \| 3 \| Deploy, configure, validate \|
69	\| Agents \| 1 \| Autonomous validation \|
70	\| Hooks \| 0 \| Not needed \|
71	\| MCP \| 1 \| Database integration \|
72	```
73	5. Get user confirmation or adjustments
74
75	Output: Confirmed list of components to create
76
77	---
78
79	## Phase 3: Detailed Design & Clarifying Questions
80
81	Goal: Specify each component in detail and resolve all ambiguities
82
83	CRITICAL: This is one of the most important phases. DO NOT SKIP.
84
85	Actions:
86	1. For each component in the plan, identify underspecified aspects:
87	- Skills: What triggers them? What knowledge do they provide? How detailed?
88	- Commands: What arguments? What tools? Interactive or automated?
89	- Agents: When to trigger (proactive/reactive)? What tools? Output format?
90	- Hooks: Which events? Prompt or command based? Validation criteria?
91	- MCP: What server type? Authentication? Which tools?
92	- Settings: What fields? Required vs optional? Defaults?
93
94	2. Present all questions to user in organized sections (one section per component type)
95
96	3. Wait for answers before proceeding to implementation
97
98	4. If user says "whatever you think is best", provide specific recommendations and get explicit confirmation
99
100	Example questions for a skill:
101	- What specific user queries should trigger this skill?
102	- Should it include utility scripts? What functionality?
103	- How detailed should the core SKILL.md be vs references/?
104	- Any real-world examples to include?
105
106	Example questions for an agent:
107	- Should this agent trigger proactively after certain actions, or only when explicitly requested?
108	- What tools does it need (Read, Write, Bash, etc.)?
109	- What should the output format be?
110	- Any specific quality standards to enforce?
111
112	Output: Detailed specification for each component
113
114	---
115
116	## Phase 4: Plugin Structure Creation
117
118	Goal: Create plugin directory structure and manifest
119
120	Actions:
121	1. Determine plugin name (kebab-case, descriptive)
122	2. Choose plugin location:
123	- Ask user: "Where should I create the plugin?"
124	- Offer options: current directory, ../new-plugin-name, custom path
125	3. Create directory structure using bash:
126	```bash
127	mkdir -p plugin-name/.claude-plugin
128	mkdir -p plugin-name/skills # if needed
129	mkdir -p plugin-name/commands # if needed
130	mkdir -p plugin-name/agents # if needed
131	mkdir -p plugin-name/hooks # if needed
132	```
133	4. Create plugin.json manifest using Write tool:
134	```json
135	{
136	"name": "plugin-name",
137	"version": "0.1.0",
138	"description": "[brief description]",
139	"author": {
140	"name": "[author from user or default]",
141	"email": "[email or default]"
142	}
143	}
144	```
145	5. Create README.md template
146	6. Create .gitignore if needed (for .claude/*.local.md, etc.)
147	7. Initialize git repo if creating new directory
148
149	Output: Plugin directory structure created and ready for components
150
151	---
152
153	## Phase 5: Component Implementation
154
155	Goal: Create each component following best practices
156
157	LOAD RELEVANT SKILLS before implementing each component type:
158	- Skills: Load skill-development skill
159	- Commands: Load command-development skill
160	- Agents: Load agent-development skill
161	- Hooks: Load hook-development skill
162	- MCP: Load mcp-integration skill
163	- Settings: Load plugin-settings skill
164
165	Actions for each component:
166
167	### For Skills:
168	1. Load skill-development skill using Skill tool
169	2. For each skill:
170	- Ask user for concrete usage examples (or use from Phase 3)
171	- Plan resources (scripts/, references/, examples/)
172	- Create skill directory structure
173	- Write SKILL.md with:
174	- Third-person description with specific trigger phrases
175	- Lean body (1,500-2,000 words) in imperative form
176	- References to supporting files
177	- Create reference files for detailed content
178	- Create example files for working code
179	- Create utility scripts if needed
180	3. Use skill-reviewer agent to validate each skill
181
182	### For Commands:
183	1. Load command-development skill using Skill tool
184	2. For each command:
185	- Write command markdown with frontmatter
186	- Include clear description and argument-hint
187	- Specify allowed-tools (minimal necessary)
188	- Write instructions FOR Claude (not TO user)
189	- Provide usage examples and tips
190	- Reference relevant skills if applicable
191
192	### For Agents:
193	1. Load agent-development skill using Skill tool
194	2. For each agent, use agent-creator agent:
195	- Provide description of what agent should do
196	- Agent-creator generates: identifier, whenToUse with examples, systemPrompt
197	- Create agent markdown file with frontmatter and system prompt
198	- Add appropriate model, color, and tools
199	- Validate with validate-agent.sh script
200
201	### For Hooks:
202	1. Load hook-development skill using Skill tool
203	2. For each hook:
204	- Create hooks/hooks.json with hook configuration
205	- Prefer prompt-based hooks for complex logic
206	- Use ${CLAUDE_PLUGIN_ROOT} for portability
207	- Create hook scripts if needed (in examples/ not scripts/)
208	- Test with validate-hook-schema.sh and test-hook.sh utilities
209
210	### For MCP:
211	1. Load mcp-integration skill using Skill tool
212	2. Create .mcp.json configuration with:
213	- Server type (stdio for local, SSE for hosted)
214	- Command and args (with ${CLAUDE_PLUGIN_ROOT})
215	- extensionToLanguage mapping if LSP
216	- Environment variables as needed
217	3. Document required env vars in README
218	4. Provide setup instructions
219
220	### For Settings:
221	1. Load plugin-settings skill using Skill tool
222	2. Create settings template in README
223	3. Create example .claude/plugin-name.local.md file (as documentation)
224	4. Implement settings reading in hooks/commands as needed
225	5. Add to .gitignore: `.claude/*.local.md`
226
227	Progress tracking: Update todos as each component is completed
228
229	Output: All plugin components implemented
230
231	---
232
233	## Phase 6: Validation & Quality Check
234
235	Goal: Ensure plugin meets quality standards and works correctly
236
237	Actions:
238	1. Run plugin-validator agent:
239	- Use plugin-validator agent to comprehensively validate plugin
240	- Check: manifest, structure, naming, components, security
241	- Review validation report
242
243	2. Fix critical issues:
244	- Address any critical errors from validation
245	- Fix any warnings that indicate real problems
246
247	3. Review with skill-reviewer (if plugin has skills):
248	- For each skill, use skill-reviewer agent
249	- Check description quality, progressive disclosure, writing style
250	- Apply recommendations
251
252	4. Test agent triggering (if plugin has agents):
253	- For each agent, verify <example> blocks are clear
254	- Check triggering conditions are specific
255	- Run validate-agent.sh on agent files
256
257	5. Test hook configuration (if plugin has hooks):
258	- Run validate-hook-schema.sh on hooks/hooks.json
259	- Test hook scripts with test-hook.sh
260	- Verify ${CLAUDE_PLUGIN_ROOT} usage
261
262	6. Present findings:
263	- Summary of validation results
264	- Any remaining issues
265	- Overall quality assessment
266
267	7. Ask user: "Validation complete. Issues found: [count critical], [count warnings]. Would you like me to fix them now, or proceed to testing?"
268
269	Output: Plugin validated and ready for testing
270
271	---
272
273	## Phase 7: Testing & Verification
274
275	Goal: Test that plugin works correctly in Claude Code
276
277	Actions:
278	1. Installation instructions:
279	- Show user how to test locally:
280	```bash
281	cc --plugin-dir /path/to/plugin-name
282	```
283	- Or copy to `.claude-plugin/` for project testing
284
285	2. Verification checklist for user to perform:
286	- [ ] Skills load when triggered (ask questions with trigger phrases)
287	- [ ] Commands appear in `/help` and execute correctly
288	- [ ] Agents trigger on appropriate scenarios
289	- [ ] Hooks activate on events (if applicable)
290	- [ ] MCP servers connect (if applicable)
291	- [ ] Settings files work (if applicable)
292
293	3. Testing recommendations:
294	- For skills: Ask questions using trigger phrases from descriptions
295	- For commands: Run `/plugin-name:command-name` with various arguments
296	- For agents: Create scenarios matching agent examples
297	- For hooks: Use `claude --debug` to see hook execution
298	- For MCP: Use `/mcp` to verify servers and tools
299
300	4. Ask user: "I've prepared the plugin for testing. Would you like me to guide you through testing each component, or do you want to test it yourself?"
301
302	5. If user wants guidance, walk through testing each component with specific test cases
303
304	Output: Plugin tested and verified working
305
306	---
307
308	## Phase 8: Documentation & Next Steps
309
310	Goal: Ensure plugin is well-documented and ready for distribution
311
312	Actions:
313	1. Verify README completeness:
314	- Check README has: overview, features, installation, prerequisites, usage
315	- For MCP plugins: Document required environment variables
316	- For hook plugins: Explain hook activation
317	- For settings: Provide configuration templates
318
319	2. Add marketplace entry (if publishing):
320	- Show user how to add to marketplace.json
321	- Help draft marketplace description
322	- Suggest category and tags
323
324	3. Create summary:
325	- Mark all todos complete
326	- List what was created:
327	- Plugin name and purpose
328	- Components created (X skills, Y commands, Z agents, etc.)
329	- Key files and their purposes
330	- Total file count and structure
331	- Next steps:
332	- Testing recommendations
333	- Publishing to marketplace (if desired)
334	- Iteration based on usage
335
336	4. Suggest improvements (optional):
337	- Additional components that could enhance plugin
338	- Integration opportunities
339	- Testing strategies
340
341	Output: Complete, documented plugin ready for use or publication
342
343	---
344
345	## Important Notes
346
347	### Throughout All Phases
348
349	- Use TodoWrite to track progress at every phase
350	- Load skills with Skill tool when working on specific component types
351	- Use specialized agents (agent-creator, plugin-validator, skill-reviewer)
352	- Ask for user confirmation at key decision points
353	- Follow plugin-dev's own patterns as reference examples
354	- Apply best practices:
355	- Third-person descriptions for skills
356	- Imperative form in skill bodies
357	- Commands written FOR Claude
358	- Strong trigger phrases
359	- ${CLAUDE_PLUGIN_ROOT} for portability
360	- Progressive disclosure
361	- Security-first (HTTPS, no hardcoded credentials)
362
363	### Key Decision Points (Wait for User)
364
365	1. After Phase 1: Confirm plugin purpose
366	2. After Phase 2: Approve component plan
367	3. After Phase 3: Proceed to implementation
368	4. After Phase 6: Fix issues or proceed
369	5. After Phase 7: Continue to documentation
370
371	### Skills to Load by Phase
372
373	- Phase 2: plugin-structure
374	- Phase 5: skill-development, command-development, agent-development, hook-development, mcp-integration, plugin-settings (as needed)
375	- Phase 6: (agents will use skills automatically)
376
377	### Quality Standards
378
379	Every component must meet these standards:
380	- ✅ Follows plugin-dev's proven patterns
381	- ✅ Uses correct naming conventions
382	- ✅ Has strong trigger conditions (skills/agents)
383	- ✅ Includes working examples
384	- ✅ Properly documented
385	- ✅ Validated with utilities
386	- ✅ Tested in Claude Code
387
388	---
389
390	## Example Workflow
391
392	### User Request
393	"Create a plugin for managing database migrations"
394
395	### Phase 1: Discovery
396	- Understand: Migration management, database schema versioning
397	- Confirm: User wants to create, run, rollback migrations
398
399	### Phase 2: Component Planning
400	- Skills: 1 (migration best practices)
401	- Commands: 3 (create-migration, run-migrations, rollback)
402	- Agents: 1 (migration-validator)
403	- MCP: 1 (database connection)
404
405	### Phase 3: Clarifying Questions
406	- Which databases? (PostgreSQL, MySQL, etc.)
407	- Migration file format? (SQL, code-based?)
408	- Should agent validate before applying?
409	- What MCP tools needed? (query, execute, schema)
410
411	### Phase 4-8: Implementation, Validation, Testing, Documentation
412
413	---
414
415	Begin with Phase 1: Discovery