6.9 KiB
6.9 KiB
/specweave-plugin-dev:plugin-test
Test Claude Code plugins for correctness, activation, and best practices compliance.
You are an expert plugin tester who validates plugin structure and functionality.
Your Task
Validate plugin structure, test activation, and verify best practices compliance.
1. Validation Checklist
File Structure:
# Check plugin exists
ls ~/.claude/plugins/my-plugin
# Verify structure
tree ~/.claude/plugins/my-plugin
# Expected:
# .claude-plugin/plugin.json ✓
# commands/*.md ✓
# skills/*/SKILL.md ✓
plugin.json Validation:
interface PluginManifest {
name: string; // Required: kebab-case
description: string; // Required: activation keywords
version: string; // Required: semver
author?: {
name: string;
email: string;
};
keywords?: string[];
homepage?: string;
repository?: string;
license?: string;
}
// Validate
const plugin = JSON.parse(fs.readFileSync('.claude-plugin/plugin.json'));
assert(plugin.name.match(/^[a-z0-9-]+$/), 'Name must be kebab-case');
assert(plugin.description.length > 20, 'Description too short');
assert(semver.valid(plugin.version), 'Invalid version');
Command Validation:
# Check header format
grep -E '^# /[a-z0-9-]+:[a-z0-9-]+$' commands/*.md
# Verify no YAML frontmatter in commands
! grep -l '^---$' commands/*.md
# Check for clear instructions
grep -A 20 '## Your Task' commands/*.md
Skill Validation:
# Check YAML frontmatter
grep -l '^---$' skills/*/SKILL.md
# Validate activation keywords
grep 'Activates for' skills/*/SKILL.md
# Verify subdirectory structure
find skills -name 'SKILL.md' -not -path 'skills/*/SKILL.md' # Should be empty
2. Activation Testing
Test Slash Command:
# In Claude Code:
# 1. Type "/"
# 2. Verify command appears in autocomplete
# 3. Execute: /my-plugin:my-command
# 4. Verify behavior matches documentation
Test Skill Auto-Activation:
# Test each activation keyword
echo "Testing skill activation..."
# Skill: cost-optimization
# Keywords: reduce costs, save money, cloud costs, finops
# Test: Ask "How can I reduce my AWS costs?"
# Expected: Skill activates, provides cost optimization advice
# Skill: python-expert
# Keywords: python, optimize python, speed up python
# Test: Ask "How do I speed up my Python code?"
# Expected: Skill activates, provides optimization tips
Test Agent Invocation:
// Verify agent exists
const agentPath = '~/.claude/plugins/my-plugin/agents/my-agent/AGENT.md';
assert(fs.existsSync(agentPath), 'Agent file missing');
// Test invocation syntax
Task({
subagent_type: "my-plugin:my-agent:my-agent", // plugin:folder:yaml-name
prompt: "Test agent invocation"
});
3. Best Practices Validation
Naming Convention Check:
# Plugin name: kebab-case only
echo "my-plugin" | grep -E '^[a-z0-9-]+$' ✓
echo "MyPlugin" | grep -E '^[a-z0-9-]+$' ✗ # No CamelCase
# Command names: kebab-case
echo "analyze-costs" | grep -E '^[a-z0-9-]+$' ✓
echo "analyzeCosts" | grep -E '^[a-z0-9-]+$' ✗ # No camelCase
Activation Keyword Quality:
# ✅ Good: Specific, varied keywords
description: Expert cost optimization. Activates for reduce costs, save money, aws costs, cloud spending, finops, cost analysis, budget optimization.
# ⚠️ Weak: Too few keywords
description: Cost expert. Activates for costs.
# ❌ Bad: No keywords
description: Cost optimization plugin.
Documentation Quality:
# Check for:
- [ ] Clear "Your Task" section
- [ ] Code examples with syntax highlighting
- [ ] Workflow/steps
- [ ] "When to Use" section
- [ ] Example usage
4. Integration Testing
Test Plugin Loading:
# Check Claude Code logs
tail -f ~/.claude/logs/claude.log | grep 'my-plugin'
# Expected output:
# ✅ "Loaded plugin: my-plugin"
# ✅ "Registered command: /my-plugin:my-command"
# ✅ "Registered skill: my-skill"
# Red flags:
# ❌ "Failed to parse plugin.json"
# ❌ "YAML parsing error in SKILL.md"
# ❌ "Command header malformed"
Test Cross-Plugin Compatibility:
# Ensure no conflicts with other plugins
ls ~/.claude/plugins/
# Check for:
- Name collisions (same plugin name)
- Command collisions (same /command)
- Skill keyword overlap (acceptable, but note)
5. Performance Testing
Skill Activation Speed:
# Skills should activate in < 100ms
# Monitor: Does Claude Code lag when typing trigger keywords?
# If slow:
# - Reduce skill description length
# - Optimize SKILL.md size (< 50KB)
# - Avoid complex regex in activation patterns
Command Execution:
# Commands should provide first response in < 2s
# Test with: /my-plugin:my-command
# If slow:
# - Check for expensive operations in command instructions
# - Optimize prompt length
6. Security Review
Secret Detection:
# Check for hardcoded secrets
grep -r 'API_KEY\|SECRET\|PASSWORD\|TOKEN' .
# ❌ Hardcoded secrets
const API_KEY = 'sk-1234567890abcdef';
# ✅ Environment variables
const API_KEY = process.env.API_KEY;
Input Validation:
# Ensure commands validate user input
grep -r 'validate\|sanitize\|escape' commands/
# Commands that execute code should warn about risks
7. Testing Workflow
Manual Testing:
- Install plugin:
cp -r my-plugin ~/.claude/plugins/ - Restart Claude Code
- Test commands:
/my-plugin:command - Test skills: Ask trigger questions
- Test agents: Use Task() tool
- Check logs:
~/.claude/logs/
Automated Testing (if applicable):
# Validation script
#!/bin/bash
PLUGIN_DIR="my-plugin"
# Check structure
test -f "$PLUGIN_DIR/.claude-plugin/plugin.json" || exit 1
test -d "$PLUGIN_DIR/commands" || exit 1
test -d "$PLUGIN_DIR/skills" || exit 1
# Validate JSON
jq . "$PLUGIN_DIR/.claude-plugin/plugin.json" > /dev/null || exit 1
# Check SKILL.md files
find "$PLUGIN_DIR/skills" -name 'SKILL.md' -path '*/*/SKILL.md' | wc -l
# Validate YAML frontmatter
for skill in "$PLUGIN_DIR/skills"/*/SKILL.md; do
head -n 5 "$skill" | grep -q '^---$' || echo "Missing YAML: $skill"
done
echo "✅ Plugin validation passed"
8. Common Issues
Issue: Command not appearing
# Check header format
# ❌ Wrong: # my-plugin:my-command
# ❌ Wrong: # /myPlugin:myCommand
# ✅ Correct: # /my-plugin:my-command
Issue: Skill not activating
# Check:
1. YAML frontmatter present?
2. Activation keywords in description?
3. SKILL.md in subdirectory?
4. Claude Code restarted after changes?
Issue: YAML parsing error
# Common causes:
- Unclosed quotes: description: "Missing end quote
- Invalid characters: name: my_skill (use hyphens)
- Missing closing ---
- Incorrect indentation
When to Use
- After creating/modifying plugins
- Before publishing to marketplace
- Debugging plugin activation issues
- Pre-release quality assurance
Test plugins thoroughly before release!