Initial commit
This commit is contained in:
Zhongwei Li
722
skills/command-development/references/advanced-workflows.md
Normal file
722
skills/command-development/references/advanced-workflows.md
Normal file
@@ -0,0 +1,722 @@
|
||||
# Advanced Workflow Patterns
|
||||
|
||||
Multi-step command sequences and composition patterns for complex workflows.
|
||||
|
||||
## Overview
|
||||
|
||||
Advanced workflows combine multiple commands, coordinate state across invocations, and create sophisticated automation sequences. These patterns enable building complex functionality from simple command building blocks.
|
||||
|
||||
## Multi-Step Command Patterns
|
||||
|
||||
### Sequential Workflow Command
|
||||
|
||||
Commands that guide users through multi-step processes:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Complete PR review workflow
|
||||
argument-hint: [pr-number]
|
||||
allowed-tools: Bash(gh:*), Read, Grep
|
||||
---
|
||||
|
||||
# PR Review Workflow for #$1
|
||||
|
||||
## Step 1: Fetch PR Details
|
||||
!`gh pr view $1 --json title,body,author,files`
|
||||
|
||||
## Step 2: Review Files
|
||||
Files changed: !`gh pr diff $1 --name-only`
|
||||
|
||||
For each file:
|
||||
- Check code quality
|
||||
- Verify tests exist
|
||||
- Review documentation
|
||||
|
||||
## Step 3: Run Checks
|
||||
Test status: !`gh pr checks $1`
|
||||
|
||||
Verify:
|
||||
- All tests passing
|
||||
- No merge conflicts
|
||||
- CI/CD successful
|
||||
|
||||
## Step 4: Provide Feedback
|
||||
|
||||
Summarize:
|
||||
- Issues found (critical/minor)
|
||||
- Suggestions for improvement
|
||||
- Approval recommendation
|
||||
|
||||
Would you like to:
|
||||
1. Approve PR
|
||||
2. Request changes
|
||||
3. Leave comments only
|
||||
|
||||
Reply with your choice and I'll help complete the action.
|
||||
```
|
||||
|
||||
**Key features:**
|
||||
- Numbered steps for clarity
|
||||
- Bash execution for context
|
||||
- Decision points for user input
|
||||
- Next action suggestions
|
||||
|
||||
### State-Carrying Workflow
|
||||
|
||||
Commands that maintain state between invocations:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Initialize deployment workflow
|
||||
allowed-tools: Write, Bash(git:*)
|
||||
---
|
||||
|
||||
# Initialize Deployment
|
||||
|
||||
Creating deployment tracking file...
|
||||
|
||||
Current branch: !`git branch --show-current`
|
||||
Latest commit: !`git log -1 --format=%H`
|
||||
|
||||
Deployment state saved to `.claude/deployment-state.local.md`:
|
||||
|
||||
\`\`\`markdown
|
||||
---
|
||||
initialized: true
|
||||
branch: $(git branch --show-current)
|
||||
commit: $(git log -1 --format=%H)
|
||||
timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)
|
||||
status: initialized
|
||||
---
|
||||
|
||||
# Deployment Tracking
|
||||
|
||||
Branch: $(git branch --show-current)
|
||||
Started: $(date)
|
||||
|
||||
Next steps:
|
||||
1. Run tests: /deploy-test
|
||||
2. Build: /deploy-build
|
||||
3. Deploy: /deploy-execute
|
||||
\`\`\`
|
||||
|
||||
State saved. Run `/deploy-test` to continue.
|
||||
```
|
||||
|
||||
**Next command** (`/deploy-test`):
|
||||
```markdown
|
||||
---
|
||||
description: Run deployment tests
|
||||
allowed-tools: Read, Bash(npm:*)
|
||||
---
|
||||
|
||||
Reading deployment state from `.claude/deployment-state.local.md`...
|
||||
|
||||
Running tests: !`npm test`
|
||||
|
||||
Updating state to 'tested'...
|
||||
|
||||
Tests complete. Run `/deploy-build` to continue.
|
||||
```
|
||||
|
||||
**Pattern benefits:**
|
||||
- Persistent state across commands
|
||||
- Clear workflow progression
|
||||
- Safety checkpoints
|
||||
- Resume capability
|
||||
|
||||
### Conditional Workflow Branching
|
||||
|
||||
Commands that adapt based on conditions:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Smart deployment workflow
|
||||
argument-hint: [environment]
|
||||
allowed-tools: Bash(git:*), Bash(npm:*), Read
|
||||
---
|
||||
|
||||
# Deploy to $1
|
||||
|
||||
## Pre-flight Checks
|
||||
|
||||
Branch: !`git branch --show-current`
|
||||
Status: !`git status --short`
|
||||
|
||||
**Checking conditions:**
|
||||
|
||||
1. Branch status:
|
||||
- If main/master: Require approval
|
||||
- If feature branch: Warning about target
|
||||
- If hotfix: Fast-track process
|
||||
|
||||
2. Tests:
|
||||
!`npm test`
|
||||
- If tests fail: STOP - fix tests first
|
||||
- If tests pass: Continue
|
||||
|
||||
3. Environment:
|
||||
- If $1 = 'production': Extra validation
|
||||
- If $1 = 'staging': Standard process
|
||||
- If $1 = 'dev': Minimal checks
|
||||
|
||||
**Workflow decision:**
|
||||
Based on above, proceeding with: [determined workflow]
|
||||
|
||||
[Conditional steps based on environment and status]
|
||||
|
||||
Ready to deploy? (yes/no)
|
||||
```
|
||||
|
||||
## Command Composition Patterns
|
||||
|
||||
### Command Chaining
|
||||
|
||||
Commands designed to work together:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Prepare for code review
|
||||
---
|
||||
|
||||
# Prepare Code Review
|
||||
|
||||
Running preparation sequence:
|
||||
|
||||
1. Format code: /format-code
|
||||
2. Run linter: /lint-code
|
||||
3. Run tests: /test-all
|
||||
4. Generate coverage: /coverage-report
|
||||
5. Create review summary: /review-summary
|
||||
|
||||
This is a meta-command. After completing each step above,
|
||||
I'll compile results and prepare comprehensive review materials.
|
||||
|
||||
Starting sequence...
|
||||
```
|
||||
|
||||
**Individual commands** are simple:
|
||||
- `/format-code` - Just formats
|
||||
- `/lint-code` - Just lints
|
||||
- `/test-all` - Just tests
|
||||
|
||||
**Composition command** orchestrates them.
|
||||
|
||||
### Pipeline Pattern
|
||||
|
||||
Commands that process output from previous commands:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Analyze test failures
|
||||
---
|
||||
|
||||
# Analyze Test Failures
|
||||
|
||||
## Step 1: Get test results
|
||||
(Run /test-all first if not done)
|
||||
|
||||
Reading test output...
|
||||
|
||||
## Step 2: Categorize failures
|
||||
- Flaky tests (random failures)
|
||||
- Consistent failures
|
||||
- New failures vs existing
|
||||
|
||||
## Step 3: Prioritize
|
||||
Rank by:
|
||||
- Impact (critical path vs edge case)
|
||||
- Frequency (always fails vs sometimes)
|
||||
- Effort (quick fix vs major work)
|
||||
|
||||
## Step 4: Generate fix plan
|
||||
For each failure:
|
||||
- Root cause hypothesis
|
||||
- Suggested fix approach
|
||||
- Estimated effort
|
||||
|
||||
Would you like me to:
|
||||
1. Fix highest priority failure
|
||||
2. Generate detailed fix plans for all
|
||||
3. Create GitHub issues for each
|
||||
```
|
||||
|
||||
### Parallel Execution Pattern
|
||||
|
||||
Commands that coordinate multiple simultaneous operations:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Run comprehensive validation
|
||||
allowed-tools: Bash(*), Read
|
||||
---
|
||||
|
||||
# Comprehensive Validation
|
||||
|
||||
Running validations in parallel...
|
||||
|
||||
Starting:
|
||||
- Code quality checks
|
||||
- Security scanning
|
||||
- Dependency audit
|
||||
- Performance profiling
|
||||
|
||||
This will take 2-3 minutes. I'll monitor all processes
|
||||
and report when complete.
|
||||
|
||||
[Poll each process and report progress]
|
||||
|
||||
All validations complete. Summary:
|
||||
- Quality: PASS (0 issues)
|
||||
- Security: WARN (2 minor issues)
|
||||
- Dependencies: PASS
|
||||
- Performance: PASS (baseline met)
|
||||
|
||||
Details:
|
||||
[Collated results from all checks]
|
||||
```
|
||||
|
||||
## Workflow State Management
|
||||
|
||||
### Using .local.md Files
|
||||
|
||||
Store workflow state in plugin-specific files:
|
||||
|
||||
```markdown
|
||||
.claude/plugin-name-workflow.local.md:
|
||||
|
||||
---
|
||||
workflow: deployment
|
||||
stage: testing
|
||||
started: 2025-01-15T10:30:00Z
|
||||
environment: staging
|
||||
branch: feature/new-api
|
||||
commit: abc123def
|
||||
tests_passed: false
|
||||
build_complete: false
|
||||
---
|
||||
|
||||
# Deployment Workflow State
|
||||
|
||||
Current stage: Testing
|
||||
Started: 2025-01-15 10:30 UTC
|
||||
|
||||
Completed steps:
|
||||
- ✅ Validation
|
||||
- ✅ Branch check
|
||||
- ⏳ Testing (in progress)
|
||||
|
||||
Pending steps:
|
||||
- Build
|
||||
- Deploy
|
||||
- Smoke tests
|
||||
```
|
||||
|
||||
**Reading state in commands:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Continue deployment workflow
|
||||
allowed-tools: Read, Write
|
||||
---
|
||||
|
||||
Reading workflow state from .claude/plugin-name-workflow.local.md...
|
||||
|
||||
Current stage: @.claude/plugin-name-workflow.local.md
|
||||
|
||||
[Parse YAML frontmatter to determine next step]
|
||||
|
||||
Next action based on state: [determined action]
|
||||
```
|
||||
|
||||
### Workflow Recovery
|
||||
|
||||
Handle interrupted workflows:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Resume deployment workflow
|
||||
allowed-tools: Read
|
||||
---
|
||||
|
||||
# Resume Deployment
|
||||
|
||||
Checking for interrupted workflow...
|
||||
|
||||
State file: @.claude/plugin-name-workflow.local.md
|
||||
|
||||
**Workflow found:**
|
||||
- Started: [timestamp]
|
||||
- Environment: [env]
|
||||
- Last completed: [step]
|
||||
|
||||
**Recovery options:**
|
||||
1. Resume from last step
|
||||
2. Restart from beginning
|
||||
3. Abort and clean up
|
||||
|
||||
Which would you like? (1/2/3)
|
||||
```
|
||||
|
||||
## Workflow Coordination Patterns
|
||||
|
||||
### Cross-Command Communication
|
||||
|
||||
Commands that signal each other:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Mark feature complete
|
||||
allowed-tools: Write
|
||||
---
|
||||
|
||||
# Mark Feature Complete
|
||||
|
||||
Writing completion marker...
|
||||
|
||||
Creating: .claude/feature-complete.flag
|
||||
|
||||
This signals other commands that feature is ready for:
|
||||
- Integration testing (/integration-test will auto-detect)
|
||||
- Documentation generation (/docs-generate will include)
|
||||
- Release notes (/release-notes will add)
|
||||
|
||||
Feature marked complete.
|
||||
```
|
||||
|
||||
**Other commands check for flag:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate release notes
|
||||
allowed-tools: Read, Bash(git:*)
|
||||
---
|
||||
|
||||
Checking for completed features...
|
||||
|
||||
if [ -f .claude/feature-complete.flag ]; then
|
||||
Feature ready for release notes
|
||||
fi
|
||||
|
||||
[Include in release notes]
|
||||
```
|
||||
|
||||
### Workflow Locking
|
||||
|
||||
Prevent concurrent workflow execution:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Start deployment
|
||||
allowed-tools: Read, Write, Bash
|
||||
---
|
||||
|
||||
# Start Deployment
|
||||
|
||||
Checking for active deployments...
|
||||
|
||||
if [ -f .claude/deployment.lock ]; then
|
||||
ERROR: Deployment already in progress
|
||||
Started: [timestamp from lock file]
|
||||
|
||||
Cannot start concurrent deployment.
|
||||
Wait for completion or run /deployment-abort
|
||||
|
||||
Exit.
|
||||
fi
|
||||
|
||||
Creating deployment lock...
|
||||
|
||||
Deployment started. Lock created.
|
||||
[Proceed with deployment]
|
||||
```
|
||||
|
||||
**Lock cleanup:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Complete deployment
|
||||
allowed-tools: Write, Bash
|
||||
---
|
||||
|
||||
Deployment complete.
|
||||
|
||||
Removing deployment lock...
|
||||
rm .claude/deployment.lock
|
||||
|
||||
Ready for next deployment.
|
||||
```
|
||||
|
||||
## Advanced Argument Handling
|
||||
|
||||
### Optional Arguments with Defaults
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Deploy with optional version
|
||||
argument-hint: [environment] [version]
|
||||
---
|
||||
|
||||
Environment: ${1:-staging}
|
||||
Version: ${2:-latest}
|
||||
|
||||
Deploying ${2:-latest} to ${1:-staging}...
|
||||
|
||||
Note: Using defaults for missing arguments:
|
||||
- Environment defaults to 'staging'
|
||||
- Version defaults to 'latest'
|
||||
```
|
||||
|
||||
### Argument Validation
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Deploy to validated environment
|
||||
argument-hint: [environment]
|
||||
---
|
||||
|
||||
Environment: $1
|
||||
|
||||
Validating environment...
|
||||
|
||||
valid_envs="dev staging production"
|
||||
if ! echo "$valid_envs" | grep -w "$1" > /dev/null; then
|
||||
ERROR: Invalid environment '$1'
|
||||
Valid options: dev, staging, production
|
||||
Exit.
|
||||
fi
|
||||
|
||||
Environment validated. Proceeding...
|
||||
```
|
||||
|
||||
### Argument Transformation
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Deploy with shorthand
|
||||
argument-hint: [env-shorthand]
|
||||
---
|
||||
|
||||
Input: $1
|
||||
|
||||
Expanding shorthand:
|
||||
- d/dev → development
|
||||
- s/stg → staging
|
||||
- p/prod → production
|
||||
|
||||
case "$1" in
|
||||
d|dev) ENV="development";;
|
||||
s|stg) ENV="staging";;
|
||||
p|prod) ENV="production";;
|
||||
*) ENV="$1";;
|
||||
esac
|
||||
|
||||
Deploying to: $ENV
|
||||
```
|
||||
|
||||
## Error Handling in Workflows
|
||||
|
||||
### Graceful Failure
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Resilient deployment workflow
|
||||
---
|
||||
|
||||
# Deployment Workflow
|
||||
|
||||
Running steps with error handling...
|
||||
|
||||
## Step 1: Tests
|
||||
!`npm test`
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
ERROR: Tests failed
|
||||
|
||||
Options:
|
||||
1. Fix tests and retry
|
||||
2. Skip tests (NOT recommended)
|
||||
3. Abort deployment
|
||||
|
||||
What would you like to do?
|
||||
|
||||
[Wait for user input before continuing]
|
||||
fi
|
||||
|
||||
## Step 2: Build
|
||||
[Continue only if Step 1 succeeded]
|
||||
```
|
||||
|
||||
### Rollback on Failure
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Deployment with rollback
|
||||
---
|
||||
|
||||
# Deploy with Rollback
|
||||
|
||||
Saving current state for rollback...
|
||||
Previous version: !`current-version.sh`
|
||||
|
||||
Deploying new version...
|
||||
|
||||
!`deploy.sh`
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
DEPLOYMENT FAILED
|
||||
|
||||
Initiating automatic rollback...
|
||||
!`rollback.sh`
|
||||
|
||||
Rolled back to previous version.
|
||||
Check logs for failure details.
|
||||
fi
|
||||
|
||||
Deployment complete.
|
||||
```
|
||||
|
||||
### Checkpoint Recovery
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Workflow with checkpoints
|
||||
---
|
||||
|
||||
# Multi-Stage Deployment
|
||||
|
||||
## Checkpoint 1: Validation
|
||||
!`validate.sh`
|
||||
echo "checkpoint:validation" >> .claude/deployment-checkpoints.log
|
||||
|
||||
## Checkpoint 2: Build
|
||||
!`build.sh`
|
||||
echo "checkpoint:build" >> .claude/deployment-checkpoints.log
|
||||
|
||||
## Checkpoint 3: Deploy
|
||||
!`deploy.sh`
|
||||
echo "checkpoint:deploy" >> .claude/deployment-checkpoints.log
|
||||
|
||||
If any step fails, resume with:
|
||||
/deployment-resume [last-successful-checkpoint]
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Workflow Design
|
||||
|
||||
1. **Clear progression**: Number steps, show current position
|
||||
2. **Explicit state**: Don't rely on implicit state
|
||||
3. **User control**: Provide decision points
|
||||
4. **Error recovery**: Handle failures gracefully
|
||||
5. **Progress indication**: Show what's done, what's pending
|
||||
|
||||
### Command Composition
|
||||
|
||||
1. **Single responsibility**: Each command does one thing well
|
||||
2. **Composable design**: Commands work together easily
|
||||
3. **Standard interfaces**: Consistent input/output formats
|
||||
4. **Loose coupling**: Commands don't depend on each other's internals
|
||||
|
||||
### State Management
|
||||
|
||||
1. **Persistent state**: Use .local.md files
|
||||
2. **Atomic updates**: Write complete state files atomically
|
||||
3. **State validation**: Check state file format/completeness
|
||||
4. **Cleanup**: Remove stale state files
|
||||
5. **Documentation**: Document state file formats
|
||||
|
||||
### Error Handling
|
||||
|
||||
1. **Fail fast**: Detect errors early
|
||||
2. **Clear messages**: Explain what went wrong
|
||||
3. **Recovery options**: Provide clear next steps
|
||||
4. **State preservation**: Keep state for recovery
|
||||
5. **Rollback capability**: Support undoing changes
|
||||
|
||||
## Example: Complete Deployment Workflow
|
||||
|
||||
### Initialize Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Initialize deployment
|
||||
argument-hint: [environment]
|
||||
allowed-tools: Write, Bash(git:*)
|
||||
---
|
||||
|
||||
# Initialize Deployment to $1
|
||||
|
||||
Creating workflow state...
|
||||
|
||||
\`\`\`yaml
|
||||
---
|
||||
workflow: deployment
|
||||
environment: $1
|
||||
branch: !`git branch --show-current`
|
||||
commit: !`git rev-parse HEAD`
|
||||
stage: initialized
|
||||
timestamp: !`date -u +%Y-%m-%dT%H:%M:%SZ`
|
||||
---
|
||||
\`\`\`
|
||||
|
||||
Written to .claude/deployment-state.local.md
|
||||
|
||||
Next: Run /deployment-validate
|
||||
```
|
||||
|
||||
### Validation Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Validate deployment
|
||||
allowed-tools: Read, Bash
|
||||
---
|
||||
|
||||
Reading state: @.claude/deployment-state.local.md
|
||||
|
||||
Running validation...
|
||||
- Branch check: PASS
|
||||
- Tests: PASS
|
||||
- Build: PASS
|
||||
|
||||
Updating state to 'validated'...
|
||||
|
||||
Next: Run /deployment-execute
|
||||
```
|
||||
|
||||
### Execution Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Execute deployment
|
||||
allowed-tools: Read, Bash, Write
|
||||
---
|
||||
|
||||
Reading state: @.claude/deployment-state.local.md
|
||||
|
||||
Executing deployment to [environment]...
|
||||
|
||||
!`deploy.sh [environment]`
|
||||
|
||||
Deployment complete.
|
||||
Updating state to 'completed'...
|
||||
|
||||
Cleanup: /deployment-cleanup
|
||||
```
|
||||
|
||||
### Cleanup Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Clean up deployment
|
||||
allowed-tools: Bash
|
||||
---
|
||||
|
||||
Removing deployment state...
|
||||
rm .claude/deployment-state.local.md
|
||||
|
||||
Deployment workflow complete.
|
||||
```
|
||||
|
||||
This complete workflow demonstrates state management, sequential execution, error handling, and clean separation of concerns across multiple commands.
|
||||
739
skills/command-development/references/documentation-patterns.md
Normal file
739
skills/command-development/references/documentation-patterns.md
Normal file
@@ -0,0 +1,739 @@
|
||||
# Command Documentation Patterns
|
||||
|
||||
Strategies for creating self-documenting, maintainable commands with excellent user experience.
|
||||
|
||||
## Overview
|
||||
|
||||
Well-documented commands are easier to use, maintain, and distribute. Documentation should be embedded in the command itself, making it immediately accessible to users and maintainers.
|
||||
|
||||
## Self-Documenting Command Structure
|
||||
|
||||
### Complete Command Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Clear, actionable description under 60 chars
|
||||
argument-hint: [arg1] [arg2] [optional-arg]
|
||||
allowed-tools: Read, Bash(git:*)
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
<!--
|
||||
COMMAND: command-name
|
||||
VERSION: 1.0.0
|
||||
AUTHOR: Team Name
|
||||
LAST UPDATED: 2025-01-15
|
||||
|
||||
PURPOSE:
|
||||
Detailed explanation of what this command does and why it exists.
|
||||
|
||||
USAGE:
|
||||
/command-name arg1 arg2
|
||||
|
||||
ARGUMENTS:
|
||||
arg1: Description of first argument (required)
|
||||
arg2: Description of second argument (optional, defaults to X)
|
||||
|
||||
EXAMPLES:
|
||||
/command-name feature-branch main
|
||||
→ Compares feature-branch with main
|
||||
|
||||
/command-name my-branch
|
||||
→ Compares my-branch with current branch
|
||||
|
||||
REQUIREMENTS:
|
||||
- Git repository
|
||||
- Branch must exist
|
||||
- Permissions to read repository
|
||||
|
||||
RELATED COMMANDS:
|
||||
/other-command - Related functionality
|
||||
/another-command - Alternative approach
|
||||
|
||||
TROUBLESHOOTING:
|
||||
- If branch not found: Check branch name spelling
|
||||
- If permission denied: Check repository access
|
||||
|
||||
CHANGELOG:
|
||||
v1.0.0 (2025-01-15): Initial release
|
||||
v0.9.0 (2025-01-10): Beta version
|
||||
-->
|
||||
|
||||
# Command Implementation
|
||||
|
||||
[Command prompt content here...]
|
||||
|
||||
[Explain what will happen...]
|
||||
|
||||
[Guide user through steps...]
|
||||
|
||||
[Provide clear output...]
|
||||
```
|
||||
|
||||
### Documentation Comment Sections
|
||||
|
||||
**PURPOSE**: Why the command exists
|
||||
- Problem it solves
|
||||
- Use cases
|
||||
- When to use vs when not to use
|
||||
|
||||
**USAGE**: Basic syntax
|
||||
- Command invocation pattern
|
||||
- Required vs optional arguments
|
||||
- Default values
|
||||
|
||||
**ARGUMENTS**: Detailed argument documentation
|
||||
- Each argument described
|
||||
- Type information
|
||||
- Valid values/ranges
|
||||
- Defaults
|
||||
|
||||
**EXAMPLES**: Concrete usage examples
|
||||
- Common use cases
|
||||
- Edge cases
|
||||
- Expected outputs
|
||||
|
||||
**REQUIREMENTS**: Prerequisites
|
||||
- Dependencies
|
||||
- Permissions
|
||||
- Environmental setup
|
||||
|
||||
**RELATED COMMANDS**: Connections
|
||||
- Similar commands
|
||||
- Complementary commands
|
||||
- Alternative approaches
|
||||
|
||||
**TROUBLESHOOTING**: Common issues
|
||||
- Known problems
|
||||
- Solutions
|
||||
- Workarounds
|
||||
|
||||
**CHANGELOG**: Version history
|
||||
- What changed when
|
||||
- Breaking changes highlighted
|
||||
- Migration guidance
|
||||
|
||||
## In-Line Documentation Patterns
|
||||
|
||||
### Commented Sections
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Complex multi-step command
|
||||
---
|
||||
|
||||
<!-- SECTION 1: VALIDATION -->
|
||||
<!-- This section checks prerequisites before proceeding -->
|
||||
|
||||
Checking prerequisites...
|
||||
- Git repository: !`git rev-parse --git-dir 2>/dev/null`
|
||||
- Branch exists: [validation logic]
|
||||
|
||||
<!-- SECTION 2: ANALYSIS -->
|
||||
<!-- Analyzes the differences between branches -->
|
||||
|
||||
Analyzing differences between $1 and $2...
|
||||
[Analysis logic...]
|
||||
|
||||
<!-- SECTION 3: RECOMMENDATIONS -->
|
||||
<!-- Provides actionable recommendations -->
|
||||
|
||||
Based on analysis, recommend:
|
||||
[Recommendations...]
|
||||
|
||||
<!-- END: Next steps for user -->
|
||||
```
|
||||
|
||||
### Inline Explanations
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Deployment command with inline docs
|
||||
---
|
||||
|
||||
# Deploy to $1
|
||||
|
||||
## Pre-flight Checks
|
||||
|
||||
<!-- We check branch status to prevent deploying from wrong branch -->
|
||||
Current branch: !`git branch --show-current`
|
||||
|
||||
<!-- Production deploys must come from main/master -->
|
||||
if [ "$1" = "production" ] && [ "$(git branch --show-current)" != "main" ]; then
|
||||
⚠️ WARNING: Not on main branch for production deploy
|
||||
This is unusual. Confirm this is intentional.
|
||||
fi
|
||||
|
||||
<!-- Test status ensures we don't deploy broken code -->
|
||||
Running tests: !`npm test`
|
||||
|
||||
✓ All checks passed
|
||||
|
||||
## Deployment
|
||||
|
||||
<!-- Actual deployment happens here -->
|
||||
<!-- Uses blue-green strategy for zero-downtime -->
|
||||
Deploying to $1 environment...
|
||||
[Deployment steps...]
|
||||
|
||||
<!-- Post-deployment verification -->
|
||||
Verifying deployment health...
|
||||
[Health checks...]
|
||||
|
||||
Deployment complete!
|
||||
|
||||
## Next Steps
|
||||
|
||||
<!-- Guide user on what to do after deployment -->
|
||||
1. Monitor logs: /logs $1
|
||||
2. Run smoke tests: /smoke-test $1
|
||||
3. Notify team: /notify-deployment $1
|
||||
```
|
||||
|
||||
### Decision Point Documentation
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Interactive deployment command
|
||||
---
|
||||
|
||||
# Interactive Deployment
|
||||
|
||||
## Configuration Review
|
||||
|
||||
Target: $1
|
||||
Current version: !`cat version.txt`
|
||||
New version: $2
|
||||
|
||||
<!-- DECISION POINT: User confirms configuration -->
|
||||
<!-- This pause allows user to verify everything is correct -->
|
||||
<!-- We can't automatically proceed because deployment is risky -->
|
||||
|
||||
Review the above configuration.
|
||||
|
||||
**Continue with deployment?**
|
||||
- Reply "yes" to proceed
|
||||
- Reply "no" to cancel
|
||||
- Reply "edit" to modify configuration
|
||||
|
||||
[Await user input before continuing...]
|
||||
|
||||
<!-- After user confirms, we proceed with deployment -->
|
||||
<!-- All subsequent steps are automated -->
|
||||
|
||||
Proceeding with deployment...
|
||||
```
|
||||
|
||||
## Help Text Patterns
|
||||
|
||||
### Built-in Help Command
|
||||
|
||||
Create a help subcommand for complex commands:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Main command with help
|
||||
argument-hint: [subcommand] [args]
|
||||
---
|
||||
|
||||
# Command Processor
|
||||
|
||||
if [ "$1" = "help" ] || [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
|
||||
**Command Help**
|
||||
|
||||
USAGE:
|
||||
/command [subcommand] [args]
|
||||
|
||||
SUBCOMMANDS:
|
||||
init [name] Initialize new configuration
|
||||
deploy [env] Deploy to environment
|
||||
status Show current status
|
||||
rollback Rollback last deployment
|
||||
help Show this help
|
||||
|
||||
EXAMPLES:
|
||||
/command init my-project
|
||||
/command deploy staging
|
||||
/command status
|
||||
/command rollback
|
||||
|
||||
For detailed help on a subcommand:
|
||||
/command [subcommand] --help
|
||||
|
||||
Exit.
|
||||
fi
|
||||
|
||||
[Regular command processing...]
|
||||
```
|
||||
|
||||
### Contextual Help
|
||||
|
||||
Provide help based on context:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Context-aware command
|
||||
argument-hint: [operation] [target]
|
||||
---
|
||||
|
||||
# Context-Aware Operation
|
||||
|
||||
if [ -z "$1" ]; then
|
||||
**No operation specified**
|
||||
|
||||
Available operations:
|
||||
- analyze: Analyze target for issues
|
||||
- fix: Apply automatic fixes
|
||||
- report: Generate detailed report
|
||||
|
||||
Usage: /command [operation] [target]
|
||||
|
||||
Examples:
|
||||
/command analyze src/
|
||||
/command fix src/app.js
|
||||
/command report
|
||||
|
||||
Run /command help for more details.
|
||||
|
||||
Exit.
|
||||
fi
|
||||
|
||||
[Command continues if operation provided...]
|
||||
```
|
||||
|
||||
## Error Message Documentation
|
||||
|
||||
### Helpful Error Messages
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Command with good error messages
|
||||
---
|
||||
|
||||
# Validation Command
|
||||
|
||||
if [ -z "$1" ]; then
|
||||
❌ ERROR: Missing required argument
|
||||
|
||||
The 'file-path' argument is required.
|
||||
|
||||
USAGE:
|
||||
/validate [file-path]
|
||||
|
||||
EXAMPLE:
|
||||
/validate src/app.js
|
||||
|
||||
Try again with a file path.
|
||||
|
||||
Exit.
|
||||
fi
|
||||
|
||||
if [ ! -f "$1" ]; then
|
||||
❌ ERROR: File not found: $1
|
||||
|
||||
The specified file does not exist or is not accessible.
|
||||
|
||||
COMMON CAUSES:
|
||||
1. Typo in file path
|
||||
2. File was deleted or moved
|
||||
3. Insufficient permissions
|
||||
|
||||
SUGGESTIONS:
|
||||
- Check spelling: $1
|
||||
- Verify file exists: ls -la $(dirname "$1")
|
||||
- Check permissions: ls -l "$1"
|
||||
|
||||
Exit.
|
||||
fi
|
||||
|
||||
[Command continues if validation passes...]
|
||||
```
|
||||
|
||||
### Error Recovery Guidance
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Command with recovery guidance
|
||||
---
|
||||
|
||||
# Operation Command
|
||||
|
||||
Running operation...
|
||||
|
||||
!`risky-operation.sh`
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
❌ OPERATION FAILED
|
||||
|
||||
The operation encountered an error and could not complete.
|
||||
|
||||
WHAT HAPPENED:
|
||||
The risky-operation.sh script returned a non-zero exit code.
|
||||
|
||||
WHAT THIS MEANS:
|
||||
- Changes may be partially applied
|
||||
- System may be in inconsistent state
|
||||
- Manual intervention may be needed
|
||||
|
||||
RECOVERY STEPS:
|
||||
1. Check operation logs: cat /tmp/operation.log
|
||||
2. Verify system state: /check-state
|
||||
3. If needed, rollback: /rollback-operation
|
||||
4. Fix underlying issue
|
||||
5. Retry operation: /retry-operation
|
||||
|
||||
NEED HELP?
|
||||
- Check troubleshooting guide: /help troubleshooting
|
||||
- Contact support with error code: ERR_OP_FAILED_001
|
||||
|
||||
Exit.
|
||||
fi
|
||||
```
|
||||
|
||||
## Usage Example Documentation
|
||||
|
||||
### Embedded Examples
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Command with embedded examples
|
||||
---
|
||||
|
||||
# Feature Command
|
||||
|
||||
This command performs feature analysis with multiple options.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
\`\`\`
|
||||
/feature analyze src/
|
||||
\`\`\`
|
||||
|
||||
Analyzes all files in src/ directory for feature usage.
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
\`\`\`
|
||||
/feature analyze src/ --detailed
|
||||
\`\`\`
|
||||
|
||||
Provides detailed analysis including:
|
||||
- Feature breakdown by file
|
||||
- Usage patterns
|
||||
- Optimization suggestions
|
||||
|
||||
## Use Cases
|
||||
|
||||
**Use Case 1: Quick overview**
|
||||
\`\`\`
|
||||
/feature analyze .
|
||||
\`\`\`
|
||||
Get high-level feature summary of entire project.
|
||||
|
||||
**Use Case 2: Specific directory**
|
||||
\`\`\`
|
||||
/feature analyze src/components
|
||||
\`\`\`
|
||||
Focus analysis on components directory only.
|
||||
|
||||
**Use Case 3: Comparison**
|
||||
\`\`\`
|
||||
/feature analyze src/ --compare baseline.json
|
||||
\`\`\`
|
||||
Compare current features against baseline.
|
||||
|
||||
---
|
||||
|
||||
Now processing your request...
|
||||
|
||||
[Command implementation...]
|
||||
```
|
||||
|
||||
### Example-Driven Documentation
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Example-heavy command
|
||||
---
|
||||
|
||||
# Transformation Command
|
||||
|
||||
## What This Does
|
||||
|
||||
Transforms data from one format to another.
|
||||
|
||||
## Examples First
|
||||
|
||||
### Example 1: JSON to YAML
|
||||
**Input:** `data.json`
|
||||
\`\`\`json
|
||||
{"name": "test", "value": 42}
|
||||
\`\`\`
|
||||
|
||||
**Command:** `/transform data.json yaml`
|
||||
|
||||
**Output:** `data.yaml`
|
||||
\`\`\`yaml
|
||||
name: test
|
||||
value: 42
|
||||
\`\`\`
|
||||
|
||||
### Example 2: CSV to JSON
|
||||
**Input:** `data.csv`
|
||||
\`\`\`csv
|
||||
name,value
|
||||
test,42
|
||||
\`\`\`
|
||||
|
||||
**Command:** `/transform data.csv json`
|
||||
|
||||
**Output:** `data.json`
|
||||
\`\`\`json
|
||||
[{"name": "test", "value": "42"}]
|
||||
\`\`\`
|
||||
|
||||
### Example 3: With Options
|
||||
**Command:** `/transform data.json yaml --pretty --sort-keys`
|
||||
|
||||
**Result:** Formatted YAML with sorted keys
|
||||
|
||||
---
|
||||
|
||||
## Your Transformation
|
||||
|
||||
File: $1
|
||||
Format: $2
|
||||
|
||||
[Perform transformation...]
|
||||
```
|
||||
|
||||
## Maintenance Documentation
|
||||
|
||||
### Version and Changelog
|
||||
|
||||
```markdown
|
||||
<!--
|
||||
VERSION: 2.1.0
|
||||
LAST UPDATED: 2025-01-15
|
||||
AUTHOR: DevOps Team
|
||||
|
||||
CHANGELOG:
|
||||
v2.1.0 (2025-01-15):
|
||||
- Added support for YAML configuration
|
||||
- Improved error messages
|
||||
- Fixed bug with special characters in arguments
|
||||
|
||||
v2.0.0 (2025-01-01):
|
||||
- BREAKING: Changed argument order
|
||||
- BREAKING: Removed deprecated --old-flag
|
||||
- Added new validation checks
|
||||
- Migration guide: /migration-v2
|
||||
|
||||
v1.5.0 (2024-12-15):
|
||||
- Added --verbose flag
|
||||
- Improved performance by 50%
|
||||
|
||||
v1.0.0 (2024-12-01):
|
||||
- Initial stable release
|
||||
|
||||
MIGRATION NOTES:
|
||||
From v1.x to v2.0:
|
||||
Old: /command arg1 arg2 --old-flag
|
||||
New: /command arg2 arg1
|
||||
|
||||
The --old-flag is removed. Use --new-flag instead.
|
||||
|
||||
DEPRECATION WARNINGS:
|
||||
- The --legacy-mode flag is deprecated as of v2.1.0
|
||||
- Will be removed in v3.0.0 (estimated 2025-06-01)
|
||||
- Use --modern-mode instead
|
||||
|
||||
KNOWN ISSUES:
|
||||
- #123: Slow performance with large files (workaround: use --stream flag)
|
||||
- #456: Special characters in Windows (fix planned for v2.2.0)
|
||||
-->
|
||||
```
|
||||
|
||||
### Maintenance Notes
|
||||
|
||||
```markdown
|
||||
<!--
|
||||
MAINTENANCE NOTES:
|
||||
|
||||
CODE STRUCTURE:
|
||||
- Lines 1-50: Argument parsing and validation
|
||||
- Lines 51-100: Main processing logic
|
||||
- Lines 101-150: Output formatting
|
||||
- Lines 151-200: Error handling
|
||||
|
||||
DEPENDENCIES:
|
||||
- Requires git 2.x or later
|
||||
- Uses jq for JSON processing
|
||||
- Needs bash 4.0+ for associative arrays
|
||||
|
||||
PERFORMANCE:
|
||||
- Fast path for small inputs (< 1MB)
|
||||
- Streams large files to avoid memory issues
|
||||
- Caches results in /tmp for 1 hour
|
||||
|
||||
SECURITY CONSIDERATIONS:
|
||||
- Validates all inputs to prevent injection
|
||||
- Uses allowed-tools to limit Bash access
|
||||
- No credentials in command file
|
||||
|
||||
TESTING:
|
||||
- Unit tests: tests/command-test.sh
|
||||
- Integration tests: tests/integration/
|
||||
- Manual test checklist: tests/manual-checklist.md
|
||||
|
||||
FUTURE IMPROVEMENTS:
|
||||
- TODO: Add support for TOML format
|
||||
- TODO: Implement parallel processing
|
||||
- TODO: Add progress bar for large files
|
||||
|
||||
RELATED FILES:
|
||||
- lib/parser.sh: Shared parsing logic
|
||||
- lib/formatter.sh: Output formatting
|
||||
- config/defaults.yml: Default configuration
|
||||
-->
|
||||
```
|
||||
|
||||
## README Documentation
|
||||
|
||||
Commands should have companion README files:
|
||||
|
||||
```markdown
|
||||
# Command Name
|
||||
|
||||
Brief description of what the command does.
|
||||
|
||||
## Installation
|
||||
|
||||
This command is part of the [plugin-name] plugin.
|
||||
|
||||
Install with:
|
||||
\`\`\`
|
||||
/plugin install plugin-name
|
||||
\`\`\`
|
||||
|
||||
## Usage
|
||||
|
||||
Basic usage:
|
||||
\`\`\`
|
||||
/command-name [arg1] [arg2]
|
||||
\`\`\`
|
||||
|
||||
## Arguments
|
||||
|
||||
- `arg1`: Description (required)
|
||||
- `arg2`: Description (optional, defaults to X)
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Basic Usage
|
||||
\`\`\`
|
||||
/command-name value1 value2
|
||||
\`\`\`
|
||||
|
||||
Description of what happens.
|
||||
|
||||
### Example 2: Advanced Usage
|
||||
\`\`\`
|
||||
/command-name value1 --option
|
||||
\`\`\`
|
||||
|
||||
Description of advanced feature.
|
||||
|
||||
## Configuration
|
||||
|
||||
Optional configuration file: `.claude/command-name.local.md`
|
||||
|
||||
\`\`\`markdown
|
||||
---
|
||||
default_arg: value
|
||||
enable_feature: true
|
||||
---
|
||||
\`\`\`
|
||||
|
||||
## Requirements
|
||||
|
||||
- Git 2.x or later
|
||||
- jq (for JSON processing)
|
||||
- Node.js 14+ (optional, for advanced features)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Command not found
|
||||
|
||||
**Solution:** Ensure plugin is installed and enabled.
|
||||
|
||||
### Issue: Permission denied
|
||||
|
||||
**Solution:** Check file permissions and allowed-tools setting.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||
|
||||
## License
|
||||
|
||||
MIT License - See [LICENSE](LICENSE).
|
||||
|
||||
## Support
|
||||
|
||||
- Issues: https://github.com/user/plugin/issues
|
||||
- Docs: https://docs.example.com
|
||||
- Email: support@example.com
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Documentation Principles
|
||||
|
||||
1. **Write for your future self**: Assume you'll forget details
|
||||
2. **Examples before explanations**: Show, then tell
|
||||
3. **Progressive disclosure**: Basic info first, details available
|
||||
4. **Keep it current**: Update docs when code changes
|
||||
5. **Test your docs**: Verify examples actually work
|
||||
|
||||
### Documentation Locations
|
||||
|
||||
1. **In command file**: Core usage, examples, inline explanations
|
||||
2. **README**: Installation, configuration, troubleshooting
|
||||
3. **Separate docs**: Detailed guides, tutorials, API reference
|
||||
4. **Comments**: Implementation details for maintainers
|
||||
|
||||
### Documentation Style
|
||||
|
||||
1. **Clear and concise**: No unnecessary words
|
||||
2. **Active voice**: "Run the command" not "The command can be run"
|
||||
3. **Consistent terminology**: Use same terms throughout
|
||||
4. **Formatted well**: Use headings, lists, code blocks
|
||||
5. **Accessible**: Assume reader is beginner
|
||||
|
||||
### Documentation Maintenance
|
||||
|
||||
1. **Version everything**: Track what changed when
|
||||
2. **Deprecate gracefully**: Warn before removing features
|
||||
3. **Migration guides**: Help users upgrade
|
||||
4. **Archive old docs**: Keep old versions accessible
|
||||
5. **Review regularly**: Ensure docs match reality
|
||||
|
||||
## Documentation Checklist
|
||||
|
||||
Before releasing a command:
|
||||
|
||||
- [ ] Description in frontmatter is clear
|
||||
- [ ] argument-hint documents all arguments
|
||||
- [ ] Usage examples in comments
|
||||
- [ ] Common use cases shown
|
||||
- [ ] Error messages are helpful
|
||||
- [ ] Requirements documented
|
||||
- [ ] Related commands listed
|
||||
- [ ] Changelog maintained
|
||||
- [ ] Version number updated
|
||||
- [ ] README created/updated
|
||||
- [ ] Examples actually work
|
||||
- [ ] Troubleshooting section complete
|
||||
|
||||
With good documentation, commands become self-service, reducing support burden and improving user experience.
|
||||
463
skills/command-development/references/frontmatter-reference.md
Normal file
463
skills/command-development/references/frontmatter-reference.md
Normal file
@@ -0,0 +1,463 @@
|
||||
# Command Frontmatter Reference
|
||||
|
||||
Complete reference for YAML frontmatter fields in slash commands.
|
||||
|
||||
## Frontmatter Overview
|
||||
|
||||
YAML frontmatter is optional metadata at the start of command files:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Brief description
|
||||
allowed-tools: Read, Write
|
||||
model: sonnet
|
||||
argument-hint: [arg1] [arg2]
|
||||
---
|
||||
|
||||
Command prompt content here...
|
||||
```
|
||||
|
||||
All fields are optional. Commands work without any frontmatter.
|
||||
|
||||
## Field Specifications
|
||||
|
||||
### description
|
||||
|
||||
**Type:** String
|
||||
**Required:** No
|
||||
**Default:** First line of command prompt
|
||||
**Max Length:** ~60 characters recommended for `/help` display
|
||||
|
||||
**Purpose:** Describes what the command does, shown in `/help` output
|
||||
|
||||
**Examples:**
|
||||
```yaml
|
||||
description: Review code for security issues
|
||||
```
|
||||
```yaml
|
||||
description: Deploy to staging environment
|
||||
```
|
||||
```yaml
|
||||
description: Generate API documentation
|
||||
```
|
||||
|
||||
**Best practices:**
|
||||
- Keep under 60 characters for clean display
|
||||
- Start with verb (Review, Deploy, Generate)
|
||||
- Be specific about what command does
|
||||
- Avoid redundant "command" or "slash command"
|
||||
|
||||
**Good:**
|
||||
- ✅ "Review PR for code quality and security"
|
||||
- ✅ "Deploy application to specified environment"
|
||||
- ✅ "Generate comprehensive API documentation"
|
||||
|
||||
**Bad:**
|
||||
- ❌ "This command reviews PRs" (unnecessary "This command")
|
||||
- ❌ "Review" (too vague)
|
||||
- ❌ "A command that reviews pull requests for code quality, security issues, and best practices" (too long)
|
||||
|
||||
### allowed-tools
|
||||
|
||||
**Type:** String or Array of strings
|
||||
**Required:** No
|
||||
**Default:** Inherits from conversation permissions
|
||||
|
||||
**Purpose:** Restrict or specify which tools command can use
|
||||
|
||||
**Formats:**
|
||||
|
||||
**Single tool:**
|
||||
```yaml
|
||||
allowed-tools: Read
|
||||
```
|
||||
|
||||
**Multiple tools (comma-separated):**
|
||||
```yaml
|
||||
allowed-tools: Read, Write, Edit
|
||||
```
|
||||
|
||||
**Multiple tools (array):**
|
||||
```yaml
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Bash(git:*)
|
||||
```
|
||||
|
||||
**Tool Patterns:**
|
||||
|
||||
**Specific tools:**
|
||||
```yaml
|
||||
allowed-tools: Read, Grep, Edit
|
||||
```
|
||||
|
||||
**Bash with command filter:**
|
||||
```yaml
|
||||
allowed-tools: Bash(git:*) # Only git commands
|
||||
allowed-tools: Bash(npm:*) # Only npm commands
|
||||
allowed-tools: Bash(docker:*) # Only docker commands
|
||||
```
|
||||
|
||||
**All tools (not recommended):**
|
||||
```yaml
|
||||
allowed-tools: "*"
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
|
||||
1. **Security:** Restrict command to safe operations
|
||||
```yaml
|
||||
allowed-tools: Read, Grep # Read-only command
|
||||
```
|
||||
|
||||
2. **Clarity:** Document required tools
|
||||
```yaml
|
||||
allowed-tools: Bash(git:*), Read
|
||||
```
|
||||
|
||||
3. **Bash execution:** Enable bash command output
|
||||
```yaml
|
||||
allowed-tools: Bash(git status:*), Bash(git diff:*)
|
||||
```
|
||||
|
||||
**Best practices:**
|
||||
- Be as restrictive as possible
|
||||
- Use command filters for Bash (e.g., `git:*` not `*`)
|
||||
- Only specify when different from conversation permissions
|
||||
- Document why specific tools are needed
|
||||
|
||||
### model
|
||||
|
||||
**Type:** String
|
||||
**Required:** No
|
||||
**Default:** Inherits from conversation
|
||||
**Values:** `sonnet`, `opus`, `haiku`
|
||||
|
||||
**Purpose:** Specify which Claude model executes the command
|
||||
|
||||
**Examples:**
|
||||
```yaml
|
||||
model: haiku # Fast, efficient for simple tasks
|
||||
```
|
||||
```yaml
|
||||
model: sonnet # Balanced performance (default)
|
||||
```
|
||||
```yaml
|
||||
model: opus # Maximum capability for complex tasks
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
|
||||
**Use `haiku` for:**
|
||||
- Simple, formulaic commands
|
||||
- Fast execution needed
|
||||
- Low complexity tasks
|
||||
- Frequent invocations
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Format code file
|
||||
model: haiku
|
||||
---
|
||||
```
|
||||
|
||||
**Use `sonnet` for:**
|
||||
- Standard commands (default)
|
||||
- Balanced speed/quality
|
||||
- Most common use cases
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Review code changes
|
||||
model: sonnet
|
||||
---
|
||||
```
|
||||
|
||||
**Use `opus` for:**
|
||||
- Complex analysis
|
||||
- Architectural decisions
|
||||
- Deep code understanding
|
||||
- Critical tasks
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Analyze system architecture
|
||||
model: opus
|
||||
---
|
||||
```
|
||||
|
||||
**Best practices:**
|
||||
- Omit unless specific need
|
||||
- Use `haiku` for speed when possible
|
||||
- Reserve `opus` for genuinely complex tasks
|
||||
- Test with different models to find right balance
|
||||
|
||||
### argument-hint
|
||||
|
||||
**Type:** String
|
||||
**Required:** No
|
||||
**Default:** None
|
||||
|
||||
**Purpose:** Document expected arguments for users and autocomplete
|
||||
|
||||
**Format:**
|
||||
```yaml
|
||||
argument-hint: [arg1] [arg2] [optional-arg]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
**Single argument:**
|
||||
```yaml
|
||||
argument-hint: [pr-number]
|
||||
```
|
||||
|
||||
**Multiple required arguments:**
|
||||
```yaml
|
||||
argument-hint: [environment] [version]
|
||||
```
|
||||
|
||||
**Optional arguments:**
|
||||
```yaml
|
||||
argument-hint: [file-path] [options]
|
||||
```
|
||||
|
||||
**Descriptive names:**
|
||||
```yaml
|
||||
argument-hint: [source-branch] [target-branch] [commit-message]
|
||||
```
|
||||
|
||||
**Best practices:**
|
||||
- Use square brackets `[]` for each argument
|
||||
- Use descriptive names (not `arg1`, `arg2`)
|
||||
- Indicate optional vs required in description
|
||||
- Match order to positional arguments in command
|
||||
- Keep concise but clear
|
||||
|
||||
**Examples by pattern:**
|
||||
|
||||
**Simple command:**
|
||||
```yaml
|
||||
---
|
||||
description: Fix issue by number
|
||||
argument-hint: [issue-number]
|
||||
---
|
||||
|
||||
Fix issue #$1...
|
||||
```
|
||||
|
||||
**Multi-argument:**
|
||||
```yaml
|
||||
---
|
||||
description: Deploy to environment
|
||||
argument-hint: [app-name] [environment] [version]
|
||||
---
|
||||
|
||||
Deploy $1 to $2 using version $3...
|
||||
```
|
||||
|
||||
**With options:**
|
||||
```yaml
|
||||
---
|
||||
description: Run tests with options
|
||||
argument-hint: [test-pattern] [options]
|
||||
---
|
||||
|
||||
Run tests matching $1 with options: $2
|
||||
```
|
||||
|
||||
### disable-model-invocation
|
||||
|
||||
**Type:** Boolean
|
||||
**Required:** No
|
||||
**Default:** false
|
||||
|
||||
**Purpose:** Prevent SlashCommand tool from programmatically invoking command
|
||||
|
||||
**Examples:**
|
||||
```yaml
|
||||
disable-model-invocation: true
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
|
||||
1. **Manual-only commands:** Commands requiring user judgment
|
||||
```yaml
|
||||
---
|
||||
description: Approve deployment to production
|
||||
disable-model-invocation: true
|
||||
---
|
||||
```
|
||||
|
||||
2. **Destructive operations:** Commands with irreversible effects
|
||||
```yaml
|
||||
---
|
||||
description: Delete all test data
|
||||
disable-model-invocation: true
|
||||
---
|
||||
```
|
||||
|
||||
3. **Interactive workflows:** Commands needing user input
|
||||
```yaml
|
||||
---
|
||||
description: Walk through setup wizard
|
||||
disable-model-invocation: true
|
||||
---
|
||||
```
|
||||
|
||||
**Default behavior (false):**
|
||||
- Command available to SlashCommand tool
|
||||
- Claude can invoke programmatically
|
||||
- Still available for manual invocation
|
||||
|
||||
**When true:**
|
||||
- Command only invokable by user typing `/command`
|
||||
- Not available to SlashCommand tool
|
||||
- Safer for sensitive operations
|
||||
|
||||
**Best practices:**
|
||||
- Use sparingly (limits Claude's autonomy)
|
||||
- Document why in command comments
|
||||
- Consider if command should exist if always manual
|
||||
|
||||
## Complete Examples
|
||||
|
||||
### Minimal Command
|
||||
|
||||
No frontmatter needed:
|
||||
|
||||
```markdown
|
||||
Review this code for common issues and suggest improvements.
|
||||
```
|
||||
|
||||
### Simple Command
|
||||
|
||||
Just description:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review code for issues
|
||||
---
|
||||
|
||||
Review this code for common issues and suggest improvements.
|
||||
```
|
||||
|
||||
### Standard Command
|
||||
|
||||
Description and tools:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review Git changes
|
||||
allowed-tools: Bash(git:*), Read
|
||||
---
|
||||
|
||||
Current changes: !`git diff --name-only`
|
||||
|
||||
Review each changed file for:
|
||||
- Code quality
|
||||
- Potential bugs
|
||||
- Best practices
|
||||
```
|
||||
|
||||
### Complex Command
|
||||
|
||||
All common fields:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Deploy application to environment
|
||||
argument-hint: [app-name] [environment] [version]
|
||||
allowed-tools: Bash(kubectl:*), Bash(helm:*), Read
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
Deploy $1 to $2 environment using version $3
|
||||
|
||||
Pre-deployment checks:
|
||||
- Verify $2 configuration
|
||||
- Check cluster status: !`kubectl cluster-info`
|
||||
- Validate version $3 exists
|
||||
|
||||
Proceed with deployment following deployment runbook.
|
||||
```
|
||||
|
||||
### Manual-Only Command
|
||||
|
||||
Restricted invocation:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Approve production deployment
|
||||
argument-hint: [deployment-id]
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(gh:*)
|
||||
---
|
||||
|
||||
<!--
|
||||
MANUAL APPROVAL REQUIRED
|
||||
This command requires human judgment and cannot be automated.
|
||||
-->
|
||||
|
||||
Review deployment $1 for production approval:
|
||||
|
||||
Deployment details: !`gh api /deployments/$1`
|
||||
|
||||
Verify:
|
||||
- All tests passed
|
||||
- Security scan clean
|
||||
- Stakeholder approval
|
||||
- Rollback plan ready
|
||||
|
||||
Type "APPROVED" to confirm deployment.
|
||||
```
|
||||
|
||||
## Validation
|
||||
|
||||
### Common Errors
|
||||
|
||||
**Invalid YAML syntax:**
|
||||
```yaml
|
||||
---
|
||||
description: Missing quote
|
||||
allowed-tools: Read, Write
|
||||
model: sonnet
|
||||
--- # ❌ Missing closing quote above
|
||||
```
|
||||
|
||||
**Fix:** Validate YAML syntax
|
||||
|
||||
**Incorrect tool specification:**
|
||||
```yaml
|
||||
allowed-tools: Bash # ❌ Missing command filter
|
||||
```
|
||||
|
||||
**Fix:** Use `Bash(git:*)` format
|
||||
|
||||
**Invalid model name:**
|
||||
```yaml
|
||||
model: gpt4 # ❌ Not a valid Claude model
|
||||
```
|
||||
|
||||
**Fix:** Use `sonnet`, `opus`, or `haiku`
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
Before committing command:
|
||||
- [ ] YAML syntax valid (no errors)
|
||||
- [ ] Description under 60 characters
|
||||
- [ ] allowed-tools uses proper format
|
||||
- [ ] model is valid value if specified
|
||||
- [ ] argument-hint matches positional arguments
|
||||
- [ ] disable-model-invocation used appropriately
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
1. **Start minimal:** Add frontmatter only when needed
|
||||
2. **Document arguments:** Always use argument-hint with arguments
|
||||
3. **Restrict tools:** Use most restrictive allowed-tools that works
|
||||
4. **Choose right model:** Use haiku for speed, opus for complexity
|
||||
5. **Manual-only sparingly:** Only use disable-model-invocation when necessary
|
||||
6. **Clear descriptions:** Make commands discoverable in `/help`
|
||||
7. **Test thoroughly:** Verify frontmatter works as expected
|
||||
920
skills/command-development/references/interactive-commands.md
Normal file
920
skills/command-development/references/interactive-commands.md
Normal file
@@ -0,0 +1,920 @@
|
||||
# Interactive Command Patterns
|
||||
|
||||
Comprehensive guide to creating commands that gather user feedback and make decisions through the AskUserQuestion tool.
|
||||
|
||||
## Overview
|
||||
|
||||
Some commands need user input that doesn't work well with simple arguments. For example:
|
||||
- Choosing between multiple complex options with trade-offs
|
||||
- Selecting multiple items from a list
|
||||
- Making decisions that require explanation
|
||||
- Gathering preferences or configuration interactively
|
||||
|
||||
For these cases, use the **AskUserQuestion tool** within command execution rather than relying on command arguments.
|
||||
|
||||
## When to Use AskUserQuestion
|
||||
|
||||
### Use AskUserQuestion When:
|
||||
|
||||
1. **Multiple choice decisions** with explanations needed
|
||||
2. **Complex options** that require context to choose
|
||||
3. **Multi-select scenarios** (choosing multiple items)
|
||||
4. **Preference gathering** for configuration
|
||||
5. **Interactive workflows** that adapt based on answers
|
||||
|
||||
### Use Command Arguments When:
|
||||
|
||||
1. **Simple values** (file paths, numbers, names)
|
||||
2. **Known inputs** user already has
|
||||
3. **Scriptable workflows** that should be automatable
|
||||
4. **Fast invocations** where prompting would slow down
|
||||
|
||||
## AskUserQuestion Basics
|
||||
|
||||
### Tool Parameters
|
||||
|
||||
```typescript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "Which authentication method should we use?",
|
||||
header: "Auth method", // Short label (max 12 chars)
|
||||
multiSelect: false, // true for multiple selection
|
||||
options: [
|
||||
{
|
||||
label: "OAuth 2.0",
|
||||
description: "Industry standard, supports multiple providers"
|
||||
},
|
||||
{
|
||||
label: "JWT",
|
||||
description: "Stateless, good for APIs"
|
||||
},
|
||||
{
|
||||
label: "Session",
|
||||
description: "Traditional, server-side state"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Key points:**
|
||||
- Users can always choose "Other" to provide custom input (automatic)
|
||||
- `multiSelect: true` allows selecting multiple options
|
||||
- Options should be 2-4 choices (not more)
|
||||
- Can ask 1-4 questions per tool call
|
||||
|
||||
## Command Pattern for User Interaction
|
||||
|
||||
### Basic Interactive Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Interactive setup command
|
||||
allowed-tools: AskUserQuestion, Write
|
||||
---
|
||||
|
||||
# Interactive Plugin Setup
|
||||
|
||||
This command will guide you through configuring the plugin with a series of questions.
|
||||
|
||||
## Step 1: Gather Configuration
|
||||
|
||||
Use the AskUserQuestion tool to ask:
|
||||
|
||||
**Question 1 - Deployment target:**
|
||||
- header: "Deploy to"
|
||||
- question: "Which deployment platform will you use?"
|
||||
- options:
|
||||
- AWS (Amazon Web Services with ECS/EKS)
|
||||
- GCP (Google Cloud with GKE)
|
||||
- Azure (Microsoft Azure with AKS)
|
||||
- Local (Docker on local machine)
|
||||
|
||||
**Question 2 - Environment strategy:**
|
||||
- header: "Environments"
|
||||
- question: "How many environments do you need?"
|
||||
- options:
|
||||
- Single (Just production)
|
||||
- Standard (Dev, Staging, Production)
|
||||
- Complete (Dev, QA, Staging, Production)
|
||||
|
||||
**Question 3 - Features to enable:**
|
||||
- header: "Features"
|
||||
- question: "Which features do you want to enable?"
|
||||
- multiSelect: true
|
||||
- options:
|
||||
- Auto-scaling (Automatic resource scaling)
|
||||
- Monitoring (Health checks and metrics)
|
||||
- CI/CD (Automated deployment pipeline)
|
||||
- Backups (Automated database backups)
|
||||
|
||||
## Step 2: Process Answers
|
||||
|
||||
Based on the answers received from AskUserQuestion:
|
||||
|
||||
1. Parse the deployment target choice
|
||||
2. Set up environment-specific configuration
|
||||
3. Enable selected features
|
||||
4. Generate configuration files
|
||||
|
||||
## Step 3: Generate Configuration
|
||||
|
||||
Create `.claude/plugin-name.local.md` with:
|
||||
|
||||
\`\`\`yaml
|
||||
---
|
||||
deployment_target: [answer from Q1]
|
||||
environments: [answer from Q2]
|
||||
features:
|
||||
auto_scaling: [true if selected in Q3]
|
||||
monitoring: [true if selected in Q3]
|
||||
ci_cd: [true if selected in Q3]
|
||||
backups: [true if selected in Q3]
|
||||
---
|
||||
|
||||
# Plugin Configuration
|
||||
|
||||
Generated: [timestamp]
|
||||
Target: [deployment_target]
|
||||
Environments: [environments]
|
||||
\`\`\`
|
||||
|
||||
## Step 4: Confirm and Next Steps
|
||||
|
||||
Confirm configuration created and guide user on next steps.
|
||||
```
|
||||
|
||||
### Multi-Stage Interactive Workflow
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Multi-stage interactive workflow
|
||||
allowed-tools: AskUserQuestion, Read, Write, Bash
|
||||
---
|
||||
|
||||
# Multi-Stage Deployment Setup
|
||||
|
||||
This command walks through deployment setup in stages, adapting based on your answers.
|
||||
|
||||
## Stage 1: Basic Configuration
|
||||
|
||||
Use AskUserQuestion to ask about deployment basics.
|
||||
|
||||
Based on answers, determine which additional questions to ask.
|
||||
|
||||
## Stage 2: Advanced Options (Conditional)
|
||||
|
||||
If user selected "Advanced" deployment in Stage 1:
|
||||
|
||||
Use AskUserQuestion to ask about:
|
||||
- Load balancing strategy
|
||||
- Caching configuration
|
||||
- Security hardening options
|
||||
|
||||
If user selected "Simple" deployment:
|
||||
- Skip advanced questions
|
||||
- Use sensible defaults
|
||||
|
||||
## Stage 3: Confirmation
|
||||
|
||||
Show summary of all selections.
|
||||
|
||||
Use AskUserQuestion for final confirmation:
|
||||
- header: "Confirm"
|
||||
- question: "Does this configuration look correct?"
|
||||
- options:
|
||||
- Yes (Proceed with setup)
|
||||
- No (Start over)
|
||||
- Modify (Let me adjust specific settings)
|
||||
|
||||
If "Modify", ask which specific setting to change.
|
||||
|
||||
## Stage 4: Execute Setup
|
||||
|
||||
Based on confirmed configuration, execute setup steps.
|
||||
```
|
||||
|
||||
## Interactive Question Design
|
||||
|
||||
### Question Structure
|
||||
|
||||
**Good questions:**
|
||||
```markdown
|
||||
Question: "Which database should we use for this project?"
|
||||
Header: "Database"
|
||||
Options:
|
||||
- PostgreSQL (Relational, ACID compliant, best for complex queries)
|
||||
- MongoDB (Document store, flexible schema, best for rapid iteration)
|
||||
- Redis (In-memory, fast, best for caching and sessions)
|
||||
```
|
||||
|
||||
**Poor questions:**
|
||||
```markdown
|
||||
Question: "Database?" // Too vague
|
||||
Header: "DB" // Unclear abbreviation
|
||||
Options:
|
||||
- Option 1 // Not descriptive
|
||||
- Option 2
|
||||
```
|
||||
|
||||
### Option Design Best Practices
|
||||
|
||||
**Clear labels:**
|
||||
- Use 1-5 words
|
||||
- Specific and descriptive
|
||||
- No jargon without context
|
||||
|
||||
**Helpful descriptions:**
|
||||
- Explain what the option means
|
||||
- Mention key benefits or trade-offs
|
||||
- Help user make informed decision
|
||||
- Keep to 1-2 sentences
|
||||
|
||||
**Appropriate number:**
|
||||
- 2-4 options per question
|
||||
- Don't overwhelm with too many choices
|
||||
- Group related options
|
||||
- "Other" automatically provided
|
||||
|
||||
### Multi-Select Questions
|
||||
|
||||
**When to use multiSelect:**
|
||||
|
||||
```markdown
|
||||
Use AskUserQuestion for enabling features:
|
||||
|
||||
Question: "Which features do you want to enable?"
|
||||
Header: "Features"
|
||||
multiSelect: true // Allow selecting multiple
|
||||
Options:
|
||||
- Logging (Detailed operation logs)
|
||||
- Metrics (Performance monitoring)
|
||||
- Alerts (Error notifications)
|
||||
- Backups (Automatic backups)
|
||||
```
|
||||
|
||||
User can select any combination: none, some, or all.
|
||||
|
||||
**When NOT to use multiSelect:**
|
||||
|
||||
```markdown
|
||||
Question: "Which authentication method?"
|
||||
multiSelect: false // Only one auth method makes sense
|
||||
```
|
||||
|
||||
Mutually exclusive choices should not use multiSelect.
|
||||
|
||||
## Command Patterns with AskUserQuestion
|
||||
|
||||
### Pattern 1: Simple Yes/No Decision
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Command with confirmation
|
||||
allowed-tools: AskUserQuestion, Bash
|
||||
---
|
||||
|
||||
# Destructive Operation
|
||||
|
||||
This operation will delete all cached data.
|
||||
|
||||
Use AskUserQuestion to confirm:
|
||||
|
||||
Question: "This will delete all cached data. Are you sure?"
|
||||
Header: "Confirm"
|
||||
Options:
|
||||
- Yes (Proceed with deletion)
|
||||
- No (Cancel operation)
|
||||
|
||||
If user selects "Yes":
|
||||
Execute deletion
|
||||
Report completion
|
||||
|
||||
If user selects "No":
|
||||
Cancel operation
|
||||
Exit without changes
|
||||
```
|
||||
|
||||
### Pattern 2: Multiple Configuration Questions
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Multi-question configuration
|
||||
allowed-tools: AskUserQuestion, Write
|
||||
---
|
||||
|
||||
# Project Configuration Setup
|
||||
|
||||
Gather configuration through multiple questions.
|
||||
|
||||
Use AskUserQuestion with multiple questions in one call:
|
||||
|
||||
**Question 1:**
|
||||
- question: "Which programming language?"
|
||||
- header: "Language"
|
||||
- options: Python, TypeScript, Go, Rust
|
||||
|
||||
**Question 2:**
|
||||
- question: "Which test framework?"
|
||||
- header: "Testing"
|
||||
- options: Jest, PyTest, Go Test, Cargo Test
|
||||
(Adapt based on language from Q1)
|
||||
|
||||
**Question 3:**
|
||||
- question: "Which CI/CD platform?"
|
||||
- header: "CI/CD"
|
||||
- options: GitHub Actions, GitLab CI, CircleCI
|
||||
|
||||
**Question 4:**
|
||||
- question: "Which features do you need?"
|
||||
- header: "Features"
|
||||
- multiSelect: true
|
||||
- options: Linting, Type checking, Code coverage, Security scanning
|
||||
|
||||
Process all answers together to generate cohesive configuration.
|
||||
```
|
||||
|
||||
### Pattern 3: Conditional Question Flow
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Conditional interactive workflow
|
||||
allowed-tools: AskUserQuestion, Read, Write
|
||||
---
|
||||
|
||||
# Adaptive Configuration
|
||||
|
||||
## Question 1: Deployment Complexity
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "How complex is your deployment?"
|
||||
Header: "Complexity"
|
||||
Options:
|
||||
- Simple (Single server, straightforward)
|
||||
- Standard (Multiple servers, load balancing)
|
||||
- Complex (Microservices, orchestration)
|
||||
|
||||
## Conditional Questions Based on Answer
|
||||
|
||||
If answer is "Simple":
|
||||
- No additional questions
|
||||
- Use minimal configuration
|
||||
|
||||
If answer is "Standard":
|
||||
- Ask about load balancing strategy
|
||||
- Ask about scaling policy
|
||||
|
||||
If answer is "Complex":
|
||||
- Ask about orchestration platform (Kubernetes, Docker Swarm)
|
||||
- Ask about service mesh (Istio, Linkerd, None)
|
||||
- Ask about monitoring (Prometheus, Datadog, CloudWatch)
|
||||
- Ask about logging aggregation
|
||||
|
||||
## Process Conditional Answers
|
||||
|
||||
Generate configuration appropriate for selected complexity level.
|
||||
```
|
||||
|
||||
### Pattern 4: Iterative Collection
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Collect multiple items iteratively
|
||||
allowed-tools: AskUserQuestion, Write
|
||||
---
|
||||
|
||||
# Collect Team Members
|
||||
|
||||
We'll collect team member information for the project.
|
||||
|
||||
## Question: How many team members?
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "How many team members should we set up?"
|
||||
Header: "Team size"
|
||||
Options:
|
||||
- 2 people
|
||||
- 3 people
|
||||
- 4 people
|
||||
- 6 people
|
||||
|
||||
## Iterate Through Team Members
|
||||
|
||||
For each team member (1 to N based on answer):
|
||||
|
||||
Use AskUserQuestion for member details:
|
||||
|
||||
Question: "What role for team member [number]?"
|
||||
Header: "Role"
|
||||
Options:
|
||||
- Frontend Developer
|
||||
- Backend Developer
|
||||
- DevOps Engineer
|
||||
- QA Engineer
|
||||
- Designer
|
||||
|
||||
Store each member's information.
|
||||
|
||||
## Generate Team Configuration
|
||||
|
||||
After collecting all N members, create team configuration file with all members and their roles.
|
||||
```
|
||||
|
||||
### Pattern 5: Dependency Selection
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Select dependencies with multi-select
|
||||
allowed-tools: AskUserQuestion
|
||||
---
|
||||
|
||||
# Configure Project Dependencies
|
||||
|
||||
## Question: Required Libraries
|
||||
|
||||
Use AskUserQuestion with multiSelect:
|
||||
|
||||
Question: "Which libraries does your project need?"
|
||||
Header: "Dependencies"
|
||||
multiSelect: true
|
||||
Options:
|
||||
- React (UI framework)
|
||||
- Express (Web server)
|
||||
- TypeORM (Database ORM)
|
||||
- Jest (Testing framework)
|
||||
- Axios (HTTP client)
|
||||
|
||||
User can select any combination.
|
||||
|
||||
## Process Selections
|
||||
|
||||
For each selected library:
|
||||
- Add to package.json dependencies
|
||||
- Generate sample configuration
|
||||
- Create usage examples
|
||||
- Update documentation
|
||||
```
|
||||
|
||||
## Best Practices for Interactive Commands
|
||||
|
||||
### Question Design
|
||||
|
||||
1. **Clear and specific**: Question should be unambiguous
|
||||
2. **Concise header**: Max 12 characters for clean display
|
||||
3. **Helpful options**: Labels are clear, descriptions explain trade-offs
|
||||
4. **Appropriate count**: 2-4 options per question, 1-4 questions per call
|
||||
5. **Logical order**: Questions flow naturally
|
||||
|
||||
### Error Handling
|
||||
|
||||
```markdown
|
||||
# Handle AskUserQuestion Responses
|
||||
|
||||
After calling AskUserQuestion, verify answers received:
|
||||
|
||||
If answers are empty or invalid:
|
||||
Something went wrong gathering responses.
|
||||
|
||||
Please try again or provide configuration manually:
|
||||
[Show alternative approach]
|
||||
|
||||
Exit.
|
||||
|
||||
If answers look correct:
|
||||
Process as expected
|
||||
```
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
```markdown
|
||||
# Start Simple, Get Detailed as Needed
|
||||
|
||||
## Question 1: Setup Type
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "How would you like to set up?"
|
||||
Header: "Setup type"
|
||||
Options:
|
||||
- Quick (Use recommended defaults)
|
||||
- Custom (Configure all options)
|
||||
- Guided (Step-by-step with explanations)
|
||||
|
||||
If "Quick":
|
||||
Apply defaults, minimal questions
|
||||
|
||||
If "Custom":
|
||||
Ask all available configuration questions
|
||||
|
||||
If "Guided":
|
||||
Ask questions with extra explanation
|
||||
Provide recommendations along the way
|
||||
```
|
||||
|
||||
### Multi-Select Guidelines
|
||||
|
||||
**Good multi-select use:**
|
||||
```markdown
|
||||
Question: "Which features do you want to enable?"
|
||||
multiSelect: true
|
||||
Options:
|
||||
- Logging
|
||||
- Metrics
|
||||
- Alerts
|
||||
- Backups
|
||||
|
||||
Reason: User might want any combination
|
||||
```
|
||||
|
||||
**Bad multi-select use:**
|
||||
```markdown
|
||||
Question: "Which database engine?"
|
||||
multiSelect: true // ❌ Should be single-select
|
||||
|
||||
Reason: Can only use one database engine
|
||||
```
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Validation Loop
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Interactive with validation
|
||||
allowed-tools: AskUserQuestion, Bash
|
||||
---
|
||||
|
||||
# Setup with Validation
|
||||
|
||||
## Gather Configuration
|
||||
|
||||
Use AskUserQuestion to collect settings.
|
||||
|
||||
## Validate Configuration
|
||||
|
||||
Check if configuration is valid:
|
||||
- Required dependencies available?
|
||||
- Settings compatible with each other?
|
||||
- No conflicts detected?
|
||||
|
||||
If validation fails:
|
||||
Show validation errors
|
||||
|
||||
Use AskUserQuestion to ask:
|
||||
|
||||
Question: "Configuration has issues. What would you like to do?"
|
||||
Header: "Next step"
|
||||
Options:
|
||||
- Fix (Adjust settings to resolve issues)
|
||||
- Override (Proceed despite warnings)
|
||||
- Cancel (Abort setup)
|
||||
|
||||
Based on answer, retry or proceed or exit.
|
||||
```
|
||||
|
||||
### Build Configuration Incrementally
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Incremental configuration builder
|
||||
allowed-tools: AskUserQuestion, Write, Read
|
||||
---
|
||||
|
||||
# Incremental Setup
|
||||
|
||||
## Phase 1: Core Settings
|
||||
|
||||
Use AskUserQuestion for core settings.
|
||||
|
||||
Save to `.claude/config-partial.yml`
|
||||
|
||||
## Phase 2: Review Core Settings
|
||||
|
||||
Show user the core settings:
|
||||
|
||||
Based on these core settings, you need to configure:
|
||||
- [Setting A] (because you chose [X])
|
||||
- [Setting B] (because you chose [Y])
|
||||
|
||||
Ready to continue?
|
||||
|
||||
## Phase 3: Detailed Settings
|
||||
|
||||
Use AskUserQuestion for settings based on Phase 1 answers.
|
||||
|
||||
Merge with core settings.
|
||||
|
||||
## Phase 4: Final Review
|
||||
|
||||
Present complete configuration.
|
||||
|
||||
Use AskUserQuestion for confirmation:
|
||||
|
||||
Question: "Is this configuration correct?"
|
||||
Options:
|
||||
- Yes (Save and apply)
|
||||
- No (Start over)
|
||||
- Modify (Edit specific settings)
|
||||
```
|
||||
|
||||
### Dynamic Options Based on Context
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Context-aware questions
|
||||
allowed-tools: AskUserQuestion, Bash, Read
|
||||
---
|
||||
|
||||
# Context-Aware Setup
|
||||
|
||||
## Detect Current State
|
||||
|
||||
Check existing configuration:
|
||||
- Current language: !`detect-language.sh`
|
||||
- Existing frameworks: !`detect-frameworks.sh`
|
||||
- Available tools: !`check-tools.sh`
|
||||
|
||||
## Ask Context-Appropriate Questions
|
||||
|
||||
Based on detected language, ask relevant questions.
|
||||
|
||||
If language is TypeScript:
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "Which TypeScript features should we enable?"
|
||||
Options:
|
||||
- Strict Mode (Maximum type safety)
|
||||
- Decorators (Experimental decorator support)
|
||||
- Path Mapping (Module path aliases)
|
||||
|
||||
If language is Python:
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "Which Python tools should we configure?"
|
||||
Options:
|
||||
- Type Hints (mypy for type checking)
|
||||
- Black (Code formatting)
|
||||
- Pylint (Linting and style)
|
||||
|
||||
Questions adapt to project context.
|
||||
```
|
||||
|
||||
## Real-World Example: Multi-Agent Swarm Launch
|
||||
|
||||
**From multi-agent-swarm plugin:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Launch multi-agent swarm
|
||||
allowed-tools: AskUserQuestion, Read, Write, Bash
|
||||
---
|
||||
|
||||
# Launch Multi-Agent Swarm
|
||||
|
||||
## Interactive Mode (No Task List Provided)
|
||||
|
||||
If user didn't provide task list file, help create one interactively.
|
||||
|
||||
### Question 1: Agent Count
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "How many agents should we launch?"
|
||||
Header: "Agent count"
|
||||
Options:
|
||||
- 2 agents (Best for simple projects)
|
||||
- 3 agents (Good for medium projects)
|
||||
- 4 agents (Standard team size)
|
||||
- 6 agents (Large projects)
|
||||
- 8 agents (Complex multi-component projects)
|
||||
|
||||
### Question 2: Task Definition Approach
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "How would you like to define tasks?"
|
||||
Header: "Task setup"
|
||||
Options:
|
||||
- File (I have a task list file ready)
|
||||
- Guided (Help me create tasks interactively)
|
||||
- Custom (Other approach)
|
||||
|
||||
If "File":
|
||||
Ask for file path
|
||||
Validate file exists and has correct format
|
||||
|
||||
If "Guided":
|
||||
Enter iterative task creation mode (see below)
|
||||
|
||||
### Question 3: Coordination Mode
|
||||
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "How should agents coordinate?"
|
||||
Header: "Coordination"
|
||||
Options:
|
||||
- Team Leader (One agent coordinates others)
|
||||
- Collaborative (Agents coordinate as peers)
|
||||
- Autonomous (Independent work, minimal coordination)
|
||||
|
||||
### Iterative Task Creation (If "Guided" Selected)
|
||||
|
||||
For each agent (1 to N from Question 1):
|
||||
|
||||
**Question A: Agent Name**
|
||||
Question: "What should we call agent [number]?"
|
||||
Header: "Agent name"
|
||||
Options:
|
||||
- auth-agent
|
||||
- api-agent
|
||||
- ui-agent
|
||||
- db-agent
|
||||
(Provide relevant suggestions based on common patterns)
|
||||
|
||||
**Question B: Task Type**
|
||||
Question: "What task for [agent-name]?"
|
||||
Header: "Task type"
|
||||
Options:
|
||||
- Authentication (User auth, JWT, OAuth)
|
||||
- API Endpoints (REST/GraphQL APIs)
|
||||
- UI Components (Frontend components)
|
||||
- Database (Schema, migrations, queries)
|
||||
- Testing (Test suites and coverage)
|
||||
- Documentation (Docs, README, guides)
|
||||
|
||||
**Question C: Dependencies**
|
||||
Question: "What does [agent-name] depend on?"
|
||||
Header: "Dependencies"
|
||||
multiSelect: true
|
||||
Options:
|
||||
- [List of previously defined agents]
|
||||
- No dependencies
|
||||
|
||||
**Question D: Base Branch**
|
||||
Question: "Which base branch for PR?"
|
||||
Header: "PR base"
|
||||
Options:
|
||||
- main
|
||||
- staging
|
||||
- develop
|
||||
|
||||
Store all task information for each agent.
|
||||
|
||||
### Generate Task List File
|
||||
|
||||
After collecting all agent task details:
|
||||
|
||||
1. Ask for project name
|
||||
2. Generate task list in proper format
|
||||
3. Save to `.daisy/swarm/tasks.md`
|
||||
4. Show user the file path
|
||||
5. Proceed with launch using generated task list
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Question Writing
|
||||
|
||||
1. **Be specific**: "Which database?" not "Choose option?"
|
||||
2. **Explain trade-offs**: Describe pros/cons in option descriptions
|
||||
3. **Provide context**: Question text should stand alone
|
||||
4. **Guide decisions**: Help user make informed choice
|
||||
5. **Keep concise**: Header max 12 chars, descriptions 1-2 sentences
|
||||
|
||||
### Option Design
|
||||
|
||||
1. **Meaningful labels**: Specific, clear names
|
||||
2. **Informative descriptions**: Explain what each option does
|
||||
3. **Show trade-offs**: Help user understand implications
|
||||
4. **Consistent detail**: All options equally explained
|
||||
5. **2-4 options**: Not too few, not too many
|
||||
|
||||
### Flow Design
|
||||
|
||||
1. **Logical order**: Questions flow naturally
|
||||
2. **Build on previous**: Later questions use earlier answers
|
||||
3. **Minimize questions**: Ask only what's needed
|
||||
4. **Group related**: Ask related questions together
|
||||
5. **Show progress**: Indicate where in flow
|
||||
|
||||
### User Experience
|
||||
|
||||
1. **Set expectations**: Tell user what to expect
|
||||
2. **Explain why**: Help user understand purpose
|
||||
3. **Provide defaults**: Suggest recommended options
|
||||
4. **Allow escape**: Let user cancel or restart
|
||||
5. **Confirm actions**: Summarize before executing
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern: Feature Selection
|
||||
|
||||
```markdown
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "Which features do you need?"
|
||||
Header: "Features"
|
||||
multiSelect: true
|
||||
Options:
|
||||
- Authentication
|
||||
- Authorization
|
||||
- Rate Limiting
|
||||
- Caching
|
||||
```
|
||||
|
||||
### Pattern: Environment Configuration
|
||||
|
||||
```markdown
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "Which environment is this?"
|
||||
Header: "Environment"
|
||||
Options:
|
||||
- Development (Local development)
|
||||
- Staging (Pre-production testing)
|
||||
- Production (Live environment)
|
||||
```
|
||||
|
||||
### Pattern: Priority Selection
|
||||
|
||||
```markdown
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "What's the priority for this task?"
|
||||
Header: "Priority"
|
||||
Options:
|
||||
- Critical (Must be done immediately)
|
||||
- High (Important, do soon)
|
||||
- Medium (Standard priority)
|
||||
- Low (Nice to have)
|
||||
```
|
||||
|
||||
### Pattern: Scope Selection
|
||||
|
||||
```markdown
|
||||
Use AskUserQuestion:
|
||||
|
||||
Question: "What scope should we analyze?"
|
||||
Header: "Scope"
|
||||
Options:
|
||||
- Current file (Just this file)
|
||||
- Current directory (All files in directory)
|
||||
- Entire project (Full codebase scan)
|
||||
```
|
||||
|
||||
## Combining Arguments and Questions
|
||||
|
||||
### Use Both Appropriately
|
||||
|
||||
**Arguments for known values:**
|
||||
```markdown
|
||||
---
|
||||
argument-hint: [project-name]
|
||||
allowed-tools: AskUserQuestion, Write
|
||||
---
|
||||
|
||||
Setup for project: $1
|
||||
|
||||
Now gather additional configuration...
|
||||
|
||||
Use AskUserQuestion for options that require explanation.
|
||||
```
|
||||
|
||||
**Questions for complex choices:**
|
||||
```markdown
|
||||
Project name from argument: $1
|
||||
|
||||
Now use AskUserQuestion to choose:
|
||||
- Architecture pattern
|
||||
- Technology stack
|
||||
- Deployment strategy
|
||||
|
||||
These require explanation, so questions work better than arguments.
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Questions not appearing:**
|
||||
- Verify AskUserQuestion in allowed-tools
|
||||
- Check question format is correct
|
||||
- Ensure options array has 2-4 items
|
||||
|
||||
**User can't make selection:**
|
||||
- Check option labels are clear
|
||||
- Verify descriptions are helpful
|
||||
- Consider if too many options
|
||||
- Ensure multiSelect setting is correct
|
||||
|
||||
**Flow feels confusing:**
|
||||
- Reduce number of questions
|
||||
- Group related questions
|
||||
- Add explanation between stages
|
||||
- Show progress through workflow
|
||||
|
||||
With AskUserQuestion, commands become interactive wizards that guide users through complex decisions while maintaining the clarity that simple arguments provide for straightforward inputs.
|
||||
@@ -0,0 +1,904 @@
|
||||
# Marketplace Considerations for Commands
|
||||
|
||||
Guidelines for creating commands designed for distribution and marketplace success.
|
||||
|
||||
## Overview
|
||||
|
||||
Commands distributed through marketplaces need additional consideration beyond personal use commands. They must work across environments, handle diverse use cases, and provide excellent user experience for unknown users.
|
||||
|
||||
## Design for Distribution
|
||||
|
||||
### Universal Compatibility
|
||||
|
||||
**Cross-platform considerations:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Cross-platform command
|
||||
allowed-tools: Bash(*)
|
||||
---
|
||||
|
||||
# Platform-Aware Command
|
||||
|
||||
Detecting platform...
|
||||
|
||||
case "$(uname)" in
|
||||
Darwin*) PLATFORM="macOS" ;;
|
||||
Linux*) PLATFORM="Linux" ;;
|
||||
MINGW*|MSYS*|CYGWIN*) PLATFORM="Windows" ;;
|
||||
*) PLATFORM="Unknown" ;;
|
||||
esac
|
||||
|
||||
Platform: $PLATFORM
|
||||
|
||||
<!-- Adjust behavior based on platform -->
|
||||
if [ "$PLATFORM" = "Windows" ]; then
|
||||
# Windows-specific handling
|
||||
PATH_SEP="\\"
|
||||
NULL_DEVICE="NUL"
|
||||
else
|
||||
# Unix-like handling
|
||||
PATH_SEP="/"
|
||||
NULL_DEVICE="/dev/null"
|
||||
fi
|
||||
|
||||
[Platform-appropriate implementation...]
|
||||
```
|
||||
|
||||
**Avoid platform-specific commands:**
|
||||
|
||||
```markdown
|
||||
<!-- BAD: macOS-specific -->
|
||||
!`pbcopy < file.txt`
|
||||
|
||||
<!-- GOOD: Platform detection -->
|
||||
if command -v pbcopy > /dev/null; then
|
||||
pbcopy < file.txt
|
||||
elif command -v xclip > /dev/null; then
|
||||
xclip -selection clipboard < file.txt
|
||||
elif command -v clip.exe > /dev/null; then
|
||||
cat file.txt | clip.exe
|
||||
else
|
||||
echo "Clipboard not available on this platform"
|
||||
fi
|
||||
```
|
||||
|
||||
### Minimal Dependencies
|
||||
|
||||
**Check for required tools:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Dependency-aware command
|
||||
allowed-tools: Bash(*)
|
||||
---
|
||||
|
||||
# Check Dependencies
|
||||
|
||||
Required tools:
|
||||
- git
|
||||
- jq
|
||||
- node
|
||||
|
||||
Checking availability...
|
||||
|
||||
MISSING_DEPS=""
|
||||
|
||||
for tool in git jq node; do
|
||||
if ! command -v $tool > /dev/null; then
|
||||
MISSING_DEPS="$MISSING_DEPS $tool"
|
||||
fi
|
||||
done
|
||||
|
||||
if [ -n "$MISSING_DEPS" ]; then
|
||||
❌ ERROR: Missing required dependencies:$MISSING_DEPS
|
||||
|
||||
INSTALLATION:
|
||||
- git: https://git-scm.com/downloads
|
||||
- jq: https://stedolan.github.io/jq/download/
|
||||
- node: https://nodejs.org/
|
||||
|
||||
Install missing tools and try again.
|
||||
|
||||
Exit.
|
||||
fi
|
||||
|
||||
✓ All dependencies available
|
||||
|
||||
[Continue with command...]
|
||||
```
|
||||
|
||||
**Document optional dependencies:**
|
||||
|
||||
```markdown
|
||||
<!--
|
||||
DEPENDENCIES:
|
||||
Required:
|
||||
- git 2.0+: Version control
|
||||
- jq 1.6+: JSON processing
|
||||
|
||||
Optional:
|
||||
- gh: GitHub CLI (for PR operations)
|
||||
- docker: Container operations (for containerized tests)
|
||||
|
||||
Feature availability depends on installed tools.
|
||||
-->
|
||||
```
|
||||
|
||||
### Graceful Degradation
|
||||
|
||||
**Handle missing features:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Feature-aware command
|
||||
---
|
||||
|
||||
# Feature Detection
|
||||
|
||||
Detecting available features...
|
||||
|
||||
FEATURES=""
|
||||
|
||||
if command -v gh > /dev/null; then
|
||||
FEATURES="$FEATURES github"
|
||||
fi
|
||||
|
||||
if command -v docker > /dev/null; then
|
||||
FEATURES="$FEATURES docker"
|
||||
fi
|
||||
|
||||
Available features: $FEATURES
|
||||
|
||||
if echo "$FEATURES" | grep -q "github"; then
|
||||
# Full functionality with GitHub integration
|
||||
echo "✓ GitHub integration available"
|
||||
else
|
||||
# Reduced functionality without GitHub
|
||||
echo "⚠ Limited functionality: GitHub CLI not installed"
|
||||
echo " Install 'gh' for full features"
|
||||
fi
|
||||
|
||||
[Adapt behavior based on available features...]
|
||||
```
|
||||
|
||||
## User Experience for Unknown Users
|
||||
|
||||
### Clear Onboarding
|
||||
|
||||
**First-run experience:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Command with onboarding
|
||||
allowed-tools: Read, Write
|
||||
---
|
||||
|
||||
# First Run Check
|
||||
|
||||
if [ ! -f ".claude/command-initialized" ]; then
|
||||
**Welcome to Command Name!**
|
||||
|
||||
This appears to be your first time using this command.
|
||||
|
||||
WHAT THIS COMMAND DOES:
|
||||
[Brief explanation of purpose and benefits]
|
||||
|
||||
QUICK START:
|
||||
1. Basic usage: /command [arg]
|
||||
2. For help: /command help
|
||||
3. Examples: /command examples
|
||||
|
||||
SETUP:
|
||||
No additional setup required. You're ready to go!
|
||||
|
||||
✓ Initialization complete
|
||||
|
||||
[Create initialization marker]
|
||||
|
||||
Ready to proceed with your request...
|
||||
fi
|
||||
|
||||
[Normal command execution...]
|
||||
```
|
||||
|
||||
**Progressive feature discovery:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Command with tips
|
||||
---
|
||||
|
||||
# Command Execution
|
||||
|
||||
[Main functionality...]
|
||||
|
||||
---
|
||||
|
||||
💡 TIP: Did you know?
|
||||
|
||||
You can speed up this command with the --fast flag:
|
||||
/command --fast [args]
|
||||
|
||||
For more tips: /command tips
|
||||
```
|
||||
|
||||
### Comprehensive Error Handling
|
||||
|
||||
**Anticipate user mistakes:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Forgiving command
|
||||
---
|
||||
|
||||
# User Input Handling
|
||||
|
||||
Argument: "$1"
|
||||
|
||||
<!-- Check for common typos -->
|
||||
if [ "$1" = "hlep" ] || [ "$1" = "hepl" ]; then
|
||||
Did you mean: help?
|
||||
|
||||
Showing help instead...
|
||||
[Display help]
|
||||
|
||||
Exit.
|
||||
fi
|
||||
|
||||
<!-- Suggest similar commands if not found -->
|
||||
if [ "$1" != "valid-option1" ] && [ "$1" != "valid-option2" ]; then
|
||||
❌ Unknown option: $1
|
||||
|
||||
Did you mean:
|
||||
- valid-option1 (most similar)
|
||||
- valid-option2
|
||||
|
||||
For all options: /command help
|
||||
|
||||
Exit.
|
||||
fi
|
||||
|
||||
[Command continues...]
|
||||
```
|
||||
|
||||
**Helpful diagnostics:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Diagnostic command
|
||||
---
|
||||
|
||||
# Operation Failed
|
||||
|
||||
The operation could not complete.
|
||||
|
||||
**Diagnostic Information:**
|
||||
|
||||
Environment:
|
||||
- Platform: $(uname)
|
||||
- Shell: $SHELL
|
||||
- Working directory: $(pwd)
|
||||
- Command: /command $@
|
||||
|
||||
Checking common issues:
|
||||
- Git repository: $(git rev-parse --git-dir 2>&1)
|
||||
- Write permissions: $(test -w . && echo "OK" || echo "DENIED")
|
||||
- Required files: $(test -f config.yml && echo "Found" || echo "Missing")
|
||||
|
||||
This information helps debug the issue.
|
||||
|
||||
For support, include the above diagnostics.
|
||||
```
|
||||
|
||||
## Distribution Best Practices
|
||||
|
||||
### Namespace Awareness
|
||||
|
||||
**Avoid name collisions:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Namespaced command
|
||||
---
|
||||
|
||||
<!--
|
||||
COMMAND NAME: plugin-name-command
|
||||
|
||||
This command is namespaced with the plugin name to avoid
|
||||
conflicts with commands from other plugins.
|
||||
|
||||
Alternative naming approaches:
|
||||
- Use plugin prefix: /plugin-command
|
||||
- Use category: /category-command
|
||||
- Use verb-noun: /verb-noun
|
||||
|
||||
Chosen approach: plugin-name prefix
|
||||
Reasoning: Clearest ownership, least likely to conflict
|
||||
-->
|
||||
|
||||
# Plugin Name Command
|
||||
|
||||
[Implementation...]
|
||||
```
|
||||
|
||||
**Document naming rationale:**
|
||||
|
||||
```markdown
|
||||
<!--
|
||||
NAMING DECISION:
|
||||
|
||||
Command name: /deploy-app
|
||||
|
||||
Alternatives considered:
|
||||
- /deploy: Too generic, likely conflicts
|
||||
- /app-deploy: Less intuitive ordering
|
||||
- /my-plugin-deploy: Too verbose
|
||||
|
||||
Final choice balances:
|
||||
- Discoverability (clear purpose)
|
||||
- Brevity (easy to type)
|
||||
- Uniqueness (unlikely conflicts)
|
||||
-->
|
||||
```
|
||||
|
||||
### Configurability
|
||||
|
||||
**User preferences:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Configurable command
|
||||
allowed-tools: Read
|
||||
---
|
||||
|
||||
# Load User Configuration
|
||||
|
||||
Default configuration:
|
||||
- verbose: false
|
||||
- color: true
|
||||
- max_results: 10
|
||||
|
||||
Checking for user config: .claude/plugin-name.local.md
|
||||
|
||||
if [ -f ".claude/plugin-name.local.md" ]; then
|
||||
# Parse YAML frontmatter for settings
|
||||
VERBOSE=$(grep "^verbose:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
|
||||
COLOR=$(grep "^color:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
|
||||
MAX_RESULTS=$(grep "^max_results:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
|
||||
|
||||
echo "✓ Using user configuration"
|
||||
else
|
||||
echo "Using default configuration"
|
||||
echo "Create .claude/plugin-name.local.md to customize"
|
||||
fi
|
||||
|
||||
[Use configuration in command...]
|
||||
```
|
||||
|
||||
**Sensible defaults:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Command with smart defaults
|
||||
---
|
||||
|
||||
# Smart Defaults
|
||||
|
||||
Configuration:
|
||||
- Format: ${FORMAT:-json} # Defaults to json
|
||||
- Output: ${OUTPUT:-stdout} # Defaults to stdout
|
||||
- Verbose: ${VERBOSE:-false} # Defaults to false
|
||||
|
||||
These defaults work for 80% of use cases.
|
||||
|
||||
Override with arguments:
|
||||
/command --format yaml --output file.txt --verbose
|
||||
|
||||
Or set in .claude/plugin-name.local.md:
|
||||
\`\`\`yaml
|
||||
---
|
||||
format: yaml
|
||||
output: custom.txt
|
||||
verbose: true
|
||||
---
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Version Compatibility
|
||||
|
||||
**Version checking:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Version-aware command
|
||||
---
|
||||
|
||||
<!--
|
||||
COMMAND VERSION: 2.1.0
|
||||
|
||||
COMPATIBILITY:
|
||||
- Requires plugin version: >= 2.0.0
|
||||
- Breaking changes from v1.x documented in MIGRATION.md
|
||||
|
||||
VERSION HISTORY:
|
||||
- v2.1.0: Added --new-feature flag
|
||||
- v2.0.0: BREAKING: Changed argument order
|
||||
- v1.0.0: Initial release
|
||||
-->
|
||||
|
||||
# Version Check
|
||||
|
||||
Command version: 2.1.0
|
||||
Plugin version: [detect from plugin.json]
|
||||
|
||||
if [ "$PLUGIN_VERSION" < "2.0.0" ]; then
|
||||
❌ ERROR: Incompatible plugin version
|
||||
|
||||
This command requires plugin version >= 2.0.0
|
||||
Current version: $PLUGIN_VERSION
|
||||
|
||||
Update plugin:
|
||||
/plugin update plugin-name
|
||||
|
||||
Exit.
|
||||
fi
|
||||
|
||||
✓ Version compatible
|
||||
|
||||
[Command continues...]
|
||||
```
|
||||
|
||||
**Deprecation warnings:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Command with deprecation warnings
|
||||
---
|
||||
|
||||
# Deprecation Check
|
||||
|
||||
if [ "$1" = "--old-flag" ]; then
|
||||
⚠️ DEPRECATION WARNING
|
||||
|
||||
The --old-flag option is deprecated as of v2.0.0
|
||||
It will be removed in v3.0.0 (est. June 2025)
|
||||
|
||||
Use instead: --new-flag
|
||||
|
||||
Example:
|
||||
Old: /command --old-flag value
|
||||
New: /command --new-flag value
|
||||
|
||||
See migration guide: /command migrate
|
||||
|
||||
Continuing with deprecated behavior for now...
|
||||
fi
|
||||
|
||||
[Handle both old and new flags during deprecation period...]
|
||||
```
|
||||
|
||||
## Marketplace Presentation
|
||||
|
||||
### Command Discovery
|
||||
|
||||
**Descriptive naming:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review pull request with security and quality checks
|
||||
---
|
||||
|
||||
<!-- GOOD: Descriptive name and description -->
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Do the thing
|
||||
---
|
||||
|
||||
<!-- BAD: Vague description -->
|
||||
```
|
||||
|
||||
**Searchable keywords:**
|
||||
|
||||
```markdown
|
||||
<!--
|
||||
KEYWORDS: security, code-review, quality, validation, audit
|
||||
|
||||
These keywords help users discover this command when searching
|
||||
for related functionality in the marketplace.
|
||||
-->
|
||||
```
|
||||
|
||||
### Showcase Examples
|
||||
|
||||
**Compelling demonstrations:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Advanced code analysis command
|
||||
---
|
||||
|
||||
# Code Analysis Command
|
||||
|
||||
This command performs deep code analysis with actionable insights.
|
||||
|
||||
## Demo: Quick Security Audit
|
||||
|
||||
Try it now:
|
||||
\`\`\`
|
||||
/analyze-code src/ --security
|
||||
\`\`\`
|
||||
|
||||
**What you'll get:**
|
||||
- Security vulnerability detection
|
||||
- Code quality metrics
|
||||
- Performance bottleneck identification
|
||||
- Actionable recommendations
|
||||
|
||||
**Sample output:**
|
||||
\`\`\`
|
||||
Security Analysis Results
|
||||
=========================
|
||||
|
||||
🔴 Critical (2):
|
||||
- SQL injection risk in users.js:45
|
||||
- XSS vulnerability in display.js:23
|
||||
|
||||
🟡 Warnings (5):
|
||||
- Unvalidated input in api.js:67
|
||||
...
|
||||
|
||||
Recommendations:
|
||||
1. Fix critical issues immediately
|
||||
2. Review warnings before next release
|
||||
3. Run /analyze-code --fix for auto-fixes
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
Ready to analyze your code...
|
||||
|
||||
[Command implementation...]
|
||||
```
|
||||
|
||||
### User Reviews and Feedback
|
||||
|
||||
**Feedback mechanism:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Command with feedback
|
||||
---
|
||||
|
||||
# Command Complete
|
||||
|
||||
[Command results...]
|
||||
|
||||
---
|
||||
|
||||
**How was your experience?**
|
||||
|
||||
This helps improve the command for everyone.
|
||||
|
||||
Rate this command:
|
||||
- 👍 Helpful
|
||||
- 👎 Not helpful
|
||||
- 🐛 Found a bug
|
||||
- 💡 Have a suggestion
|
||||
|
||||
Reply with an emoji or:
|
||||
- /command feedback
|
||||
|
||||
Your feedback matters!
|
||||
```
|
||||
|
||||
**Usage analytics preparation:**
|
||||
|
||||
```markdown
|
||||
<!--
|
||||
ANALYTICS NOTES:
|
||||
|
||||
Track for improvement:
|
||||
- Most common arguments
|
||||
- Failure rates
|
||||
- Average execution time
|
||||
- User satisfaction scores
|
||||
|
||||
Privacy-preserving:
|
||||
- No personally identifiable information
|
||||
- Aggregate statistics only
|
||||
- User opt-out respected
|
||||
-->
|
||||
```
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### Professional Polish
|
||||
|
||||
**Consistent branding:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Branded command
|
||||
---
|
||||
|
||||
# ✨ Command Name
|
||||
|
||||
Part of the [Plugin Name] suite
|
||||
|
||||
[Command functionality...]
|
||||
|
||||
---
|
||||
|
||||
**Need Help?**
|
||||
- Documentation: https://docs.example.com
|
||||
- Support: support@example.com
|
||||
- Community: https://community.example.com
|
||||
|
||||
Powered by Plugin Name v2.1.0
|
||||
```
|
||||
|
||||
**Attention to detail:**
|
||||
|
||||
```markdown
|
||||
<!-- Details that matter -->
|
||||
|
||||
✓ Use proper emoji/symbols consistently
|
||||
✓ Align output columns neatly
|
||||
✓ Format numbers with thousands separators
|
||||
✓ Use color/formatting appropriately
|
||||
✓ Provide progress indicators
|
||||
✓ Show estimated time remaining
|
||||
✓ Confirm successful operations
|
||||
```
|
||||
|
||||
### Reliability
|
||||
|
||||
**Idempotency:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Idempotent command
|
||||
---
|
||||
|
||||
# Safe Repeated Execution
|
||||
|
||||
Checking if operation already completed...
|
||||
|
||||
if [ -f ".claude/operation-completed.flag" ]; then
|
||||
ℹ️ Operation already completed
|
||||
|
||||
Completed at: $(cat .claude/operation-completed.flag)
|
||||
|
||||
To re-run:
|
||||
1. Remove flag: rm .claude/operation-completed.flag
|
||||
2. Run command again
|
||||
|
||||
Otherwise, no action needed.
|
||||
|
||||
Exit.
|
||||
fi
|
||||
|
||||
Performing operation...
|
||||
|
||||
[Safe, repeatable operation...]
|
||||
|
||||
Marking complete...
|
||||
echo "$(date)" > .claude/operation-completed.flag
|
||||
```
|
||||
|
||||
**Atomic operations:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Atomic command
|
||||
---
|
||||
|
||||
# Atomic Operation
|
||||
|
||||
This operation is atomic - either fully succeeds or fully fails.
|
||||
|
||||
Creating temporary workspace...
|
||||
TEMP_DIR=$(mktemp -d)
|
||||
|
||||
Performing changes in isolated environment...
|
||||
[Make changes in $TEMP_DIR]
|
||||
|
||||
if [ $? -eq 0 ]; then
|
||||
✓ Changes validated
|
||||
|
||||
Applying changes atomically...
|
||||
mv $TEMP_DIR/* ./target/
|
||||
|
||||
✓ Operation complete
|
||||
else
|
||||
❌ Changes failed validation
|
||||
|
||||
Rolling back...
|
||||
rm -rf $TEMP_DIR
|
||||
|
||||
No changes applied. Safe to retry.
|
||||
fi
|
||||
```
|
||||
|
||||
## Testing for Distribution
|
||||
|
||||
### Pre-Release Checklist
|
||||
|
||||
```markdown
|
||||
<!--
|
||||
PRE-RELEASE CHECKLIST:
|
||||
|
||||
Functionality:
|
||||
- [ ] Works on macOS
|
||||
- [ ] Works on Linux
|
||||
- [ ] Works on Windows (WSL)
|
||||
- [ ] All arguments tested
|
||||
- [ ] Error cases handled
|
||||
- [ ] Edge cases covered
|
||||
|
||||
User Experience:
|
||||
- [ ] Clear description
|
||||
- [ ] Helpful error messages
|
||||
- [ ] Examples provided
|
||||
- [ ] First-run experience good
|
||||
- [ ] Documentation complete
|
||||
|
||||
Distribution:
|
||||
- [ ] No hardcoded paths
|
||||
- [ ] Dependencies documented
|
||||
- [ ] Configuration options clear
|
||||
- [ ] Version number set
|
||||
- [ ] Changelog updated
|
||||
|
||||
Quality:
|
||||
- [ ] No TODO comments
|
||||
- [ ] No debug code
|
||||
- [ ] Performance acceptable
|
||||
- [ ] Security reviewed
|
||||
- [ ] Privacy considered
|
||||
|
||||
Support:
|
||||
- [ ] README complete
|
||||
- [ ] Troubleshooting guide
|
||||
- [ ] Support contact provided
|
||||
- [ ] Feedback mechanism
|
||||
- [ ] License specified
|
||||
-->
|
||||
```
|
||||
|
||||
### Beta Testing
|
||||
|
||||
**Beta release approach:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Beta command (v0.9.0)
|
||||
---
|
||||
|
||||
# 🧪 Beta Command
|
||||
|
||||
**This is a beta release**
|
||||
|
||||
Features may change based on feedback.
|
||||
|
||||
BETA STATUS:
|
||||
- Version: 0.9.0
|
||||
- Stability: Experimental
|
||||
- Support: Limited
|
||||
- Feedback: Encouraged
|
||||
|
||||
Known limitations:
|
||||
- Performance not optimized
|
||||
- Some edge cases not handled
|
||||
- Documentation incomplete
|
||||
|
||||
Help improve this command:
|
||||
- Report issues: /command report-issue
|
||||
- Suggest features: /command suggest
|
||||
- Join beta testers: /command join-beta
|
||||
|
||||
---
|
||||
|
||||
[Command implementation...]
|
||||
|
||||
---
|
||||
|
||||
**Thank you for beta testing!**
|
||||
|
||||
Your feedback helps make this command better.
|
||||
```
|
||||
|
||||
## Maintenance and Updates
|
||||
|
||||
### Update Strategy
|
||||
|
||||
**Versioned commands:**
|
||||
|
||||
```markdown
|
||||
<!--
|
||||
VERSION STRATEGY:
|
||||
|
||||
Major (X.0.0): Breaking changes
|
||||
- Document all breaking changes
|
||||
- Provide migration guide
|
||||
- Support old version briefly
|
||||
|
||||
Minor (x.Y.0): New features
|
||||
- Backward compatible
|
||||
- Announce new features
|
||||
- Update examples
|
||||
|
||||
Patch (x.y.Z): Bug fixes
|
||||
- No user-facing changes
|
||||
- Update changelog
|
||||
- Security fixes prioritized
|
||||
|
||||
Release schedule:
|
||||
- Patches: As needed
|
||||
- Minors: Monthly
|
||||
- Majors: Annually or as needed
|
||||
-->
|
||||
```
|
||||
|
||||
**Update notifications:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Update-aware command
|
||||
---
|
||||
|
||||
# Check for Updates
|
||||
|
||||
Current version: 2.1.0
|
||||
Latest version: [check if available]
|
||||
|
||||
if [ "$CURRENT_VERSION" != "$LATEST_VERSION" ]; then
|
||||
📢 UPDATE AVAILABLE
|
||||
|
||||
New version: $LATEST_VERSION
|
||||
Current: $CURRENT_VERSION
|
||||
|
||||
What's new:
|
||||
- Feature improvements
|
||||
- Bug fixes
|
||||
- Performance enhancements
|
||||
|
||||
Update with:
|
||||
/plugin update plugin-name
|
||||
|
||||
Release notes: https://releases.example.com/v$LATEST_VERSION
|
||||
fi
|
||||
|
||||
[Command continues...]
|
||||
```
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
### Distribution Design
|
||||
|
||||
1. **Universal**: Works across platforms and environments
|
||||
2. **Self-contained**: Minimal dependencies, clear requirements
|
||||
3. **Graceful**: Degrades gracefully when features unavailable
|
||||
4. **Forgiving**: Anticipates and handles user mistakes
|
||||
5. **Helpful**: Clear errors, good defaults, excellent docs
|
||||
|
||||
### Marketplace Success
|
||||
|
||||
1. **Discoverable**: Clear name, good description, searchable keywords
|
||||
2. **Professional**: Polished presentation, consistent branding
|
||||
3. **Reliable**: Tested thoroughly, handles edge cases
|
||||
4. **Maintainable**: Versioned, updated regularly, supported
|
||||
5. **User-focused**: Great UX, responsive to feedback
|
||||
|
||||
### Quality Standards
|
||||
|
||||
1. **Complete**: Fully documented, all features working
|
||||
2. **Tested**: Works in real environments, edge cases handled
|
||||
3. **Secure**: No vulnerabilities, safe operations
|
||||
4. **Performant**: Reasonable speed, resource-efficient
|
||||
5. **Ethical**: Privacy-respecting, user consent
|
||||
|
||||
With these considerations, commands become marketplace-ready and delight users across diverse environments and use cases.
|
||||
@@ -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.
|
||||
702
skills/command-development/references/testing-strategies.md
Normal file
702
skills/command-development/references/testing-strategies.md
Normal file
@@ -0,0 +1,702 @@
|
||||
# Command Testing Strategies
|
||||
|
||||
Comprehensive strategies for testing slash commands before deployment and distribution.
|
||||
|
||||
## Overview
|
||||
|
||||
Testing commands ensures they work correctly, handle edge cases, and provide good user experience. A systematic testing approach catches issues early and builds confidence in command reliability.
|
||||
|
||||
## Testing Levels
|
||||
|
||||
### Level 1: Syntax and Structure Validation
|
||||
|
||||
**What to test:**
|
||||
- YAML frontmatter syntax
|
||||
- Markdown format
|
||||
- File location and naming
|
||||
|
||||
**How to test:**
|
||||
|
||||
```bash
|
||||
# Validate YAML frontmatter
|
||||
head -n 20 .claude/commands/my-command.md | grep -A 10 "^---"
|
||||
|
||||
# Check for closing frontmatter marker
|
||||
head -n 20 .claude/commands/my-command.md | grep -c "^---" # Should be 2
|
||||
|
||||
# Verify file has .md extension
|
||||
ls .claude/commands/*.md
|
||||
|
||||
# Check file is in correct location
|
||||
test -f .claude/commands/my-command.md && echo "Found" || echo "Missing"
|
||||
```
|
||||
|
||||
**Automated validation script:**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# validate-command.sh
|
||||
|
||||
COMMAND_FILE="$1"
|
||||
|
||||
if [ ! -f "$COMMAND_FILE" ]; then
|
||||
echo "ERROR: File not found: $COMMAND_FILE"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check .md extension
|
||||
if [[ ! "$COMMAND_FILE" =~ \.md$ ]]; then
|
||||
echo "ERROR: File must have .md extension"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Validate YAML frontmatter if present
|
||||
if head -n 1 "$COMMAND_FILE" | grep -q "^---"; then
|
||||
# Count frontmatter markers
|
||||
MARKERS=$(head -n 50 "$COMMAND_FILE" | grep -c "^---")
|
||||
if [ "$MARKERS" -ne 2 ]; then
|
||||
echo "ERROR: Invalid YAML frontmatter (need exactly 2 '---' markers)"
|
||||
exit 1
|
||||
fi
|
||||
echo "✓ YAML frontmatter syntax valid"
|
||||
fi
|
||||
|
||||
# Check for empty file
|
||||
if [ ! -s "$COMMAND_FILE" ]; then
|
||||
echo "ERROR: File is empty"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✓ Command file structure valid"
|
||||
```
|
||||
|
||||
### Level 2: Frontmatter Field Validation
|
||||
|
||||
**What to test:**
|
||||
- Field types correct
|
||||
- Values in valid ranges
|
||||
- Required fields present (if any)
|
||||
|
||||
**Validation script:**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# validate-frontmatter.sh
|
||||
|
||||
COMMAND_FILE="$1"
|
||||
|
||||
# Extract YAML frontmatter
|
||||
FRONTMATTER=$(sed -n '/^---$/,/^---$/p' "$COMMAND_FILE" | sed '1d;$d')
|
||||
|
||||
if [ -z "$FRONTMATTER" ]; then
|
||||
echo "No frontmatter to validate"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Check 'model' field if present
|
||||
if echo "$FRONTMATTER" | grep -q "^model:"; then
|
||||
MODEL=$(echo "$FRONTMATTER" | grep "^model:" | cut -d: -f2 | tr -d ' ')
|
||||
if ! echo "sonnet opus haiku" | grep -qw "$MODEL"; then
|
||||
echo "ERROR: Invalid model '$MODEL' (must be sonnet, opus, or haiku)"
|
||||
exit 1
|
||||
fi
|
||||
echo "✓ Model field valid: $MODEL"
|
||||
fi
|
||||
|
||||
# Check 'allowed-tools' field format
|
||||
if echo "$FRONTMATTER" | grep -q "^allowed-tools:"; then
|
||||
echo "✓ allowed-tools field present"
|
||||
# Could add more sophisticated validation here
|
||||
fi
|
||||
|
||||
# Check 'description' length
|
||||
if echo "$FRONTMATTER" | grep -q "^description:"; then
|
||||
DESC=$(echo "$FRONTMATTER" | grep "^description:" | cut -d: -f2-)
|
||||
LENGTH=${#DESC}
|
||||
if [ "$LENGTH" -gt 80 ]; then
|
||||
echo "WARNING: Description length $LENGTH (recommend < 60 chars)"
|
||||
else
|
||||
echo "✓ Description length acceptable: $LENGTH chars"
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "✓ Frontmatter fields valid"
|
||||
```
|
||||
|
||||
### Level 3: Manual Command Invocation
|
||||
|
||||
**What to test:**
|
||||
- Command appears in `/help`
|
||||
- Command executes without errors
|
||||
- Output is as expected
|
||||
|
||||
**Test procedure:**
|
||||
|
||||
```bash
|
||||
# 1. Start Claude Code
|
||||
claude --debug
|
||||
|
||||
# 2. Check command appears in help
|
||||
> /help
|
||||
# Look for your command in the list
|
||||
|
||||
# 3. Invoke command without arguments
|
||||
> /my-command
|
||||
# Check for reasonable error or behavior
|
||||
|
||||
# 4. Invoke with valid arguments
|
||||
> /my-command arg1 arg2
|
||||
# Verify expected behavior
|
||||
|
||||
# 5. Check debug logs
|
||||
tail -f ~/.claude/debug-logs/latest
|
||||
# Look for errors or warnings
|
||||
```
|
||||
|
||||
### Level 4: Argument Testing
|
||||
|
||||
**What to test:**
|
||||
- Positional arguments work ($1, $2, etc.)
|
||||
- $ARGUMENTS captures all arguments
|
||||
- Missing arguments handled gracefully
|
||||
- Invalid arguments detected
|
||||
|
||||
**Test matrix:**
|
||||
|
||||
| Test Case | Command | Expected Result |
|
||||
|-----------|---------|-----------------|
|
||||
| No args | `/cmd` | Graceful handling or useful message |
|
||||
| One arg | `/cmd arg1` | $1 substituted correctly |
|
||||
| Two args | `/cmd arg1 arg2` | $1 and $2 substituted |
|
||||
| Extra args | `/cmd a b c d` | All captured or extras ignored appropriately |
|
||||
| Special chars | `/cmd "arg with spaces"` | Quotes handled correctly |
|
||||
| Empty arg | `/cmd ""` | Empty string handled |
|
||||
|
||||
**Test script:**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# test-command-arguments.sh
|
||||
|
||||
COMMAND="$1"
|
||||
|
||||
echo "Testing argument handling for /$COMMAND"
|
||||
echo
|
||||
|
||||
echo "Test 1: No arguments"
|
||||
echo " Command: /$COMMAND"
|
||||
echo " Expected: [describe expected behavior]"
|
||||
echo " Manual test required"
|
||||
echo
|
||||
|
||||
echo "Test 2: Single argument"
|
||||
echo " Command: /$COMMAND test-value"
|
||||
echo " Expected: 'test-value' appears in output"
|
||||
echo " Manual test required"
|
||||
echo
|
||||
|
||||
echo "Test 3: Multiple arguments"
|
||||
echo " Command: /$COMMAND arg1 arg2 arg3"
|
||||
echo " Expected: All arguments used appropriately"
|
||||
echo " Manual test required"
|
||||
echo
|
||||
|
||||
echo "Test 4: Special characters"
|
||||
echo " Command: /$COMMAND \"value with spaces\""
|
||||
echo " Expected: Entire phrase captured"
|
||||
echo " Manual test required"
|
||||
```
|
||||
|
||||
### Level 5: File Reference Testing
|
||||
|
||||
**What to test:**
|
||||
- @ syntax loads file contents
|
||||
- Non-existent files handled
|
||||
- Large files handled appropriately
|
||||
- Multiple file references work
|
||||
|
||||
**Test procedure:**
|
||||
|
||||
```bash
|
||||
# Create test files
|
||||
echo "Test content" > /tmp/test-file.txt
|
||||
echo "Second file" > /tmp/test-file-2.txt
|
||||
|
||||
# Test single file reference
|
||||
> /my-command /tmp/test-file.txt
|
||||
# Verify file content is read
|
||||
|
||||
# Test non-existent file
|
||||
> /my-command /tmp/nonexistent.txt
|
||||
# Verify graceful error handling
|
||||
|
||||
# Test multiple files
|
||||
> /my-command /tmp/test-file.txt /tmp/test-file-2.txt
|
||||
# Verify both files processed
|
||||
|
||||
# Test large file
|
||||
dd if=/dev/zero of=/tmp/large-file.bin bs=1M count=100
|
||||
> /my-command /tmp/large-file.bin
|
||||
# Verify reasonable behavior (may truncate or warn)
|
||||
|
||||
# Cleanup
|
||||
rm /tmp/test-file*.txt /tmp/large-file.bin
|
||||
```
|
||||
|
||||
### Level 6: Bash Execution Testing
|
||||
|
||||
**What to test:**
|
||||
- !` commands execute correctly
|
||||
- Command output included in prompt
|
||||
- Command failures handled
|
||||
- Security: only allowed commands run
|
||||
|
||||
**Test procedure:**
|
||||
|
||||
```bash
|
||||
# Create test command with bash execution
|
||||
cat > .claude/commands/test-bash.md << 'EOF'
|
||||
---
|
||||
description: Test bash execution
|
||||
allowed-tools: Bash(echo:*), Bash(date:*)
|
||||
---
|
||||
|
||||
Current date: !`date`
|
||||
Test output: !`echo "Hello from bash"`
|
||||
|
||||
Analysis of output above...
|
||||
EOF
|
||||
|
||||
# Test in Claude Code
|
||||
> /test-bash
|
||||
# Verify:
|
||||
# 1. Date appears correctly
|
||||
# 2. Echo output appears
|
||||
# 3. No errors in debug logs
|
||||
|
||||
# Test with disallowed command (should fail or be blocked)
|
||||
cat > .claude/commands/test-forbidden.md << 'EOF'
|
||||
---
|
||||
description: Test forbidden command
|
||||
allowed-tools: Bash(echo:*)
|
||||
---
|
||||
|
||||
Trying forbidden: !`ls -la /`
|
||||
EOF
|
||||
|
||||
> /test-forbidden
|
||||
# Verify: Permission denied or appropriate error
|
||||
```
|
||||
|
||||
### Level 7: Integration Testing
|
||||
|
||||
**What to test:**
|
||||
- Commands work with other plugin components
|
||||
- Commands interact correctly with each other
|
||||
- State management works across invocations
|
||||
- Workflow commands execute in sequence
|
||||
|
||||
**Test scenarios:**
|
||||
|
||||
**Scenario 1: Command + Hook Integration**
|
||||
|
||||
```bash
|
||||
# Setup: Command that triggers a hook
|
||||
# Test: Invoke command, verify hook executes
|
||||
|
||||
# Command: .claude/commands/risky-operation.md
|
||||
# Hook: PreToolUse that validates the operation
|
||||
|
||||
> /risky-operation
|
||||
# Verify: Hook executes and validates before command completes
|
||||
```
|
||||
|
||||
**Scenario 2: Command Sequence**
|
||||
|
||||
```bash
|
||||
# Setup: Multi-command workflow
|
||||
> /workflow-init
|
||||
# Verify: State file created
|
||||
|
||||
> /workflow-step2
|
||||
# Verify: State file read, step 2 executes
|
||||
|
||||
> /workflow-complete
|
||||
# Verify: State file cleaned up
|
||||
```
|
||||
|
||||
**Scenario 3: Command + MCP Integration**
|
||||
|
||||
```bash
|
||||
# Setup: Command uses MCP tools
|
||||
# Test: Verify MCP server accessible
|
||||
|
||||
> /mcp-command
|
||||
# Verify:
|
||||
# 1. MCP server starts (if stdio)
|
||||
# 2. Tool calls succeed
|
||||
# 3. Results included in output
|
||||
```
|
||||
|
||||
## Automated Testing Approaches
|
||||
|
||||
### Command Test Suite
|
||||
|
||||
Create a test suite script:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# test-commands.sh - Command test suite
|
||||
|
||||
TEST_DIR=".claude/commands"
|
||||
FAILED_TESTS=0
|
||||
|
||||
echo "Command Test Suite"
|
||||
echo "=================="
|
||||
echo
|
||||
|
||||
for cmd_file in "$TEST_DIR"/*.md; do
|
||||
cmd_name=$(basename "$cmd_file" .md)
|
||||
echo "Testing: $cmd_name"
|
||||
|
||||
# Validate structure
|
||||
if ./validate-command.sh "$cmd_file"; then
|
||||
echo " ✓ Structure valid"
|
||||
else
|
||||
echo " ✗ Structure invalid"
|
||||
((FAILED_TESTS++))
|
||||
fi
|
||||
|
||||
# Validate frontmatter
|
||||
if ./validate-frontmatter.sh "$cmd_file"; then
|
||||
echo " ✓ Frontmatter valid"
|
||||
else
|
||||
echo " ✗ Frontmatter invalid"
|
||||
((FAILED_TESTS++))
|
||||
fi
|
||||
|
||||
echo
|
||||
done
|
||||
|
||||
echo "=================="
|
||||
echo "Tests complete"
|
||||
echo "Failed: $FAILED_TESTS"
|
||||
|
||||
exit $FAILED_TESTS
|
||||
```
|
||||
|
||||
### Pre-Commit Hook
|
||||
|
||||
Validate commands before committing:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/pre-commit
|
||||
|
||||
echo "Validating commands..."
|
||||
|
||||
COMMANDS_CHANGED=$(git diff --cached --name-only | grep "\.claude/commands/.*\.md")
|
||||
|
||||
if [ -z "$COMMANDS_CHANGED" ]; then
|
||||
echo "No commands changed"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
for cmd in $COMMANDS_CHANGED; do
|
||||
echo "Checking: $cmd"
|
||||
|
||||
if ! ./scripts/validate-command.sh "$cmd"; then
|
||||
echo "ERROR: Command validation failed: $cmd"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
|
||||
echo "✓ All commands valid"
|
||||
```
|
||||
|
||||
### Continuous Testing
|
||||
|
||||
Test commands in CI/CD:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/test-commands.yml
|
||||
name: Test Commands
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
|
||||
- name: Validate command structure
|
||||
run: |
|
||||
for cmd in .claude/commands/*.md; do
|
||||
echo "Testing: $cmd"
|
||||
./scripts/validate-command.sh "$cmd"
|
||||
done
|
||||
|
||||
- name: Validate frontmatter
|
||||
run: |
|
||||
for cmd in .claude/commands/*.md; do
|
||||
./scripts/validate-frontmatter.sh "$cmd"
|
||||
done
|
||||
|
||||
- name: Check for TODOs
|
||||
run: |
|
||||
if grep -r "TODO" .claude/commands/; then
|
||||
echo "ERROR: TODOs found in commands"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Edge Case Testing
|
||||
|
||||
### Test Edge Cases
|
||||
|
||||
**Empty arguments:**
|
||||
```bash
|
||||
> /cmd ""
|
||||
> /cmd '' ''
|
||||
```
|
||||
|
||||
**Special characters:**
|
||||
```bash
|
||||
> /cmd "arg with spaces"
|
||||
> /cmd arg-with-dashes
|
||||
> /cmd arg_with_underscores
|
||||
> /cmd arg/with/slashes
|
||||
> /cmd 'arg with "quotes"'
|
||||
```
|
||||
|
||||
**Long arguments:**
|
||||
```bash
|
||||
> /cmd $(python -c "print('a' * 10000)")
|
||||
```
|
||||
|
||||
**Unusual file paths:**
|
||||
```bash
|
||||
> /cmd ./file
|
||||
> /cmd ../file
|
||||
> /cmd ~/file
|
||||
> /cmd "/path with spaces/file"
|
||||
```
|
||||
|
||||
**Bash command edge cases:**
|
||||
```markdown
|
||||
# Commands that might fail
|
||||
!`exit 1`
|
||||
!`false`
|
||||
!`command-that-does-not-exist`
|
||||
|
||||
# Commands with special output
|
||||
!`echo ""`
|
||||
!`cat /dev/null`
|
||||
!`yes | head -n 1000000`
|
||||
```
|
||||
|
||||
## Performance Testing
|
||||
|
||||
### Response Time Testing
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# test-command-performance.sh
|
||||
|
||||
COMMAND="$1"
|
||||
|
||||
echo "Testing performance of /$COMMAND"
|
||||
echo
|
||||
|
||||
for i in {1..5}; do
|
||||
echo "Run $i:"
|
||||
START=$(date +%s%N)
|
||||
|
||||
# Invoke command (manual step - record time)
|
||||
echo " Invoke: /$COMMAND"
|
||||
echo " Start time: $START"
|
||||
echo " (Record end time manually)"
|
||||
echo
|
||||
done
|
||||
|
||||
echo "Analyze results:"
|
||||
echo " - Average response time"
|
||||
echo " - Variance"
|
||||
echo " - Acceptable threshold: < 3 seconds for fast commands"
|
||||
```
|
||||
|
||||
### Resource Usage Testing
|
||||
|
||||
```bash
|
||||
# Monitor Claude Code during command execution
|
||||
# In terminal 1:
|
||||
claude --debug
|
||||
|
||||
# In terminal 2:
|
||||
watch -n 1 'ps aux | grep claude'
|
||||
|
||||
# Execute command and observe:
|
||||
# - Memory usage
|
||||
# - CPU usage
|
||||
# - Process count
|
||||
```
|
||||
|
||||
## User Experience Testing
|
||||
|
||||
### Usability Checklist
|
||||
|
||||
- [ ] Command name is intuitive
|
||||
- [ ] Description is clear in `/help`
|
||||
- [ ] Arguments are well-documented
|
||||
- [ ] Error messages are helpful
|
||||
- [ ] Output is formatted readably
|
||||
- [ ] Long-running commands show progress
|
||||
- [ ] Results are actionable
|
||||
- [ ] Edge cases have good UX
|
||||
|
||||
### User Acceptance Testing
|
||||
|
||||
Recruit testers:
|
||||
|
||||
```markdown
|
||||
# Testing Guide for Beta Testers
|
||||
|
||||
## Command: /my-new-command
|
||||
|
||||
### Test Scenarios
|
||||
|
||||
1. **Basic usage:**
|
||||
- Run: `/my-new-command`
|
||||
- Expected: [describe]
|
||||
- Rate clarity: 1-5
|
||||
|
||||
2. **With arguments:**
|
||||
- Run: `/my-new-command arg1 arg2`
|
||||
- Expected: [describe]
|
||||
- Rate usefulness: 1-5
|
||||
|
||||
3. **Error case:**
|
||||
- Run: `/my-new-command invalid-input`
|
||||
- Expected: Helpful error message
|
||||
- Rate error message: 1-5
|
||||
|
||||
### Feedback Questions
|
||||
|
||||
1. Was the command easy to understand?
|
||||
2. Did the output meet your expectations?
|
||||
3. What would you change?
|
||||
4. Would you use this command regularly?
|
||||
```
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
Before releasing a command:
|
||||
|
||||
### Structure
|
||||
- [ ] File in correct location
|
||||
- [ ] Correct .md extension
|
||||
- [ ] Valid YAML frontmatter (if present)
|
||||
- [ ] Markdown syntax correct
|
||||
|
||||
### Functionality
|
||||
- [ ] Command appears in `/help`
|
||||
- [ ] Description is clear
|
||||
- [ ] Command executes without errors
|
||||
- [ ] Arguments work as expected
|
||||
- [ ] File references work
|
||||
- [ ] Bash execution works (if used)
|
||||
|
||||
### Edge Cases
|
||||
- [ ] Missing arguments handled
|
||||
- [ ] Invalid arguments detected
|
||||
- [ ] Non-existent files handled
|
||||
- [ ] Special characters work
|
||||
- [ ] Long inputs handled
|
||||
|
||||
### Integration
|
||||
- [ ] Works with other commands
|
||||
- [ ] Works with hooks (if applicable)
|
||||
- [ ] Works with MCP (if applicable)
|
||||
- [ ] State management works
|
||||
|
||||
### Quality
|
||||
- [ ] Performance acceptable
|
||||
- [ ] No security issues
|
||||
- [ ] Error messages helpful
|
||||
- [ ] Output formatted well
|
||||
- [ ] Documentation complete
|
||||
|
||||
### Distribution
|
||||
- [ ] Tested by others
|
||||
- [ ] Feedback incorporated
|
||||
- [ ] README updated
|
||||
- [ ] Examples provided
|
||||
|
||||
## Debugging Failed Tests
|
||||
|
||||
### Common Issues and Solutions
|
||||
|
||||
**Issue: Command not appearing in /help**
|
||||
|
||||
```bash
|
||||
# Check file location
|
||||
ls -la .claude/commands/my-command.md
|
||||
|
||||
# Check permissions
|
||||
chmod 644 .claude/commands/my-command.md
|
||||
|
||||
# Check syntax
|
||||
head -n 20 .claude/commands/my-command.md
|
||||
|
||||
# Restart Claude Code
|
||||
claude --debug
|
||||
```
|
||||
|
||||
**Issue: Arguments not substituting**
|
||||
|
||||
```bash
|
||||
# Verify syntax
|
||||
grep '\$1' .claude/commands/my-command.md
|
||||
grep '\$ARGUMENTS' .claude/commands/my-command.md
|
||||
|
||||
# Test with simple command first
|
||||
echo "Test: \$1 and \$2" > .claude/commands/test-args.md
|
||||
```
|
||||
|
||||
**Issue: Bash commands not executing**
|
||||
|
||||
```bash
|
||||
# Check allowed-tools
|
||||
grep "allowed-tools" .claude/commands/my-command.md
|
||||
|
||||
# Verify command syntax
|
||||
grep '!\`' .claude/commands/my-command.md
|
||||
|
||||
# Test command manually
|
||||
date
|
||||
echo "test"
|
||||
```
|
||||
|
||||
**Issue: File references not working**
|
||||
|
||||
```bash
|
||||
# Check @ syntax
|
||||
grep '@' .claude/commands/my-command.md
|
||||
|
||||
# Verify file exists
|
||||
ls -la /path/to/referenced/file
|
||||
|
||||
# Check permissions
|
||||
chmod 644 /path/to/referenced/file
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Test early, test often**: Validate as you develop
|
||||
2. **Automate validation**: Use scripts for repeatable checks
|
||||
3. **Test edge cases**: Don't just test the happy path
|
||||
4. **Get feedback**: Have others test before wide release
|
||||
5. **Document tests**: Keep test scenarios for regression testing
|
||||
6. **Monitor in production**: Watch for issues after release
|
||||
7. **Iterate**: Improve based on real usage data
|
||||
Reference in New Issue
Block a user