Skip to main content
skill CX Codex

plugin-validator — Claude Code skill: audit plugins

plugin-validator — a skill that validates plugin structure before release and catches silent failures in hooks—error-handling gaps in shell commands and unhandled Python exceptions. Essential before publishing to the marketplace.

MIT 122 installs ★ 3 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill plugin-validator -a claude-code
Open on GitHub

What plugin-validator does

plugin-validator runs three validation phases: structural checks on the directory layout and plugin.json syntax, scans for error-prone patterns in bash and Python hooks (commands like mkdir, cp, rm without error traps; except blocks without stderr output), then shows fix templates. It calls Bash, jq, and Grep through uv run.

The validator distinguishes between hook entry points (must always signal failure to stderr) and utility scripts (silent fallback is acceptable). Exit codes are 0 for pass, 1 for violations, 2 for structural issues. After each run, the skill updates itself—if an instruction drifted or failed, the fix lands directly in this file, no deferral.

What it helps with

  • catch silent failures in hooks before marketplace upload
  • verify plugin.json syntax and required fields
  • audit bash commands for missing error handling
  • detect except:pass in Python without stderr
  • get concrete patterns to rewrite problematic code

Example prompts for the agent

  • Check the structure of the plugin in plugins/my-plugin/
  • Run a silent-failure audit on plugins/my-plugin/ and show fixes
  • Validate the plugin before registering it in the marketplace

How to install plugin-validator

1Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill plugin-validator -a claude-code

2Manually: put the files in place

~/.claude/skills/plugin-validator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/plugin-validator/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about plugin-validator

How do I install plugin-validator in Claude Code?

Run npx skills add terrylica/cc-skills --skill plugin-validator -a claude-code, then open ~/.claude/skills/plugin-validator/SKILL.md to verify.

What does plugin-validator do?

It checks that plugin.json has all required fields, that hooks wrap error-prone commands (mkdir, cp, rm) with error traps, that except blocks print to stderr, and provides code samples for each fix.

What's the difference between hooks and scripts in the validator?

Hooks in plugins/*/hooks/ must always report errors to stderr; scripts in plugins/*/scripts/ can fail silently. The validator enforces different rules for each.

Source text

SKILL.md · MIT
---
name: plugin-validator
description: Validate plugin structure and silent failures. TRIGGERS - plugin validation, check plugin, hook audit.
allowed-tools: Read, Bash, Glob, Grep, TodoWrite
---

# Plugin Validator

Comprehensive validation for Claude Code marketplace plugins.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## 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

```bash
# 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:

```bash
/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:

```bash
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

```bash
# 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

```python
# 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:

```markdown
### 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](./references/silent-failure-patterns.md)


## 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          |

## Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. **Locate yourself.** — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation.
1. **What failed?** — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
2. **What worked better than expected?** — Promote it to recommended practice. Document why.
3. **What drifted?** — Any script, reference, or external dependency that no longer matches reality gets fixed now.
4. **Log it.** — Every change gets an evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.

---
---

© terrylica · MIT · terrylica/cc-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set79

The whole set →
ml-failfast-validation ml-failfast-validation is a Claude Code skill that runs preflight checks for machine learning experiments, catching tensor, schema, and gradient errors before long training jobs. CX Codex +1 124installs pr-gfm-validator pr-gfm-validator turns relative markdown links in a pull request body into absolute blob URLs pinned to your feature branch, so reviewers stop landing on 404s. CX Codex +1 123installs pypi-doppler pypi-doppler — a skill for Claude Code and five other platforms that publishes Python packages to PyPI using a token stored in Doppler — local machine only. The bundled script detects CI environments and exits immediately if one is found. CX Codex +1 123installs schema-e2e-validation The schema-e2e-validation skill runs YAML schema generation and Earthly E2E checks. Use it before committing schema changes or to compare a contract with ClickHouse Cloud. CX Codex +1 123installs evolutionary-metric-ranking evolutionary-metric-ranking is a Claude Code skill that ranks and filters model and strategy configurations across multiple metrics using percentile cutoffs, intersection rules, and evolutionary search. CX Codex +1 121installs pre-ship-review The pre-ship-review skill runs structured quality checks before a pull request, release, or milestone. It catches integration failures where contracts, examples, and tests must align across files. CX Codex +1 120installs pueue-job-orchestration pueue-job-orchestration manages long-running tasks and batch processing using pueue queue orchestration, parallelism groups, and detailed CLI logs. CX Codex +1 120installs distributed-job-safety The distributed-job-safety skill helps prevent file collisions and unsafe concurrency in pipelines using pueue, moon, and systemd-run. Use it when jobs share files or compete for host resources. CX Codex +1 120installs

Project sponsors

Companies that keep this analytics open