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 / skills / command-development / examples / plugin-commands.md

Daisy S. HollmanMerge pull request #11780 from anthropics/daisy/plugin-dev/public-marketplace c508e59 · on Nov 18, 2025 History

557 lines · 13.7 KBPreview CodeRaw

1	# Plugin Command Examples
2
3	Practical examples of commands designed for Claude Code plugins, demonstrating plugin-specific patterns and features.
4
5	## Table of Contents
6
7	1. [Simple Plugin Command](#1-simple-plugin-command)
8	2. [Script-Based Analysis](#2-script-based-analysis)
9	3. [Template-Based Generation](#3-template-based-generation)
10	4. [Multi-Script Workflow](#4-multi-script-workflow)
11	5. [Configuration-Driven Deployment](#5-configuration-driven-deployment)
12	6. [Agent Integration](#6-agent-integration)
13	7. [Skill Integration](#7-skill-integration)
14	8. [Multi-Component Workflow](#8-multi-component-workflow)
15	9. [Validated Input Command](#9-validated-input-command)
16	10. [Environment-Aware Command](#10-environment-aware-command)
17
18	---
19
20	## 1. Simple Plugin Command
21
22	Use case: Basic command that uses plugin script
23
24	File: `commands/analyze.md`
25
26	```markdown
27	---
28	description: Analyze code quality using plugin tools
29	argument-hint: [file-path]
30	allowed-tools: Bash(node:*), Read
31	---
32
33	Analyze @$1 using plugin's quality checker:
34
35	!`node ${CLAUDE_PLUGIN_ROOT}/scripts/quality-check.js $1`
36
37	Review the analysis output and provide:
38	1. Summary of findings
39	2. Priority issues to address
40	3. Suggested improvements
41	4. Code quality score interpretation
42	```
43
44	Key features:
45	- Uses `${CLAUDE_PLUGIN_ROOT}` for portable path
46	- Combines file reference with script execution
47	- Simple single-purpose command
48
49	---
50
51	## 2. Script-Based Analysis
52
53	Use case: Run comprehensive analysis using multiple plugin scripts
54
55	File: `commands/full-audit.md`
56
57	```markdown
58	---
59	description: Complete code audit using plugin suite
60	argument-hint: [directory]
61	allowed-tools: Bash(*)
62	model: sonnet
63	---
64
65	Running complete audit on $1:
66
67	Security scan:
68	!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh $1`
69
70	Performance analysis:
71	!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-analyze.sh $1`
72
73	Best practices check:
74	!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/best-practices.sh $1`
75
76	Analyze all results and create comprehensive report including:
77	- Critical issues requiring immediate attention
78	- Performance optimization opportunities
79	- Security vulnerabilities and fixes
80	- Overall health score and recommendations
81	```
82
83	Key features:
84	- Multiple script executions
85	- Organized output sections
86	- Comprehensive workflow
87	- Clear reporting structure
88
89	---
90
91	## 3. Template-Based Generation
92
93	Use case: Generate documentation following plugin template
94
95	File: `commands/gen-api-docs.md`
96
97	```markdown
98	---
99	description: Generate API documentation from template
100	argument-hint: [api-file]
101	---
102
103	Template structure: @${CLAUDE_PLUGIN_ROOT}/templates/api-documentation.md
104
105	API implementation: @$1
106
107	Generate complete API documentation following the template format above.
108
109	Ensure documentation includes:
110	- Endpoint descriptions with HTTP methods
111	- Request/response schemas
112	- Authentication requirements
113	- Error codes and handling
114	- Usage examples with curl commands
115	- Rate limiting information
116
117	Format output as markdown suitable for README or docs site.
118	```
119
120	Key features:
121	- Uses plugin template
122	- Combines template with source file
123	- Standardized output format
124	- Clear documentation structure
125
126	---
127
128	## 4. Multi-Script Workflow
129
130	Use case: Orchestrate build, test, and deploy workflow
131
132	File: `commands/release.md`
133
134	```markdown
135	---
136	description: Execute complete release workflow
137	argument-hint: [version]
138	allowed-tools: Bash(*), Read
139	---
140
141	Executing release workflow for version $1:
142
143	Step 1 - Pre-release validation:
144	!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/pre-release-check.sh $1`
145
146	Step 2 - Build artifacts:
147	!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build-release.sh $1`
148
149	Step 3 - Run test suite:
150	!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh`
151
152	Step 4 - Package release:
153	!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/package.sh $1`
154
155	Review all step outputs and report:
156	1. Any failures or warnings
157	2. Build artifacts location
158	3. Test results summary
159	4. Next steps for deployment
160	5. Rollback plan if needed
161	```
162
163	Key features:
164	- Multi-step workflow
165	- Sequential script execution
166	- Clear step numbering
167	- Comprehensive reporting
168
169	---
170
171	## 5. Configuration-Driven Deployment
172
173	Use case: Deploy using environment-specific plugin configuration
174
175	File: `commands/deploy.md`
176
177	```markdown
178	---
179	description: Deploy application to environment
180	argument-hint: [environment]
181	allowed-tools: Read, Bash(*)
182	---
183
184	Deployment configuration for $1: @${CLAUDE_PLUGIN_ROOT}/config/$1-deploy.json
185
186	Current git state: !`git rev-parse --short HEAD`
187
188	Build info: !`cat package.json \| grep -E '(name\|version)'`
189
190	Execute deployment to $1 environment using configuration above.
191
192	Deployment checklist:
193	1. Validate configuration settings
194	2. Build application for $1
195	3. Run pre-deployment tests
196	4. Deploy to target environment
197	5. Run smoke tests
198	6. Verify deployment success
199	7. Update deployment log
200
201	Report deployment status and any issues encountered.
202	```
203
204	Key features:
205	- Environment-specific configuration
206	- Dynamic config file loading
207	- Pre-deployment validation
208	- Structured checklist
209
210	---
211
212	## 6. Agent Integration
213
214	Use case: Command that launches plugin agent for complex task
215
216	File: `commands/deep-review.md`
217
218	```markdown
219	---
220	description: Deep code review using plugin agent
221	argument-hint: [file-or-directory]
222	---
223
224	Initiate comprehensive code review of @$1 using the code-reviewer agent.
225
226	The agent will perform:
227	1. Static analysis - Check for code smells and anti-patterns
228	2. Security audit - Identify potential vulnerabilities
229	3. Performance review - Find optimization opportunities
230	4. Best practices - Ensure code follows standards
231	5. Documentation check - Verify adequate documentation
232
233	The agent has access to:
234	- Plugin's linting rules: ${CLAUDE_PLUGIN_ROOT}/config/lint-rules.json
235	- Security checklist: ${CLAUDE_PLUGIN_ROOT}/checklists/security.md
236	- Performance guidelines: ${CLAUDE_PLUGIN_ROOT}/docs/performance.md
237
238	Note: This uses the Task tool to launch the plugin's code-reviewer agent for thorough analysis.
239	```
240
241	Key features:
242	- Delegates to plugin agent
243	- Documents agent capabilities
244	- References plugin resources
245	- Clear scope definition
246
247	---
248
249	## 7. Skill Integration
250
251	Use case: Command that leverages plugin skill for specialized knowledge
252
253	File: `commands/document-api.md`
254
255	```markdown
256	---
257	description: Document API following plugin standards
258	argument-hint: [api-file]
259	---
260
261	API source code: @$1
262
263	Generate API documentation following the plugin's API documentation standards.
264
265	Use the api-documentation-standards skill to ensure:
266	- OpenAPI compliance - Follow OpenAPI 3.0 specification
267	- Consistent formatting - Use plugin's documentation style
268	- Complete coverage - Document all endpoints and schemas
269	- Example quality - Provide realistic usage examples
270	- Error documentation - Cover all error scenarios
271
272	The skill provides:
273	- Standard documentation templates
274	- API documentation best practices
275	- Common patterns for this codebase
276	- Quality validation criteria
277
278	Generate production-ready API documentation.
279	```
280
281	Key features:
282	- Invokes plugin skill by name
283	- Documents skill purpose
284	- Clear expectations
285	- Leverages skill knowledge
286
287	---
288
289	## 8. Multi-Component Workflow
290
291	Use case: Complex workflow using agents, skills, and scripts
292
293	File: `commands/complete-review.md`
294
295	```markdown
296	---
297	description: Comprehensive review using all plugin components
298	argument-hint: [file-path]
299	allowed-tools: Bash(node:*), Read
300	---
301
302	Target file: @$1
303
304	Execute comprehensive review workflow:
305
306	Phase 1: Automated Analysis
307	Run plugin analyzer: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js $1`
308
309	Phase 2: Deep Review (Agent)
310	Launch the code-quality-reviewer agent for detailed analysis.
311	Agent will examine:
312	- Code structure and organization
313	- Error handling patterns
314	- Testing coverage
315	- Documentation quality
316
317	Phase 3: Standards Check (Skill)
318	Use the coding-standards skill to validate:
319	- Naming conventions
320	- Code formatting
321	- Best practices adherence
322	- Framework-specific patterns
323
324	Phase 4: Report Generation
325	Template: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md
326
327	Compile all findings into comprehensive report following template.
328
329	Phase 5: Recommendations
330	Generate prioritized action items:
331	1. Critical issues (must fix)
332	2. Important improvements (should fix)
333	3. Nice-to-have enhancements (could fix)
334
335	Include specific file locations and suggested changes for each item.
336	```
337
338	Key features:
339	- Multi-phase workflow
340	- Combines scripts, agents, skills
341	- Template-based reporting
342	- Prioritized outputs
343
344	---
345
346	## 9. Validated Input Command
347
348	Use case: Command with input validation and error handling
349
350	File: `commands/build-env.md`
351
352	```markdown
353	---
354	description: Build for specific environment with validation
355	argument-hint: [environment]
356	allowed-tools: Bash(*)
357	---
358
359	Validate environment argument: !`echo "$1" \| grep -E "^(dev\|staging\|prod)$" && echo "VALID" \|\| echo "INVALID"`
360
361	Check build script exists: !`test -x ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh && echo "EXISTS" \|\| echo "MISSING"`
362
363	Verify configuration available: !`test -f ${CLAUDE_PLUGIN_ROOT}/config/$1.json && echo "FOUND" \|\| echo "NOT_FOUND"`
364
365	If all validations pass:
366
367	Configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1.json
368
369	Execute build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh $1 2>&1`
370
371	Validation results: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-build.sh $1 2>&1`
372
373	Report build status and any issues.
374
375	If validations fail:
376	- Explain which validation failed
377	- Provide expected values/locations
378	- Suggest corrective actions
379	- Document troubleshooting steps
380	```
381
382	Key features:
383	- Input validation
384	- Resource existence checks
385	- Error handling
386	- Helpful error messages
387	- Graceful failure handling
388
389	---
390
391	## 10. Environment-Aware Command
392
393	Use case: Command that adapts behavior based on environment
394
395	File: `commands/run-checks.md`
396
397	```markdown
398	---
399	description: Run environment-appropriate checks
400	argument-hint: [environment]
401	allowed-tools: Bash(*), Read
402	---
403
404	Environment: $1
405
406	Load environment configuration: @${CLAUDE_PLUGIN_ROOT}/config/$1-checks.json
407
408	Determine check level: !`echo "$1" \| grep -E "^prod$" && echo "FULL" \|\| echo "BASIC"`
409
410	For production environment:
411	- Full test suite: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-full.sh`
412	- Security scan: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/security-scan.sh`
413	- Performance audit: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/perf-check.sh`
414	- Compliance check: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/compliance.sh`
415
416	For non-production environments:
417	- Basic tests: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test-basic.sh`
418	- Quick lint: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh`
419
420	Analyze results based on environment requirements:
421
422	Production: All checks must pass with zero critical issues
423	Staging: No critical issues, warnings acceptable
424	Development: Focus on blocking issues only
425
426	Report status and recommend proceed/block decision.
427	```
428
429	Key features:
430	- Environment-aware logic
431	- Conditional execution
432	- Different validation levels
433	- Appropriate reporting per environment
434
435	---
436
437	## Common Patterns Summary
438
439	### Pattern: Plugin Script Execution
440	```markdown
441	!`node ${CLAUDE_PLUGIN_ROOT}/scripts/script-name.js $1`
442	```
443	Use for: Running plugin-provided Node.js scripts
444
445	### Pattern: Plugin Configuration Loading
446	```markdown
447	@${CLAUDE_PLUGIN_ROOT}/config/config-name.json
448	```
449	Use for: Loading plugin configuration files
450
451	### Pattern: Plugin Template Usage
452	```markdown
453	@${CLAUDE_PLUGIN_ROOT}/templates/template-name.md
454	```
455	Use for: Using plugin templates for generation
456
457	### Pattern: Agent Invocation
458	```markdown
459	Launch the [agent-name] agent for [task description].
460	```
461	Use for: Delegating complex tasks to plugin agents
462
463	### Pattern: Skill Reference
464	```markdown
465	Use the [skill-name] skill to ensure [requirements].
466	```
467	Use for: Leveraging plugin skills for specialized knowledge
468
469	### Pattern: Input Validation
470	```markdown
471	Validate input: !`echo "$1" \| grep -E "^pattern$" && echo "OK" \|\| echo "ERROR"`
472	```
473	Use for: Validating command arguments
474
475	### Pattern: Resource Validation
476	```markdown
477	Check exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/path/file && echo "YES" \|\| echo "NO"`
478	```
479	Use for: Verifying required plugin files exist
480
481	---
482
483	## Development Tips
484
485	### Testing Plugin Commands
486
487	1. Test with plugin installed:
488	```bash
489	cd /path/to/plugin
490	claude /command-name args
491	```
492
493	2. Verify ${CLAUDE_PLUGIN_ROOT} expansion:
494	```bash
495	# Add debug output to command
496	!`echo "Plugin root: ${CLAUDE_PLUGIN_ROOT}"`
497	```
498
499	3. Test across different working directories:
500	```bash
501	cd /tmp && claude /command-name
502	cd /other/project && claude /command-name
503	```
504
505	4. Validate resource availability:
506	```bash
507	# Check all plugin resources exist
508	!`ls -la ${CLAUDE_PLUGIN_ROOT}/scripts/`
509	!`ls -la ${CLAUDE_PLUGIN_ROOT}/config/`
510	```
511
512	### Common Mistakes to Avoid
513
514	1. Using relative paths instead of ${CLAUDE_PLUGIN_ROOT}:
515	```markdown
516	# Wrong
517	!`node ./scripts/analyze.js`
518
519	# Correct
520	!`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`
521	```
522
523	2. Forgetting to allow required tools:
524	```markdown
525	# Missing allowed-tools
526	!`bash script.sh` # Will fail without Bash permission
527
528	# Correct
529	---
530	allowed-tools: Bash(*)
531	---
532	!`bash ${CLAUDE_PLUGIN_ROOT}/scripts/script.sh`
533	```
534
535	3. Not validating inputs:
536	```markdown
537	# Risky - no validation
538	Deploy to $1 environment
539
540	# Better - with validation
541	Validate: !`echo "$1" \| grep -E "^(dev\|staging\|prod)$" \|\| echo "INVALID"`
542	Deploy to $1 environment (if valid)
543	```
544
545	4. Hardcoding plugin paths:
546	```markdown
547	# Wrong - breaks on different installations
548	@/home/user/.claude/plugins/my-plugin/config.json
549
550	# Correct - works everywhere
551	@${CLAUDE_PLUGIN_ROOT}/config.json
552	```
553
554	---
555
556	For detailed plugin-specific features, see `references/plugin-features-reference.md`.
557	For general command development, see main `SKILL.md`.