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 / references / plugin-features-reference.md

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

609 lines · 14.3 KBPreview CodeRaw

1	# Plugin-Specific Command Features Reference
2
3	This reference covers features and patterns specific to commands bundled in Claude Code plugins.
4
5	## Table of Contents
6
7	- [Plugin Command Discovery](#plugin-command-discovery)
8	- [CLAUDE_PLUGIN_ROOT Environment Variable](#claude_plugin_root-environment-variable)
9	- [Plugin Command Patterns](#plugin-command-patterns)
10	- [Integration with Plugin Components](#integration-with-plugin-components)
11	- [Validation Patterns](#validation-patterns)
12
13	## Plugin Command Discovery
14
15	### Auto-Discovery
16
17	Claude Code automatically discovers commands in plugins using the following locations:
18
19	```
20	plugin-name/
21	├── commands/ # Auto-discovered commands
22	│ ├── foo.md # /foo (plugin:plugin-name)
23	│ └── bar.md # /bar (plugin:plugin-name)
24	└── plugin.json # Plugin manifest
25	```
26
27	Key points:
28	- Commands are discovered at plugin load time
29	- No manual registration required
30	- Commands appear in `/help` with "(plugin:plugin-name)" label
31	- Subdirectories create namespaces
32
33	### Namespaced Plugin Commands
34
35	Organize commands in subdirectories for logical grouping:
36
37	```
38	plugin-name/
39	└── commands/
40	├── review/
41	│ ├── security.md # /security (plugin:plugin-name:review)
42	│ └── style.md # /style (plugin:plugin-name:review)
43	└── deploy/
44	├── staging.md # /staging (plugin:plugin-name:deploy)
45	└── prod.md # /prod (plugin:plugin-name:deploy)
46	```
47
48	Namespace behavior:
49	- Subdirectory name becomes namespace
50	- Shown as "(plugin:plugin-name:namespace)" in `/help`
51	- Helps organize related commands
52	- Use when plugin has 5+ commands
53
54	### Command Naming Conventions
55
56	Plugin command names should:
57	1. Be descriptive and action-oriented
58	2. Avoid conflicts with common command names
59	3. Use hyphens for multi-word names
60	4. Consider prefixing with plugin name for uniqueness
61
62	Examples:
63	```
64	Good:
65	- /mylyn-sync (plugin-specific prefix)
66	- /analyze-performance (descriptive action)
67	- /docker-compose-up (clear purpose)
68
69	Avoid:
70	- /test (conflicts with common name)
71	- /run (too generic)
72	- /do-stuff (not descriptive)
73	```
74
75	## CLAUDE_PLUGIN_ROOT Environment Variable
76
77	### Purpose
78
79	`${CLAUDE_PLUGIN_ROOT}` is a special environment variable available in plugin commands that resolves to the absolute path of the plugin directory.
80
81	Why it matters:
82	- Enables portable paths within plugin
83	- Allows referencing plugin files and scripts
84	- Works across different installations
85	- Essential for multi-file plugin operations
86
87	### Basic Usage
88
89	Reference files within your plugin:
90
91	```markdown
92	---
93	description: Analyze using plugin script
94	allowed-tools: Bash(node:*), Read
95	---
96
97	Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`
98
99	Read template: @${CLAUDE_PLUGIN_ROOT}/templates/report.md
100	```
101
102	Expands to:
103	```
104	Run analysis: !`node /path/to/plugins/plugin-name/scripts/analyze.js`
105
106	Read template: @/path/to/plugins/plugin-name/templates/report.md
107	```
108
109	### Common Patterns
110
111	#### 1. Executing Plugin Scripts
112
113	```markdown
114	---
115	description: Run custom linter from plugin
116	allowed-tools: Bash(node:*)
117	---
118
119	Lint results: !`node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1`
120
121	Review the linting output and suggest fixes.
122	```
123
124	#### 2. Loading Configuration Files
125
126	```markdown
127	---
128	description: Deploy using plugin configuration
129	allowed-tools: Read, Bash(*)
130	---
131
132	Configuration: @${CLAUDE_PLUGIN_ROOT}/config/deploy-config.json
133
134	Deploy application using the configuration above for $1 environment.
135	```
136
137	#### 3. Accessing Plugin Resources
138
139	```markdown
140	---
141	description: Generate report from template
142	---
143
144	Use this template: @${CLAUDE_PLUGIN_ROOT}/templates/api-report.md
145
146	Generate a report for @$1 following the template format.
147	```
148
149	#### 4. Multi-Step Plugin Workflows
150
151	```markdown
152	---
153	description: Complete plugin workflow
154	allowed-tools: Bash(*), Read
155	---
156
157	Step 1 - Prepare: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/prepare.sh $1`
158	Step 2 - Config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json
159	Step 3 - Execute: !`${CLAUDE_PLUGIN_ROOT}/bin/execute $1`
160
161	Review results and report status.
162	```
163
164	### Best Practices
165
166	1. Always use for plugin-internal paths:
167	```markdown
168	# Good
169	@${CLAUDE_PLUGIN_ROOT}/templates/foo.md
170
171	# Bad
172	@./templates/foo.md # Relative to current directory, not plugin
173	```
174
175	2. Validate file existence:
176	```markdown
177	---
178	description: Use plugin config if exists
179	allowed-tools: Bash(test:*), Read
180	---
181
182	!`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "exists" \|\| echo "missing"`
183
184	If config exists, load it: @${CLAUDE_PLUGIN_ROOT}/config.json
185	Otherwise, use defaults...
186	```
187
188	3. Document plugin file structure:
189	```markdown
190	<!--
191	Plugin structure:
192	${CLAUDE_PLUGIN_ROOT}/
193	├── scripts/analyze.js (analysis script)
194	├── templates/ (report templates)
195	└── config/ (configuration files)
196	-->
197	```
198
199	4. Combine with arguments:
200	```markdown
201	Run: !`${CLAUDE_PLUGIN_ROOT}/bin/process.sh $1 $2`
202	```
203
204	### Troubleshooting
205
206	Variable not expanding:
207	- Ensure command is loaded from plugin
208	- Check bash execution is allowed
209	- Verify syntax is exact: `${CLAUDE_PLUGIN_ROOT}`
210
211	File not found errors:
212	- Verify file exists in plugin directory
213	- Check file path is correct relative to plugin root
214	- Ensure file permissions allow reading/execution
215
216	Path with spaces:
217	- Bash commands automatically handle spaces
218	- File references work with spaces in paths
219	- No special quoting needed
220
221	## Plugin Command Patterns
222
223	### Pattern 1: Configuration-Based Commands
224
225	Commands that load plugin-specific configuration:
226
227	```markdown
228	---
229	description: Deploy using plugin settings
230	allowed-tools: Read, Bash(*)
231	---
232
233	Load configuration: @${CLAUDE_PLUGIN_ROOT}/deploy-config.json
234
235	Deploy to $1 environment using:
236	1. Configuration settings above
237	2. Current git branch: !`git branch --show-current`
238	3. Application version: !`cat package.json \| grep version`
239
240	Execute deployment and monitor progress.
241	```
242
243	When to use: Commands that need consistent settings across invocations
244
245	### Pattern 2: Template-Based Generation
246
247	Commands that use plugin templates:
248
249	```markdown
250	---
251	description: Generate documentation from template
252	argument-hint: [component-name]
253	---
254
255	Template: @${CLAUDE_PLUGIN_ROOT}/templates/component-docs.md
256
257	Generate documentation for $1 component following the template structure.
258	Include:
259	- Component purpose and usage
260	- API reference
261	- Examples
262	- Testing guidelines
263	```
264
265	When to use: Standardized output generation
266
267	### Pattern 3: Multi-Script Workflow
268
269	Commands that orchestrate multiple plugin scripts:
270
271	```markdown
272	---
273	description: Complete build and test workflow
274	allowed-tools: Bash(*)
275	---
276
277	Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
278	Validate: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh`
279	Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
280
281	Review all outputs and report:
282	1. Build status
283	2. Validation results
284	3. Test results
285	4. Recommended next steps
286	```
287
288	When to use: Complex plugin workflows with multiple steps
289
290	### Pattern 4: Environment-Aware Commands
291
292	Commands that adapt to environment:
293
294	```markdown
295	---
296	description: Deploy based on environment
297	argument-hint: [dev\|staging\|prod]
298	---
299
300	Environment config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json
301
302	Environment check: !`echo "Deploying to: $1"`
303
304	Deploy application using $1 environment configuration.
305	Verify deployment and run smoke tests.
306	```
307
308	When to use: Commands that behave differently per environment
309
310	### Pattern 5: Plugin Data Management
311
312	Commands that manage plugin-specific data:
313
314	```markdown
315	---
316	description: Save analysis results to plugin cache
317	allowed-tools: Bash(*), Read, Write
318	---
319
320	Cache directory: ${CLAUDE_PLUGIN_ROOT}/cache/
321
322	Analyze @$1 and save results to cache:
323	!`mkdir -p ${CLAUDE_PLUGIN_ROOT}/cache && date > ${CLAUDE_PLUGIN_ROOT}/cache/last-run.txt`
324
325	Store analysis for future reference and comparison.
326	```
327
328	When to use: Commands that need persistent data storage
329
330	## Integration with Plugin Components
331
332	### Invoking Plugin Agents
333
334	Commands can trigger plugin agents using the Task tool:
335
336	```markdown
337	---
338	description: Deep analysis using plugin agent
339	argument-hint: [file-path]
340	---
341
342	Initiate deep code analysis of @$1 using the code-analyzer agent.
343
344	The agent will:
345	1. Analyze code structure
346	2. Identify patterns
347	3. Suggest improvements
348	4. Generate detailed report
349
350	Note: This uses the Task tool to launch the plugin's code-analyzer agent.
351	```
352
353	Key points:
354	- Agent must be defined in plugin's `agents/` directory
355	- Claude will automatically use Task tool to launch agent
356	- Agent has access to same plugin resources
357
358	### Invoking Plugin Skills
359
360	Commands can reference plugin skills for specialized knowledge:
361
362	```markdown
363	---
364	description: API documentation with best practices
365	argument-hint: [api-file]
366	---
367
368	Document the API in @$1 following our API documentation standards.
369
370	Use the api-docs-standards skill to ensure documentation includes:
371	- Endpoint descriptions
372	- Parameter specifications
373	- Response formats
374	- Error codes
375	- Usage examples
376
377	Note: This leverages the plugin's api-docs-standards skill for consistency.
378	```
379
380	Key points:
381	- Skill must be defined in plugin's `skills/` directory
382	- Mention skill by name to hint Claude should invoke it
383	- Skills provide specialized domain knowledge
384
385	### Coordinating with Plugin Hooks
386
387	Commands can be designed to work with plugin hooks:
388
389	```markdown
390	---
391	description: Commit with pre-commit validation
392	allowed-tools: Bash(git:*)
393	---
394
395	Stage changes: !\`git add $1\`
396
397	Commit changes: !\`git commit -m "$2"\`
398
399	Note: This commit will trigger the plugin's pre-commit hook for validation.
400	Review hook output for any issues.
401	```
402
403	Key points:
404	- Hooks execute automatically on events
405	- Commands can prepare state for hooks
406	- Document hook interaction in command
407
408	### Multi-Component Plugin Commands
409
410	Commands that coordinate multiple plugin components:
411
412	```markdown
413	---
414	description: Comprehensive code review workflow
415	argument-hint: [file-path]
416	---
417
418	File to review: @$1
419
420	Execute comprehensive review:
421
422	1. Static Analysis (via plugin scripts)
423	!`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`
424
425	2. Deep Review (via plugin agent)
426	Launch the code-reviewer agent for detailed analysis.
427
428	3. Best Practices (via plugin skill)
429	Use the code-standards skill to ensure compliance.
430
431	4. Documentation (via plugin template)
432	Template: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md
433
434	Generate final report combining all outputs.
435	```
436
437	When to use: Complex workflows leveraging multiple plugin capabilities
438
439	## Validation Patterns
440
441	### Input Validation
442
443	Commands should validate inputs before processing:
444
445	```markdown
446	---
447	description: Deploy to environment with validation
448	argument-hint: [environment]
449	---
450
451	Validate environment: !`echo "$1" \| grep -E "^(dev\|staging\|prod)$" \|\| echo "INVALID"`
452
453	$IF($1 in [dev, staging, prod],
454	Deploy to $1 environment using validated configuration,
455	ERROR: Invalid environment '$1'. Must be one of: dev, staging, prod
456	)
457	```
458
459	Validation approaches:
460	1. Bash validation using grep/test
461	2. Inline validation in prompt
462	3. Script-based validation
463
464	### File Existence Checks
465
466	Verify required files exist:
467
468	```markdown
469	---
470	description: Process configuration file
471	argument-hint: [config-file]
472	---
473
474	Check file: !`test -f $1 && echo "EXISTS" \|\| echo "MISSING"`
475
476	Process configuration if file exists: @$1
477
478	If file doesn't exist, explain:
479	- Expected location
480	- Required format
481	- How to create it
482	```
483
484	### Required Arguments
485
486	Validate required arguments provided:
487
488	```markdown
489	---
490	description: Create deployment with version
491	argument-hint: [environment] [version]
492	---
493
494	Validate inputs: !`test -n "$1" -a -n "$2" && echo "OK" \|\| echo "MISSING"`
495
496	$IF($1 AND $2,
497	Deploy version $2 to $1 environment,
498	ERROR: Both environment and version required. Usage: /deploy [env] [version]
499	)
500	```
501
502	### Plugin Resource Validation
503
504	Verify plugin resources available:
505
506	```markdown
507	---
508	description: Run analysis with plugin tools
509	allowed-tools: Bash(test:*)
510	---
511
512	Validate plugin setup:
513	- Config exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" \|\| echo "✗"`
514	- Scripts exist: !`test -d ${CLAUDE_PLUGIN_ROOT}/scripts && echo "✓" \|\| echo "✗"`
515	- Tools available: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" \|\| echo "✗"`
516
517	If all checks pass, proceed with analysis.
518	Otherwise, report missing components and installation steps.
519	```
520
521	### Output Validation
522
523	Validate command execution results:
524
525	```markdown
526	---
527	description: Build and validate output
528	allowed-tools: Bash(*)
529	---
530
531	Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
532
533	Validate output:
534	- Exit code: !`echo $?`
535	- Output exists: !`test -d dist && echo "✓" \|\| echo "✗"`
536	- File count: !`find dist -type f \| wc -l`
537
538	Report build status and any validation failures.
539	```
540
541	### Graceful Error Handling
542
543	Handle errors gracefully with helpful messages:
544
545	```markdown
546	---
547	description: Process file with error handling
548	argument-hint: [file-path]
549	---
550
551	Try processing: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/process.js $1 2>&1 \|\| echo "ERROR: $?"`
552
553	If processing succeeded:
554	- Report results
555	- Suggest next steps
556
557	If processing failed:
558	- Explain likely causes
559	- Provide troubleshooting steps
560	- Suggest alternative approaches
561	```
562
563	## Best Practices Summary
564
565	### Plugin Commands Should:
566
567	1. Use ${CLAUDE_PLUGIN_ROOT} for all plugin-internal paths
568	- Scripts, templates, configuration, resources
569
570	2. Validate inputs early
571	- Check required arguments
572	- Verify file existence
573	- Validate argument formats
574
575	3. Document plugin structure
576	- Explain required files
577	- Document script purposes
578	- Clarify dependencies
579
580	4. Integrate with plugin components
581	- Reference agents for complex tasks
582	- Use skills for specialized knowledge
583	- Coordinate with hooks when relevant
584
585	5. Provide helpful error messages
586	- Explain what went wrong
587	- Suggest how to fix
588	- Offer alternatives
589
590	6. Handle edge cases
591	- Missing files
592	- Invalid arguments
593	- Failed script execution
594	- Missing dependencies
595
596	7. Keep commands focused
597	- One clear purpose per command
598	- Delegate complex logic to scripts
599	- Use agents for multi-step workflows
600
601	8. Test across installations
602	- Verify paths work everywhere
603	- Test with different arguments
604	- Validate error cases
605
606	---
607
608	For general command development, see main SKILL.md.
609	For command examples, see examples/ directory.