| name | plugin-checker |
| description | Use this skill when asked to "validate plugin", "check plugin structure", "verify plugin", "audit plugin", "is my plugin correct", "plugin issues", or when troubleshooting plugin problems. |
Plugin Checker Skill
This skill provides comprehensive validation guidelines for Claude Code plugins, helping identify structural issues, misconfigurations, and best practice violations.
Validation Checklist
1. Plugin Manifest Validation
Check .claude-plugin/plugin.json:
Required:
Name validation:
Optional fields (if present):
2. Directory Structure Validation
Required structure:
plugin-name/
├── .claude-plugin/
│ └── plugin.json ← REQUIRED
Valid optional directories:
Invalid patterns to flag:
- ❌
AGENTS.md at root (should be agents/*.md)
- ❌
SKILL.md at root (should be skills/*/SKILL.md)
- ❌ Nested
.claude-plugin/ directories
- ❌ Files directly in
skills/ (should be in subdirs)
3. Agent File Validation
For each file in agents/*.md:
Frontmatter checks:
Name field:
Description field:
Model field (if present):
Color field (if present):
Tools field (if present):
Content check:
4. Skill Directory Validation
For each directory in skills/*/:
Structure:
Frontmatter:
Optional subdirectories:
5. Command File Validation
For each file in commands/*.md:
Frontmatter:
Naming:
6. Hooks Validation
For hooks/hooks.json:
JSON structure:
Event names (if present):
Hook entries:
Path portability:
Script references:
7. Security Checks
Credentials:
URLs:
Scripts:
Common Issues and Fixes
Issue: "plugin not found"
Cause: Missing or invalid plugin.json
Fix: Create .claude-plugin/plugin.json with valid JSON and name field
Issue: "agents not loading"
Cause: Agents not in correct location
Fix: Move to agents/ directory with .md extension
Issue: "skill not triggering"
Cause: Weak trigger description or wrong structure
Fix:
- Ensure
skills/{name}/SKILL.md structure
- Add specific trigger phrases to description
Issue: "hooks not running"
Cause: Invalid hooks.json or script permissions
Fix:
- Validate JSON syntax
- Make scripts executable:
chmod +x scripts/*.sh
- Use
${CLAUDE_PLUGIN_ROOT} in paths
Issue: "command not appearing"
Cause: Missing frontmatter or wrong location
Fix: Ensure commands/*.md with description in frontmatter
Validation Commands
Quick structure check:
jq . my-plugin/.claude-plugin/plugin.json
find my-plugin -name "*.md" -o -name "*.json" | head -20
jq . my-plugin/hooks/hooks.json 2>/dev/null || echo "No hooks.json"
Test plugin locally:
claude --plugin-dir /path/to/my-plugin
Debug mode:
claude --debug --plugin-dir /path/to/my-plugin
Validation Report Format
When reporting validation results:
## Plugin Validation Report
### Plugin: [name]
Location: [path]
### Summary
[PASS/FAIL] - [brief assessment]
### Critical Issues (must fix)
- [ ] `path/to/file` - [issue] - [fix]
### Warnings (should fix)
- [ ] `path/to/file` - [issue] - [recommendation]
### Components Found
- Agents: [count] files
- Skills: [count] directories
- Commands: [count] files
- Hooks: [present/not present]
### Positive Findings
- [What's done correctly]
### Recommendations
1. [Priority fix]
2. [Improvement suggestion]
Quick Validation Script
#!/bin/bash
PLUGIN_DIR="${1:-.}"
echo "=== Plugin Validation ==="
if [ -f "$PLUGIN_DIR/.claude-plugin/plugin.json" ]; then
echo "✓ plugin.json exists"
NAME=$(jq -r '.name' "$PLUGIN_DIR/.claude-plugin/plugin.json" 2>/dev/null)
if [ -n "$NAME" ] && [ "$NAME" != "null" ]; then
echo "✓ name: $NAME"
else
echo "✗ ERROR: name field missing or invalid"
fi
else
echo "✗ CRITICAL: .claude-plugin/plugin.json not found"
fi
if [ -d "$PLUGIN_DIR/agents" ]; then
AGENT_COUNT=$(find "$PLUGIN_DIR/agents" -name "*.md" | wc -l)
echo "✓ agents/: $AGENT_COUNT files"
fi
if [ -d "$PLUGIN_DIR/skills" ]; then
SKILL_COUNT=$(find -name | -l)
[ -d ];
CMD_COUNT=$(find -name | -l)
[ -f ];
jq empty 2>/dev/null;
References
