plugin-validator

Validate plugin structure, manifests, and silent failure patterns. TRIGGERS - plugin validation, validate plugin, check plugin, silent failures, hook audit, stderr emission.

⭐4stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026⬇️1downloads

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.
nameplugin-validator
description"Validate plugin structure, manifests, and silent failure patterns. TRIGGERS - plugin validation, validate plugin, check plugin, silent failures, hook audit, stderr emission."
allowed-toolsRead, 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)

References