Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,609 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user