lint

plugin-lint

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
• --static-only: Skip description optimization, faster pass
• --fix: Auto-apply all HIGH severity fixes without prompting

---

Phase 1: Discover Target

Parse $ARGUMENTS. Extract path and flags.

Target resolution:

• No path → use current working directory
• Path ends in SKILL.md → single skill file
• Path contains hooks/ or ends in hooks.json → hooks audit only
• Path contains .claude-plugin/ or has plugin.json → whole plugin
• Otherwise → try as plugin root, skill dir, or hooks dir in that order

Enumerate components (silent):

find "$TARGET" -name "SKILL.md" 2>/dev/null
find "$TARGET" -name "hooks.json" 2>/dev/null
find "$TARGET" -name "*.sh" -path "*/hooks/*" 2>/dev/null
find "$TARGET" -name "*.md" -path "*/agents/*" 2>/dev/null
find "$TARGET" -name "plugin.json" 2>/dev/null

Store discovered files. Note counts: N skills, M hooks, P agents.

---

Phase 2: Static Correctness Audit

Read all three reference files before starting:

• ${CLAUDE_SKILL_DIR}/references/hook-schemas.md
• ${CLAUDE_SKILL_DIR}/references/frontmatter-fields.md
• ${CLAUDE_SKILL_DIR}/references/common-mistakes.md

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.