// Pre-commit mechanical validator — checks plugin registration, SKILL.md frontmatter, hook executability, and token budget. Focuses on correctness; complements `/entropy-scan` which focuses on drift.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | validate-marketplace |
| description | Pre-commit mechanical validator — checks plugin registration, SKILL.md frontmatter, hook executability, and token budget. Focuses on correctness; complements `/entropy-scan` which focuses on drift. |
| when_to_use | Reach for this before committing any change to `plugins/`, after editing `marketplace.json` or a SKILL.md frontmatter, before bumping a plugin version, or when `/entropy-scan` reports a registration gap and you want a focused pass. Do NOT use for documentation-vs-reality drift (counts, stale README) — that's `/entropy-scan`; validate-marketplace answers "will the install succeed?". |
| disable-model-invocation | true |
| allowed-tools | ["Read","Bash","Glob","Grep"] |
| logical | report shows OK / FAIL per check; returns CLEAN when every check passes |
Mechanical validation of marketplace integrity. Fast, deterministic, scriptable. Distinct from /entropy-scan: this skill focuses on correctness (will the marketplace install cleanly?), not drift (is the README accurate?).
marketplace.json or a SKILL.md/entropy-scan reports issues and you want a focused passRun the checks below. Stop at the first check that returns FAIL if time-constrained; otherwise run all and produce a structured report.
marketplace.json Parsespython3 plugins/diagnostics/skills/validate-marketplace/scripts/check-parses.py
Every plugins/*/ directory must have a marketplace entry whose name matches the directory and whose source points to ./plugins/<name>. And vice versa.
python3 plugins/diagnostics/skills/validate-marketplace/scripts/check-registration.py
Every SKILL.md must have description. Only the 2026 official fields are allowed; unknown keys are flagged.
Allowed fields (per code.claude.com/docs/en/skills, 2026 schema):
name, description, when_to_use, argument-hint, arguments,
disable-model-invocation, user-invocable, allowed-tools, model,
effort, context, agent, hooks, paths, shell.
python3 plugins/diagnostics/skills/validate-marketplace/scripts/check-frontmatter.py
Every plugins/*/hooks/*.sh must be executable. hooks.json files are not expected to be executable.
non_exec=$(find plugins -type f -path '*/hooks/*.sh' ! -perm -u+x 2>/dev/null)
if [ -z "$non_exec" ]; then
echo "HOOK_EXEC: CLEAN"
else
echo "HOOK_EXEC: FAIL"
echo "$non_exec"
fi
Every plugins/*/hooks/hooks.json must parse.
python3 plugins/diagnostics/skills/validate-marketplace/scripts/check-hooks-json.py
Every agent .md in plugins/*/agents/ must have valid frontmatter and any skill it preloads
must NOT have disable-model-invocation: true (per official docs: disabled skills cannot be
preloaded into a subagent — Claude Code silently skips them).
python3 plugins/diagnostics/skills/validate-marketplace/scripts/check-agents.py
Skills should stay under the compaction survival budget.
| Band | Character count | Approx tokens | Status |
|---|---|---|---|
| Ideal | ≤ 8,000 | ≤ 2,000 | OK |
| Warn | 8,001–20,000 | 2,000–5,000 | truncation risk after compaction |
| Fail | > 20,000 | > 5,000 | will be dropped after compaction |
python3 plugins/diagnostics/skills/validate-marketplace/scripts/check-skill-size.py
Each plugins/<name>/.claude-plugin/plugin.json version must equal the corresponding .claude-plugin/marketplace.json entry. A mismatch ships a wrong version label to users.
python3 plugins/diagnostics/skills/validate-marketplace/scripts/check-version-sync.py
Every shell script under plugins/*/hooks/, plugins/*/skills/*/scripts/, and plugins/*/lib/ must pass bash -n. Catches syntax breakage before a hook fires at runtime.
python3 plugins/diagnostics/skills/validate-marketplace/scripts/check-bash-syntax.py
The <available_skills> block injected into the LLM context at runtime has a 15 000-byte ceiling. Only auto-loadable skills (those without disable-model-invocation: true) occupy this block; skills with that flag appear only in the user-facing / menu and are excluded from the count. This check sums description+when_to_use UTF-8 bytes across auto-loadable skills only.
python3 plugins/diagnostics/skills/validate-marketplace/scripts/check-registry-budget.py
Every SKILL.md body (content after the closing --- of frontmatter) must be under 500 lines. Longer bodies saturate the context window before the skill has finished reasoning (Source 5: Anthropic best-practices, 2026).
python3 plugins/diagnostics/skills/validate-marketplace/scripts/check-body-lines.py
The name: field in every SKILL.md frontmatter must match ^[a-z0-9]+(-[a-z0-9]+)*$: lowercase alphanumeric segments joined by single hyphens, no underscores, no consecutive hyphens, no leading/trailing hyphen.
python3 plugins/diagnostics/skills/validate-marketplace/scripts/check-frontmatter.py
One section per check, then a verdict.
## Validate Marketplace Report
### Check N — <title>
Status: {OK / CLEAN / {N} failures / FAIL}
{check-specific lines: counts, file lists, deltas — only when non-clean}
### Verdict
Overall: {VALID / INVALID}
{One-line remediation per issue kind}
Per-check non-clean payloads:
| Check | Payload on failure |
|---|---|
| 1 marketplace parse | parser error |
| 2 registration | Missing marketplace entry, Missing plugin directory, Source path mismatches |
| 3 frontmatter | failing SKILL.md paths + reason |
| 4 hook exec | non-executable script paths |
| 5 hooks.json | parse-error path + line |
| 6 agents | unknown/banned fields, disabled-skill preloads |
| 7 size | Oversized-fail (>5,000 tokens, dropped), Oversized-warn (>2,000 tokens, truncation risk) |
| 8 version sync | (plugin, marketplace_version, plugin_json_version) |
| 9 bash syntax | (path, stderr) |
/entropy-scan: this checks correctness, entropy-scan checks drift. A commit can pass validate-marketplace while entropy-scan reports stale README counts.python3), report SKIPPED for that check rather than failing the whole scan.plugins/ has no subdirectories, report the whole scan as N/A.check-parses.py — marketplace.json parses, plugin count looks sanecheck-registration.py — no missing entries, no missing dirs, no source-path mismatchescheck-frontmatter.py — every SKILL.md frontmatter is valid YAML and within schemafind ! -perm -u+x hook-executability check — cleancheck-hooks-json.py — every hooks.json parsescheck-agents.py — no banned fields, no disabled-skill preloadscheck-skill-size.py — no file over the compaction-fail thresholdcheck-version-sync.py — every plugin.json version matches marketplace.jsoncheck-bash-syntax.py — every shell script parseswhen_to_use. A field value that begins with a backtick (e.g. when_to_use: `/foo` after...) reads as YAML's tag indicator and rejects the file. The check reports yaml error: ... cannot start any token; fix by quoting the value or rewording so it starts with a letter.--- reads as "no frontmatter" instead of "broken frontmatter". The reported failure looks like a missing description even though the field is there — check the closing delimiter first.source path mismatch after rename. Renaming a plugin directory without updating the source: ./plugins/<name> field in marketplace.json produces SOURCE_PATH_MISMATCH while every other check passes. The plugin still won't install.skills: list referencing a SKILL.md with disable-model-invocation: true is silently skipped at runtime; the agent runs without the preload and the user sees no error. check-agents.py flags this so the misconfiguration surfaces before merge.