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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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
