plugin-validator

terrylica 的头像作者 terrylica

验证插件结构、清单和静默失败模式。触发器 - 插件验证,验证插件,检查插件,静默失败,钩子审计,stderr输出。

📖 中文导读:验证插件结构、清单和静默失败模式。触发器 - 插件验证,验证插件,检查插件,静默失败,钩子审计,stderr输出。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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)

References