plugin-validator
Validate plugin structure, manifests, and silent failure patterns. TRIGGERS - plugin validation, validate plugin, check plugin, silent failures, hook audit, stderr emission.
When & Why to Use This Skill
The Plugin Validator is a specialized Claude skill designed to ensure the integrity and reliability of Claude Code marketplace plugins. It performs comprehensive audits of plugin structures, validates manifest files, and identifies critical silent failure patterns in Bash and Python scripts to guarantee robust error handling and marketplace compliance.
Use Cases
- Automated validation of plugin directory structures and mandatory fields in plugin.json manifests to ensure compatibility.
- Detecting and fixing silent failure patterns in shell hooks where commands like mkdir or jq might fail without reporting errors.
- Auditing Python-based plugin components to prevent suppressed exceptions and ensure all errors are correctly emitted to stderr for better observability.
- Streamlining the plugin development lifecycle by integrating mandatory quality checks before marketplace registration.
| name | plugin-validator |
|---|---|
| description | "Validate plugin structure, manifests, and silent failure patterns. TRIGGERS - plugin validation, validate plugin, check plugin, silent failures, hook audit, stderr emission." |
| allowed-tools | Read, Bash, Glob, Grep, TodoWrite |
Plugin Validator
Comprehensive validation for Claude Code marketplace plugins.
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) |