claude-code / plugins /plugin-dev /skills /command-development /references /plugin-features-reference.md
| # Plugin-Specific Command Features Reference | |
| This reference covers features and patterns specific to commands bundled in Claude Code plugins. | |
| ## Table of Contents | |
| - [Plugin Command Discovery](#plugin-command-discovery) | |
| - [CLAUDE_PLUGIN_ROOT Environment Variable](#claude_plugin_root-environment-variable) | |
| - [Plugin Command Patterns](#plugin-command-patterns) | |
| - [Integration with Plugin Components](#integration-with-plugin-components) | |
| - [Validation Patterns](#validation-patterns) | |
| ## Plugin Command Discovery | |
| ### Auto-Discovery | |
| Claude Code automatically discovers commands in plugins using the following locations: | |
| ``` | |
| plugin-name/ | |
| ├── commands/ # Auto-discovered commands | |
| │ ├── foo.md # /foo (plugin:plugin-name) | |
| │ └── bar.md # /bar (plugin:plugin-name) | |
| └── plugin.json # Plugin manifest | |
| ``` | |
| **Key points:** | |
| - Commands are discovered at plugin load time | |
| - No manual registration required | |
| - Commands appear in `/help` with "(plugin:plugin-name)" label | |
| - Subdirectories create namespaces | |
| ### Namespaced Plugin Commands | |
| Organize commands in subdirectories for logical grouping: | |
| ``` | |
| plugin-name/ | |
| └── commands/ | |
| ├── review/ | |
| │ ├── security.md # /security (plugin:plugin-name:review) | |
| │ └── style.md # /style (plugin:plugin-name:review) | |
| └── deploy/ | |
| ├── staging.md # /staging (plugin:plugin-name:deploy) | |
| └── prod.md # /prod (plugin:plugin-name:deploy) | |
| ``` | |
| **Namespace behavior:** | |
| - Subdirectory name becomes namespace | |
| - Shown as "(plugin:plugin-name:namespace)" in `/help` | |
| - Helps organize related commands | |
| - Use when plugin has 5+ commands | |
| ### Command Naming Conventions | |
| **Plugin command names should:** | |
| 1. Be descriptive and action-oriented | |
| 2. Avoid conflicts with common command names | |
| 3. Use hyphens for multi-word names | |
| 4. Consider prefixing with plugin name for uniqueness | |
| **Examples:** | |
| ``` | |
| Good: | |
| - /mylyn-sync (plugin-specific prefix) | |
| - /analyze-performance (descriptive action) | |
| - /docker-compose-up (clear purpose) | |
| Avoid: | |
| - /test (conflicts with common name) | |
| - /run (too generic) | |
| - /do-stuff (not descriptive) | |
| ``` | |
| ## CLAUDE_PLUGIN_ROOT Environment Variable | |
| ### Purpose | |
| `${CLAUDE_PLUGIN_ROOT}` is a special environment variable available in plugin commands that resolves to the absolute path of the plugin directory. | |
| **Why it matters:** | |
| - Enables portable paths within plugin | |
| - Allows referencing plugin files and scripts | |
| - Works across different installations | |
| - Essential for multi-file plugin operations | |
| ### Basic Usage | |
| Reference files within your plugin: | |
| ```markdown | |
| --- | |
| description: Analyze using plugin script | |
| allowed-tools: Bash(node:*), Read | |
| --- | |
| Run analysis: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js` | |
| Read template: @${CLAUDE_PLUGIN_ROOT}/templates/report.md | |
| ``` | |
| **Expands to:** | |
| ``` | |
| Run analysis: !`node /path/to/plugins/plugin-name/scripts/analyze.js` | |
| Read template: @/path/to/plugins/plugin-name/templates/report.md | |
| ``` | |
| ### Common Patterns | |
| #### 1. Executing Plugin Scripts | |
| ```markdown | |
| --- | |
| description: Run custom linter from plugin | |
| allowed-tools: Bash(node:*) | |
| --- | |
| Lint results: !`node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1` | |
| Review the linting output and suggest fixes. | |
| ``` | |
| #### 2. Loading Configuration Files | |
| ```markdown | |
| --- | |
| description: Deploy using plugin configuration | |
| allowed-tools: Read, Bash(*) | |
| --- | |
| Configuration: @${CLAUDE_PLUGIN_ROOT}/config/deploy-config.json | |
| Deploy application using the configuration above for $1 environment. | |
| ``` | |
| #### 3. Accessing Plugin Resources | |
| ```markdown | |
| --- | |
| description: Generate report from template | |
| --- | |
| Use this template: @${CLAUDE_PLUGIN_ROOT}/templates/api-report.md | |
| Generate a report for @$1 following the template format. | |
| ``` | |
| #### 4. Multi-Step Plugin Workflows | |
| ```markdown | |
| --- | |
| description: Complete plugin workflow | |
| allowed-tools: Bash(*), Read | |
| --- | |
| Step 1 - Prepare: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/prepare.sh $1` | |
| Step 2 - Config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json | |
| Step 3 - Execute: !`${CLAUDE_PLUGIN_ROOT}/bin/execute $1` | |
| Review results and report status. | |
| ``` | |
| ### Best Practices | |
| 1. **Always use for plugin-internal paths:** | |
| ```markdown | |
| # Good | |
| @${CLAUDE_PLUGIN_ROOT}/templates/foo.md | |
| # Bad | |
| @./templates/foo.md # Relative to current directory, not plugin | |
| ``` | |
| 2. **Validate file existence:** | |
| ```markdown | |
| --- | |
| description: Use plugin config if exists | |
| allowed-tools: Bash(test:*), Read | |
| --- | |
| !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "exists" || echo "missing"` | |
| If config exists, load it: @${CLAUDE_PLUGIN_ROOT}/config.json | |
| Otherwise, use defaults... | |
| ``` | |
| 3. **Document plugin file structure:** | |
| ```markdown | |
| <!-- | |
| Plugin structure: | |
| ${CLAUDE_PLUGIN_ROOT}/ | |
| ├── scripts/analyze.js (analysis script) | |
| ├── templates/ (report templates) | |
| └── config/ (configuration files) | |
| --> | |
| ``` | |
| 4. **Combine with arguments:** | |
| ```markdown | |
| Run: !`${CLAUDE_PLUGIN_ROOT}/bin/process.sh $1 $2` | |
| ``` | |
| ### Troubleshooting | |
| **Variable not expanding:** | |
| - Ensure command is loaded from plugin | |
| - Check bash execution is allowed | |
| - Verify syntax is exact: `${CLAUDE_PLUGIN_ROOT}` | |
| **File not found errors:** | |
| - Verify file exists in plugin directory | |
| - Check file path is correct relative to plugin root | |
| - Ensure file permissions allow reading/execution | |
| **Path with spaces:** | |
| - Bash commands automatically handle spaces | |
| - File references work with spaces in paths | |
| - No special quoting needed | |
| ## Plugin Command Patterns | |
| ### Pattern 1: Configuration-Based Commands | |
| Commands that load plugin-specific configuration: | |
| ```markdown | |
| --- | |
| description: Deploy using plugin settings | |
| allowed-tools: Read, Bash(*) | |
| --- | |
| Load configuration: @${CLAUDE_PLUGIN_ROOT}/deploy-config.json | |
| Deploy to $1 environment using: | |
| 1. Configuration settings above | |
| 2. Current git branch: !`git branch --show-current` | |
| 3. Application version: !`cat package.json | grep version` | |
| Execute deployment and monitor progress. | |
| ``` | |
| **When to use:** Commands that need consistent settings across invocations | |
| ### Pattern 2: Template-Based Generation | |
| Commands that use plugin templates: | |
| ```markdown | |
| --- | |
| description: Generate documentation from template | |
| argument-hint: [component-name] | |
| --- | |
| Template: @${CLAUDE_PLUGIN_ROOT}/templates/component-docs.md | |
| Generate documentation for $1 component following the template structure. | |
| Include: | |
| - Component purpose and usage | |
| - API reference | |
| - Examples | |
| - Testing guidelines | |
| ``` | |
| **When to use:** Standardized output generation | |
| ### Pattern 3: Multi-Script Workflow | |
| Commands that orchestrate multiple plugin scripts: | |
| ```markdown | |
| --- | |
| description: Complete build and test workflow | |
| allowed-tools: Bash(*) | |
| --- | |
| Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh` | |
| Validate: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh` | |
| Test: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh` | |
| Review all outputs and report: | |
| 1. Build status | |
| 2. Validation results | |
| 3. Test results | |
| 4. Recommended next steps | |
| ``` | |
| **When to use:** Complex plugin workflows with multiple steps | |
| ### Pattern 4: Environment-Aware Commands | |
| Commands that adapt to environment: | |
| ```markdown | |
| --- | |
| description: Deploy based on environment | |
| argument-hint: [dev|staging|prod] | |
| --- | |
| Environment config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json | |
| Environment check: !`echo "Deploying to: $1"` | |
| Deploy application using $1 environment configuration. | |
| Verify deployment and run smoke tests. | |
| ``` | |
| **When to use:** Commands that behave differently per environment | |
| ### Pattern 5: Plugin Data Management | |
| Commands that manage plugin-specific data: | |
| ```markdown | |
| --- | |
| description: Save analysis results to plugin cache | |
| allowed-tools: Bash(*), Read, Write | |
| --- | |
| Cache directory: ${CLAUDE_PLUGIN_ROOT}/cache/ | |
| Analyze @$1 and save results to cache: | |
| !`mkdir -p ${CLAUDE_PLUGIN_ROOT}/cache && date > ${CLAUDE_PLUGIN_ROOT}/cache/last-run.txt` | |
| Store analysis for future reference and comparison. | |
| ``` | |
| **When to use:** Commands that need persistent data storage | |
| ## Integration with Plugin Components | |
| ### Invoking Plugin Agents | |
| Commands can trigger plugin agents using the Task tool: | |
| ```markdown | |
| --- | |
| description: Deep analysis using plugin agent | |
| argument-hint: [file-path] | |
| --- | |
| Initiate deep code analysis of @$1 using the code-analyzer agent. | |
| The agent will: | |
| 1. Analyze code structure | |
| 2. Identify patterns | |
| 3. Suggest improvements | |
| 4. Generate detailed report | |
| Note: This uses the Task tool to launch the plugin's code-analyzer agent. | |
| ``` | |
| **Key points:** | |
| - Agent must be defined in plugin's `agents/` directory | |
| - Claude will automatically use Task tool to launch agent | |
| - Agent has access to same plugin resources | |
| ### Invoking Plugin Skills | |
| Commands can reference plugin skills for specialized knowledge: | |
| ```markdown | |
| --- | |
| description: API documentation with best practices | |
| argument-hint: [api-file] | |
| --- | |
| Document the API in @$1 following our API documentation standards. | |
| Use the api-docs-standards skill to ensure documentation includes: | |
| - Endpoint descriptions | |
| - Parameter specifications | |
| - Response formats | |
| - Error codes | |
| - Usage examples | |
| Note: This leverages the plugin's api-docs-standards skill for consistency. | |
| ``` | |
| **Key points:** | |
| - Skill must be defined in plugin's `skills/` directory | |
| - Mention skill by name to hint Claude should invoke it | |
| - Skills provide specialized domain knowledge | |
| ### Coordinating with Plugin Hooks | |
| Commands can be designed to work with plugin hooks: | |
| ```markdown | |
| --- | |
| description: Commit with pre-commit validation | |
| allowed-tools: Bash(git:*) | |
| --- | |
| Stage changes: !\`git add $1\` | |
| Commit changes: !\`git commit -m "$2"\` | |
| Note: This commit will trigger the plugin's pre-commit hook for validation. | |
| Review hook output for any issues. | |
| ``` | |
| **Key points:** | |
| - Hooks execute automatically on events | |
| - Commands can prepare state for hooks | |
| - Document hook interaction in command | |
| ### Multi-Component Plugin Commands | |
| Commands that coordinate multiple plugin components: | |
| ```markdown | |
| --- | |
| description: Comprehensive code review workflow | |
| argument-hint: [file-path] | |
| --- | |
| File to review: @$1 | |
| Execute comprehensive review: | |
| 1. **Static Analysis** (via plugin scripts) | |
| !`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1` | |
| 2. **Deep Review** (via plugin agent) | |
| Launch the code-reviewer agent for detailed analysis. | |
| 3. **Best Practices** (via plugin skill) | |
| Use the code-standards skill to ensure compliance. | |
| 4. **Documentation** (via plugin template) | |
| Template: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md | |
| Generate final report combining all outputs. | |
| ``` | |
| **When to use:** Complex workflows leveraging multiple plugin capabilities | |
| ## Validation Patterns | |
| ### Input Validation | |
| Commands should validate inputs before processing: | |
| ```markdown | |
| --- | |
| description: Deploy to environment with validation | |
| argument-hint: [environment] | |
| --- | |
| Validate environment: !`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"` | |
| $IF($1 in [dev, staging, prod], | |
| Deploy to $1 environment using validated configuration, | |
| ERROR: Invalid environment '$1'. Must be one of: dev, staging, prod | |
| ) | |
| ``` | |
| **Validation approaches:** | |
| 1. Bash validation using grep/test | |
| 2. Inline validation in prompt | |
| 3. Script-based validation | |
| ### File Existence Checks | |
| Verify required files exist: | |
| ```markdown | |
| --- | |
| description: Process configuration file | |
| argument-hint: [config-file] | |
| --- | |
| Check file: !`test -f $1 && echo "EXISTS" || echo "MISSING"` | |
| Process configuration if file exists: @$1 | |
| If file doesn't exist, explain: | |
| - Expected location | |
| - Required format | |
| - How to create it | |
| ``` | |
| ### Required Arguments | |
| Validate required arguments provided: | |
| ```markdown | |
| --- | |
| description: Create deployment with version | |
| argument-hint: [environment] [version] | |
| --- | |
| Validate inputs: !`test -n "$1" -a -n "$2" && echo "OK" || echo "MISSING"` | |
| $IF($1 AND $2, | |
| Deploy version $2 to $1 environment, | |
| ERROR: Both environment and version required. Usage: /deploy [env] [version] | |
| ) | |
| ``` | |
| ### Plugin Resource Validation | |
| Verify plugin resources available: | |
| ```markdown | |
| --- | |
| description: Run analysis with plugin tools | |
| allowed-tools: Bash(test:*) | |
| --- | |
| Validate plugin setup: | |
| - Config exists: !`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"` | |
| - Scripts exist: !`test -d ${CLAUDE_PLUGIN_ROOT}/scripts && echo "✓" || echo "✗"` | |
| - Tools available: !`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"` | |
| If all checks pass, proceed with analysis. | |
| Otherwise, report missing components and installation steps. | |
| ``` | |
| ### Output Validation | |
| Validate command execution results: | |
| ```markdown | |
| --- | |
| description: Build and validate output | |
| allowed-tools: Bash(*) | |
| --- | |
| Build: !`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh` | |
| Validate output: | |
| - Exit code: !`echo $?` | |
| - Output exists: !`test -d dist && echo "✓" || echo "✗"` | |
| - File count: !`find dist -type f | wc -l` | |
| Report build status and any validation failures. | |
| ``` | |
| ### Graceful Error Handling | |
| Handle errors gracefully with helpful messages: | |
| ```markdown | |
| --- | |
| description: Process file with error handling | |
| argument-hint: [file-path] | |
| --- | |
| Try processing: !`node ${CLAUDE_PLUGIN_ROOT}/scripts/process.js $1 2>&1 || echo "ERROR: $?"` | |
| If processing succeeded: | |
| - Report results | |
| - Suggest next steps | |
| If processing failed: | |
| - Explain likely causes | |
| - Provide troubleshooting steps | |
| - Suggest alternative approaches | |
| ``` | |
| ## Best Practices Summary | |
| ### Plugin Commands Should: | |
| 1. **Use ${CLAUDE_PLUGIN_ROOT} for all plugin-internal paths** | |
| - Scripts, templates, configuration, resources | |
| 2. **Validate inputs early** | |
| - Check required arguments | |
| - Verify file existence | |
| - Validate argument formats | |
| 3. **Document plugin structure** | |
| - Explain required files | |
| - Document script purposes | |
| - Clarify dependencies | |
| 4. **Integrate with plugin components** | |
| - Reference agents for complex tasks | |
| - Use skills for specialized knowledge | |
| - Coordinate with hooks when relevant | |
| 5. **Provide helpful error messages** | |
| - Explain what went wrong | |
| - Suggest how to fix | |
| - Offer alternatives | |
| 6. **Handle edge cases** | |
| - Missing files | |
| - Invalid arguments | |
| - Failed script execution | |
| - Missing dependencies | |
| 7. **Keep commands focused** | |
| - One clear purpose per command | |
| - Delegate complex logic to scripts | |
| - Use agents for multi-step workflows | |
| 8. **Test across installations** | |
| - Verify paths work everywhere | |
| - Test with different arguments | |
| - Validate error cases | |
| --- | |
| For general command development, see main SKILL.md. | |
| For command examples, see examples/ directory. | |