Lint and audit a Claude Code plugin, skill, or hook for correctness, token efficiency, and quality. Runs static analysis against verified Claude Code internals, then delegates to skill-creator for description optimization and eval benchmarking. Use when reviewing plugin changes, writing new hooks/skills, debugging a hook that silently does nothing, or before merging to main.
Lint and audit a Claude Code plugin, skill, or hook for correctness, token efficiency, and quality. Runs static analysis against verified Claude Code internals, then delegates to skill-creator for description optimization and eval benchmarking. Use when reviewing plugin changes, writing new hooks/skills, debugging a hook that silently does nothing, or before merging to main.
when_to_use
Before merging plugin changes, after writing a new skill or hook, debugging unexpected hook behavior, validating a whole plugin directory, or running pre-commit quality checks.
Orchestrated quality audit for Claude Code plugins. Runs static correctness checks first (the unique value), then delegates to existing tools for depth.
Flags:
(default): Full lint — static analysis + skill-creator description optimization
Collect findings as a list. Each finding: {severity, file, line, issue, fix}.
2a. Audit hooks.json files
For each hooks.json found:
if condition syntax:
grep -n '"if"'"$HOOKS_JSON"
Flag any value containing ==, ===, ||, &&, != — these are JS expressions, not permission-rule syntax. Correct form: "Bash", "Bash(git *)", "Write".
hookSpecificOutput event names:
grep -n '"hookEventName"'"$HOOKS_JSON"
Cross-reference against the valid-events table in hook-schemas.md. Flag "PreCompact" — it has no schema entry. Flag any unknown event name.
SessionStart matcher:
grep -n '"matcher"'"$HOOKS_JSON"
If the hook event is SessionStart and the matcher doesn't include clear, flag as MEDIUM.
updatedMCPToolOutput on built-in tools:
For each PostToolUse hook, check if the hook script references updatedMCPToolOutput. If so, also check the if condition — if it targets a built-in tool (Bash, Read, Write, Edit, Grep, Glob), flag HIGH.
2b. Audit hook shell scripts
For each .sh in hooks/:
Wrong input field name:
grep -n 'tool_output'"$SCRIPT"
Flag any tool_output reference — correct field is tool_response.
JSON PreCompact output:
grep -n 'hookEventName.*PreCompact'"$SCRIPT"
Flag — PreCompact must use plain stdout, not JSON hookSpecificOutput.
Placeholder scripts:
If script has fewer than 5 non-comment lines and only outputs suppressOutput: true, flag as LOW (dead weight — spawns process for nothing).
2c. Audit SKILL.md files
For each SKILL.md found:
Extract frontmatter (between first and second ---):
Compare against hookSpecificOutput event names found in target's hooks. Cite actual source line numbers in findings. Upgrade confidence of all schema findings from "reference says" to "source-verified at line N".
If not available, note "source not present — findings based on reference docs only."
Phase 4: Description Quality Delegation
Skip if --static-only flag is set.
For each SKILL.md with a non-empty description:
Invoke skill-creator's description optimization. Spawn as background Agent tasks (parallel if multiple skills):
Agent task prompt:
"Use the skill-creator skill to run description optimization on this skill.
Skill path: <path>
Current description: <description>
Run the description optimization loop (not full evals — just the trigger optimization).
Find the skill-creator scripts at: ~/.claude/plugins/cache/claude-plugins-official/skill-creator/unknown/skills/skill-creator/
Report: original score, best score, and the improved description if score improved by >0.05."
Collect results as each task completes. Note: skill-creator needs the claude CLI available for run_loop.py.
If claude CLI is not found or skill-creator scripts are absent, skip this phase and note why.
Phase 5: Synthesize and Report
Present unified report:
## plugin-lint Report: <target path>
Checked: <N> skills, <M> hooks.json, <P> hook scripts, <Q> agents
Source verification: [available / not available]
### 🔴 HIGH — Must Fix (<count>)
<file>:<line> <issue>
→ Fix: <specific correction>
### 🟡 MEDIUM — Should Fix (<count>)
...
### 🟢 LOW — Consider (<count>)
...
### ✅ Clean
<files with no issues>
### Description Optimization Results
<skill-name>: <old-score> → <new-score>
New description: "<improved text>"
<skill-name>: <score> — no improvement found
[skipped — --static-only]
If zero findings and no description improvements: "All checks passed. No issues found."
Then — unless --fix was passed:
AskUserQuestion:question:"Found <N> issues. How would you like to proceed?"header:"plugin-lint"multiSelect:falseoptions:-label:"Apply all HIGH fixes"description:"Auto-fix the <count> HIGH severity issues"-label:"Walk me through each issue"description:"Review and approve fixes one by one"-label:"Apply description improvements"description:"Update descriptions with optimized versions"-label:"Just the report"description:"No changes — report only"
If --fix: apply all HIGH fixes automatically, then show report.
Applying Fixes
For each HIGH finding, apply the specific correction:
Bad if syntax → rewrite the "if" value in hooks.json
when_not_to_use frontmatter → remove the line
Body corruption (extra when_to_use: lines) → remove all occurrences after the frontmatter close
Wrong tool_output field → replace with tool_response in the script
PreCompact JSON → rewrite script to output plain text
After applying fixes, re-run Phase 2 on modified files to confirm clean.
Reference Files
Load on demand — do not load all at once:
references/hook-schemas.md — hook event schemas, if syntax, input fields
references/frontmatter-fields.md — valid frontmatter keys for skills and agents
references/common-mistakes.md — top 10 failure patterns with source citations
