1# Plugin-Specific Command Features Reference
2 
3This 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 
17Claude Code automatically discovers commands in plugins using the following locations:
18 
19```
20plugin-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 
35Organize commands in subdirectories for logical grouping:
36 
37```
38plugin-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:**
571. Be descriptive and action-oriented
582. Avoid conflicts with common command names
593. Use hyphens for multi-word names
604. Consider prefixing with plugin name for uniqueness
61 
62**Examples:**
63```
64Good:
65- /mylyn-sync          (plugin-specific prefix)
66- /analyze-performance (descriptive action)
67- /docker-compose-up   (clear purpose)
68 
69Avoid:
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 
89Reference files within your plugin:
90 
91```markdown
92---
93description: Analyze using plugin script
94allowed-tools: Bash(node:*), Read
95---
96 
97Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`
98 
99Read template: @${CLAUDE_PLUGIN_ROOT}/templates/report.md
100```
101 
102**Expands to:**
103```
104Run analysis: !`node /path/to/plugins/plugin-name/scripts/analyze.js`
105 
106Read template: @/path/to/plugins/plugin-name/templates/report.md
107```
108 
109### Common Patterns
110 
111#### 1. Executing Plugin Scripts
112 
113```markdown
114---
115description: Run custom linter from plugin
116allowed-tools: Bash(node:*)
117---
118 
119Lint results: !`node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1`
120 
121Review the linting output and suggest fixes.
122```
123 
124#### 2. Loading Configuration Files
125 
126```markdown
127---
128description: Deploy using plugin configuration
129allowed-tools: Read, Bash(*)
130---
131 
132Configuration: @${CLAUDE_PLUGIN_ROOT}/config/deploy-config.json
133 
134Deploy application using the configuration above for $1 environment.
135```
136 
137#### 3. Accessing Plugin Resources
138 
139```markdown
140---
141description: Generate report from template
142---
143 
144Use this template: @${CLAUDE_PLUGIN_ROOT}/templates/api-report.md
145 
146Generate a report for @$1 following the template format.
147```
148 
149#### 4. Multi-Step Plugin Workflows
150 
151```markdown
152---
153description: Complete plugin workflow
154allowed-tools: Bash(*), Read
155---
156 
157Step 1 - Prepare: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/prepare.sh $1`
158Step 2 - Config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json
159Step 3 - Execute: !`${CLAUDE_PLUGIN_ROOT}/bin/execute $1`
160 
161Review results and report status.
162```
163 
164### Best Practices
165 
1661. **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 
1752. **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 
1883. **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 
1994. **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 
225Commands that load plugin-specific configuration:
226 
227```markdown
228---
229description: Deploy using plugin settings
230allowed-tools: Read, Bash(*)
231---
232 
233Load configuration: @${CLAUDE_PLUGIN_ROOT}/deploy-config.json
234 
235Deploy to $1 environment using:
2361. Configuration settings above
2372. Current git branch: !`git branch --show-current`
2383. Application version: !`cat package.json | grep version`
239 
240Execute 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 
247Commands that use plugin templates:
248 
249```markdown
250---
251description: Generate documentation from template
252argument-hint: [component-name]
253---
254 
255Template: @${CLAUDE_PLUGIN_ROOT}/templates/component-docs.md
256 
257Generate documentation for $1 component following the template structure.
258Include:
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 
269Commands that orchestrate multiple plugin scripts:
270 
271```markdown
272---
273description: Complete build and test workflow
274allowed-tools: Bash(*)
275---
276 
277Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
278Validate: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh`
279Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
280 
281Review all outputs and report:
2821. Build status
2832. Validation results
2843. Test results
2854. Recommended next steps
286```
287 
288**When to use:** Complex plugin workflows with multiple steps
289 
290### Pattern 4: Environment-Aware Commands
291 
292Commands that adapt to environment:
293 
294```markdown
295---
296description: Deploy based on environment
297argument-hint: [dev|staging|prod]
298---
299 
300Environment config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json
301 
302Environment check: !`echo "Deploying to: $1"`
303 
304Deploy application using $1 environment configuration.
305Verify 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 
312Commands that manage plugin-specific data:
313 
314```markdown
315---
316description: Save analysis results to plugin cache
317allowed-tools: Bash(*), Read, Write
318---
319 
320Cache directory: ${CLAUDE_PLUGIN_ROOT}/cache/
321 
322Analyze @$1 and save results to cache:
323!`mkdir -p ${CLAUDE_PLUGIN_ROOT}/cache && date > ${CLAUDE_PLUGIN_ROOT}/cache/last-run.txt`
324 
325Store 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 
334Commands can trigger plugin agents using the Task tool:
335 
336```markdown
337---
338description: Deep analysis using plugin agent
339argument-hint: [file-path]
340---
341 
342Initiate deep code analysis of @$1 using the code-analyzer agent.
343 
344The agent will:
3451. Analyze code structure
3462. Identify patterns
3473. Suggest improvements
3484. Generate detailed report
349 
350Note: 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 
360Commands can reference plugin skills for specialized knowledge:
361 
362```markdown
363---
364description: API documentation with best practices
365argument-hint: [api-file]
366---
367 
368Document the API in @$1 following our API documentation standards.
369 
370Use 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 
377Note: 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 
387Commands can be designed to work with plugin hooks:
388 
389```markdown
390---
391description: Commit with pre-commit validation
392allowed-tools: Bash(git:*)
393---
394 
395Stage changes: !\`git add $1\`
396 
397Commit changes: !\`git commit -m "$2"\`
398 
399Note: This commit will trigger the plugin's pre-commit hook for validation.
400Review 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 
410Commands that coordinate multiple plugin components:
411 
412```markdown
413---
414description: Comprehensive code review workflow
415argument-hint: [file-path]
416---
417 
418File to review: @$1
419 
420Execute comprehensive review:
421 
4221. **Static Analysis** (via plugin scripts)
423   !`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`
424 
4252. **Deep Review** (via plugin agent)
426   Launch the code-reviewer agent for detailed analysis.
427 
4283. **Best Practices** (via plugin skill)
429   Use the code-standards skill to ensure compliance.
430 
4314. **Documentation** (via plugin template)
432   Template: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md
433 
434Generate 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 
443Commands should validate inputs before processing:
444 
445```markdown
446---
447description: Deploy to environment with validation
448argument-hint: [environment]
449---
450 
451Validate 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:**
4601. Bash validation using grep/test
4612. Inline validation in prompt
4623. Script-based validation
463 
464### File Existence Checks
465 
466Verify required files exist:
467 
468```markdown
469---
470description: Process configuration file
471argument-hint: [config-file]
472---
473 
474Check file: !`test -f $1 && echo "EXISTS" || echo "MISSING"`
475 
476Process configuration if file exists: @$1
477 
478If file doesn't exist, explain:
479- Expected location
480- Required format
481- How to create it
482```
483 
484### Required Arguments
485 
486Validate required arguments provided:
487 
488```markdown
489---
490description: Create deployment with version
491argument-hint: [environment] [version]
492---
493 
494Validate 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 
504Verify plugin resources available:
505 
506```markdown
507---
508description: Run analysis with plugin tools
509allowed-tools: Bash(test:*)
510---
511 
512Validate 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 
517If all checks pass, proceed with analysis.
518Otherwise, report missing components and installation steps.
519```
520 
521### Output Validation
522 
523Validate command execution results:
524 
525```markdown
526---
527description: Build and validate output
528allowed-tools: Bash(*)
529---
530 
531Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
532 
533Validate output:
534- Exit code: !`echo $?`
535- Output exists: !`test -d dist && echo "✓" || echo "✗"`
536- File count: !`find dist -type f | wc -l`
537 
538Report build status and any validation failures.
539```
540 
541### Graceful Error Handling
542 
543Handle errors gracefully with helpful messages:
544 
545```markdown
546---
547description: Process file with error handling
548argument-hint: [file-path]
549---
550 
551Try processing: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/process.js $1 2>&1 || echo "ERROR: $?"`
552 
553If processing succeeded:
554- Report results
555- Suggest next steps
556 
557If 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 
5671. **Use ${CLAUDE_PLUGIN_ROOT} for all plugin-internal paths**
568   - Scripts, templates, configuration, resources
569 
5702. **Validate inputs early**
571   - Check required arguments
572   - Verify file existence
573   - Validate argument formats
574 
5753. **Document plugin structure**
576   - Explain required files
577   - Document script purposes
578   - Clarify dependencies
579 
5804. **Integrate with plugin components**
581   - Reference agents for complex tasks
582   - Use skills for specialized knowledge
583   - Coordinate with hooks when relevant
584 
5855. **Provide helpful error messages**
586   - Explain what went wrong
587   - Suggest how to fix
588   - Offer alternatives
589 
5906. **Handle edge cases**
591   - Missing files
592   - Invalid arguments
593   - Failed script execution
594   - Missing dependencies
595 
5967. **Keep commands focused**
597   - One clear purpose per command
598   - Delegate complex logic to scripts
599   - Use agents for multi-step workflows
600 
6018. **Test across installations**
602   - Verify paths work everywhere
603   - Test with different arguments
604   - Validate error cases
605 
606---
607 
608For general command development, see main SKILL.md.
609For command examples, see examples/ directory.
610