Plugin Validator
Comprehensive validation for Claude Code marketplace plugins.
When to Use This Skill
Use this skill when:
-
Validating plugin structure before release
-
Auditing hooks for silent failures
-
Checking plugin.json syntax and required fields
-
Verifying skill file formatting and frontmatter
Quick Start
Validate a specific plugin
uv run plugins/plugin-dev/skills/plugin-validator/scripts/audit_silent_failures.py plugins/my-plugin/
Validate with fix suggestions
uv run plugins/plugin-dev/skills/plugin-validator/scripts/audit_silent_failures.py plugins/my-plugin/ --fix
Validation Phases
Phase 1: Structure Validation
Check plugin directory structure:
/usr/bin/env bash << 'VALIDATE_EOF' PLUGIN_PATH="${1:-.}"
Check plugin.json exists
if [[ ! -f "$PLUGIN_PATH/plugin.json" ]]; then echo "ERROR: Missing plugin.json" >&2 exit 1 fi
Validate JSON syntax
if ! jq empty "$PLUGIN_PATH/plugin.json" 2>/dev/null; then echo "ERROR: Invalid JSON in plugin.json" >&2 exit 1 fi
Check required fields
REQUIRED_FIELDS=("name" "version" "description") for field in "${REQUIRED_FIELDS[@]}"; do if ! jq -e ".$field" "$PLUGIN_PATH/plugin.json" >/dev/null 2>&1; then echo "ERROR: Missing required field: $field" >&2 exit 1 fi done
echo "Structure validation passed" VALIDATE_EOF
Phase 2: Silent Failure Audit
Critical Rule: All hook entry points MUST emit to stderr on failure.
Run the audit script:
uv run plugins/plugin-dev/skills/plugin-validator/scripts/audit_silent_failures.py plugins/my-plugin/
What Gets Checked
Check Target Files Pattern
Shellcheck hooks/*.sh
SC2155, SC2086, etc.
Silent bash hooks/*.sh
mkdir|cp|mv|rm|jq without if !
Silent Python hooks/*.py
except.*: pass without stderr
Hook Entry Points vs Utility Scripts
Location Type Requirement
plugins//hooks/.sh
Entry point MUST emit to stderr
plugins//hooks/.py
Entry point MUST emit to stderr
plugins//scripts/.sh
Utility Fallback behavior OK
plugins//scripts/.py
Utility Fallback behavior OK
Phase 3: Fix Patterns
Bash: Silent mkdir
BAD - silent failure
mkdir -p "$DIR"
GOOD - emits to stderr
if ! mkdir -p "$DIR" 2>&1; then echo "[plugin] Failed to create directory: $DIR" >&2 fi
Python: Silent except pass
BAD - silent failure
except (json.JSONDecodeError, OSError): pass
GOOD - emits to stderr
except (json.JSONDecodeError, OSError) as e: print(f"[plugin] Warning: {e}", file=sys.stderr)
Integration with /plugin-dev:create
This skill is invoked in Phase 3 of the plugin-add workflow:
3.4 Plugin Validation
MANDATORY: Run plugin-validator before registration.
Task with subagent_type="plugin-dev:plugin-validator" prompt: "Validate the plugin at plugins/$PLUGIN_NAME/"
Exit Codes
Code Meaning
0 All validations passed
1 Violations found (see output)
2 Error (invalid path, missing files)
References
- Silent Failure Patterns
Troubleshooting
Issue Cause Solution
plugin.json not found Missing manifest file Create plugin.json with required fields
Invalid JSON syntax Malformed plugin.json Run jq empty plugin.json to find syntax errors
Missing required field Incomplete manifest Add name, version, description to plugin.json
Shellcheck errors Bash script issues Run shellcheck hooks/*.sh to see details
Silent failure in bash Missing error handling Add if ! check around mkdir/cp/mv/rm commands
Silent except:pass in Python Missing stderr output Add print(..., file=sys.stderr) before pass
Exit code 2 Invalid path or missing files Verify plugin path exists and has correct structure
Violations after --fix Fix suggestions not applied Manually apply suggested fixes from output