Hooks vs Agent Skills
A hook always runs; a skill runs when Claude judges it relevant. That single difference decides which one you need.
Last verified August 21, 2026
The short answer
If it must happen every time, it is a hook. If it needs judgement about when and how, it is a skill. Trying to guarantee behaviour with instructions is the most common configuration mistake in Claude Code.
Can you use both? Yes, and the strongest setups use both — a skill for how to do the work, a hook to guarantee the check afterwards.
Side by side
Option A
Hooks
Shell commands that run at defined points in Claude Code's execution — before a tool call, after a file edit. Deterministic and able to block.
Pick it when
Enforcement. Formatting after every edit, linting before a commit, blocking writes to protected paths, logging for audit.
Option B
Agent Skills
Folders of instructions, scripts and resources, loaded on demand when relevant. Portable across Claude apps, Claude Code, the API and the Agent SDK.
Pick it when
Capability. A workflow, a house style, a review checklist — anything where knowing when to apply it is part of the job.
Guaranteed versus probable
| Hooks | Skills | |
|---|---|---|
| Triggered by | An event in Claude Code | The model judging relevance |
| Guaranteed | Yes | No |
| Can block | Yes | No |
| Written as | Shell commands | Instructions, scripts, resources |
| Runs in | Claude Code, Agent SDK | Claude apps, Code, API, SDK |
| Failure mode | The command fails, loudly | It quietly does not apply |
“Guaranteed” is the entire distinction. Everything else follows.
The mistake this comparison exists to prevent
Someone writes in CLAUDE.md: always run the formatter after editing a file.
It works. Mostly. Then one day, in a long session with a lot of context, it does not — and a badly-formatted file lands in a pull request. The instruction was never a guarantee; it was a strong suggestion to a model that was weighing a hundred other things.
A PostToolUse hook running the formatter is not a suggestion. It runs, or it errors.
Rule of thumb: if you would be annoyed to discover it had been skipped, it is a hook.
Where skills are genuinely better
Hooks cannot use judgement. They fire on an event, run a command, and that is all.
Anything requiring “it depends” — how to structure a migration, what a good bug report contains, when a change needs a design doc — is a skill, because the decision about whether and how is part of the task.
Skills are also far more portable: they work in the Claude apps, the API and the Agent SDK, where hooks are Claude Code and SDK only.
Using both
The pattern that holds up:
- A skill describing how your team does database migrations.
- A hook that runs the migration linter before any commit touching
migrations/.
The skill makes the work good. The hook makes sure the check happened. Neither substitutes for the other — and note that a hook can also enforce what permissions would have allowed, which is the usual way to protect specific paths.
Common misconceptions
- "I put it in CLAUDE.md so it always happens." Instructions are followed, not executed. If it must happen, it is a hook.
- "Hooks and skills are alternatives." They operate at different layers. A skill describes work; a hook constrains the environment the work happens in.
- "Hooks are sandboxed." A hook is a shell command with your privileges — including a hook installed by a plugin someone else wrote.
Sources
- 01Automate actions with hooks — Claude Code docsOfficialcode.claude.com
- 02Agent Skills announcementOfficialclaude.com