Skip to content

content-hook-candidate

Detect instructions that should be automated as hooks instead of prose instructions
Severity info (auto)
Autofix -
Since v0.7.0
Category Content Intelligence

Why

Prose instructions like "always run the formatter before committing" depend on the model choosing to follow them every time. Hooks execute deterministically on every matching event — they cannot be forgotten or deprioritized. Converting automatable instructions to hooks makes the behavior reliable instead of aspirational.

Examples

Bad:

Always run `prettier --write` after every change.
Run tests before every commit.

Good (hooks.json):

{
  "hooks": {
    "PostToolUse": [
      {"hooks": [{"type": "command", "command": "prettier --write ."}]}
    ]
  }
}

How to fix

Move the instruction into a hook configuration (.claude/hooks.json or equivalent). Use the hook type suggested in the violation message (e.g., pre-commit, PostToolUse, Stop). You can keep a brief note in the instruction file referencing the hook for documentation purposes.

Configuration

rules:
  content-hook-candidate:
    enabled: auto  # true | false | auto
    severity: info

Research Basis

Identifies instructions that should be automated as hooks instead of prose instructions (e.g., "always run tests before committing").

Instructions like "run tests before every commit" are advisory — the model follows them probabilistically. A pre-commit hook runs deterministically, every time, without fail. When an instruction describes a mechanical, automatable action, it should be a hook.

As one practitioner put it: "The hook does not forget. It does not reason. It does not skip." Instruction files should focus on judgment calls and context-dependent decisions that only the model can make. Automatable actions belong in hooks.

References:

Run skillsaw explain content-hook-candidate to see this documentation and the rule's effective configuration in your terminal.