Hooks intercept. Skills package judgment.

Okay, confession first: I spent about a month thinking hooks and skills were basically the same thing with different names, and in that month I broke my team's agent twice. Both times I reached for the wrong primitive. I wrote a skill to stop the agent from doing something dangerous, when what I actually needed was a hook. It failed exactly the way you would expect, which is to say silently, on a Friday.

A hand-drawn notebook sketch: a friendly robot wearing a backpack full of cards labeled SKILLS stands next to a tripwire gate labeled HOOK, with margin notes reading 'always learning, always growing' and 'not every hook is for you, and that's okay'. — How I keep it straight now: the robot carries **skills** it can choose to pull out, and walks through **hooks** that fire whether it wants them to or not. The rest of this post is just that picture, explained.

If you are newer to this and the words "hook" and "skill" make you nod along while quietly panicking, hi, that was me. The docs define each one fine on its own. What took me ages to find was the one sentence that makes them click, so let me put it up top and then earn it: a skill teaches your agent how to do something; a hook decides whether it is allowed to.

Figure 1 · the mental model that fixed my brain

A skill is a card the agent picks up. A hook is a gate it has to pass.

The thing that finally clicked for me: skills are optional and chosen by the agent (it picks the card that fits the job). Hooks are mandatory and fire on their own (the action has to pass the gate whether the agent likes it or not). Once I saw it this way I stopped mixing them up.

SkillsExpertise you hand the agent, loaded only when it is needed

A skill is a folder with a SKILL.md file that says, in plain language, what it is for and when to use it, plus optional scripts or templates. The agent reads the short description, and if the current task matches, it pulls in the full instructions. That "if it matches" part is the clever bit. Anthropic calls it progressive disclosure, and the official description is the clearest I have found:

"Skills are reusable, filesystem-based resources that provide Claude with domain-specific expertise... Unlike prompts, Skills load on-demand." (Anthropic, Agent Skills overview)

Here is a tiny one so it is not abstract. The top part (the "frontmatter") is what the agent skims to decide whether this skill is relevant:

---
name: review-sql
description: Use when reviewing or writing SQL in a pull request
---
# How to review SQL here
- Check for missing WHERE clauses on UPDATE/DELETE
- Prefer explicit column lists over SELECT *
- Flag any query without an index on the join key

What I like, now that I get it: the agent only spends context on this when SQL actually shows up. The rest of the time it is just a one-line description sitting on disk. So you can have a whole shelf of skills and not drown the model, because it grabs the one card it needs. I asked a senior on my team why this matters and she said "context is a budget." For more on that framing, the agent programmer's stack is an interesting read.

HooksGates that fire on their own, whether the agent wants them or not

A hook is different in a way that took me embarrassingly long to feel. You do not ask for a hook; it just happens at a specific moment in the agent's lifecycle, when a session starts, before a tool runs, after a file is edited. You wire it up in a config (often hooks.json) as an event plus a matcher plus a command to run. The way both the Cursor and Claude Code hook docs frame it is the part that landed for me: a hook is the deterministic layer you inject into an otherwise non-deterministic system. The model is fuzzy; the hook is not.

Here is a minimal one that runs a guard script before any shell command the agent tries:

{
  "hooks": {
    "preToolUse": [
      { "matcher": "Shell", "command": "./scripts/guard.sh" }
    ]
  }
}

That guard.sh can check the command and refuse it, for example block anything with rm -rf. The agent does not get a vote. And that is the property I needed back when I tried to keep my agent safe by writing a skill called "please be careful." A skill is advice the agent may or may not follow. A hook is a rule it cannot route around. Guess which one you want standing between your agent and a destructive command.

Figure 2 · same goal, wrong tool vs right tool

"Be safe" is a skill smell. "Block this" is a hook job.

If your sentence has the word "always" or "never" in it, you almost certainly want a hook. If it has "how to" or "the way we like to," that is a skill. This one test would have saved me both outages.

ChoosingA two-question test for when you are stuck

When I am not sure which one I need, I ask myself two questions in order, and they have never let me down yet.

Figure 3 · my actual decision flow

Two questions, four outcomes

That last box matters too, and I learned it second: not every instruction needs to become a hook or a skill. Sometimes a sentence in your prompt is genuinely enough, and reaching for machinery just adds moving parts that can break.

My mistakeYou can also over-hook (ask me how I know)

After the two outages, I overcorrected. I added hooks for everything: pre-edit, post-edit, pre-commit, you name it. Suddenly my agent was crawling, fighting me on edits I actually wanted, and the feedback loop got so slow I stopped wanting to use it. The people who write about this warn about exactly this: hooks are friction by design, and too much friction fights the model instead of guiding it. It is tool-specific, too. What is called a "hook" or "skill" in one stack might be a policy engine or a system prompt somewhere else, so do not assume the words port everywhere.

What I'd tell past me

Start with zero hooks and a couple of skills. Add a hook only the first time something has to be true and you catch the agent getting it wrong. Earn each hook with a real failure. Do not pre-build a cage.

Figure 4 · where they both live

Skills ride along inside the loop; hooks sit on the edges of it

This is the picture I keep in my head now: skills get pulled into the thinking (expertise on demand), and hooks stand at the doors (the session boundaries and the risky actions). If you want the zoomed-out version of where these sit, it's worth taking a look at the six-components breakdown.

Try itA tiny exercise that made it stick

If you learn like I do (by breaking stuff), here is the smallest thing that helped: write one skill and one hook for an agent you already use. Make the skill teach it something specific to your project. Make the hook block one command you never want it to run. Then try to get the agent to do the blocked thing, and watch the hook stop it, while the skill quietly shows up only when relevant. Seeing both fire (and not fire) in real time is what finally moved this from "words I nod at" to "things I understand."

Skills make your agent smarter. Hooks make it safer. You need both, and you need to stop using one to do the other's job.

Thanks for reading all the way down, genuinely. I wrote this because I could not find it when I needed it, and if it saves you even one silent-Friday outage, that is a win. If you have got a clever hook or skill pattern, I would love to hear it. I am still very much learning this in public.

Comments (4)

Join the discussion

Uma YamamotoAwakened5/13/2025

Hooks intercept, skills package judgment is a clean line and I am stealing it. In my n8n brain a hook is the trigger node and a skill is the subworkflow you actually trust to make a call. People conflate them and then wonder why their hook is trying to make decisions it has no business making.

Beatriz EzeAwakened5/14/2025

Thank you, the n8n comparison is what made it land for me, even more than my own article honestly. I was worried this one was too beginner but the trigger vs subworkflow framing is a better way to say it than I managed.

Viktor ZhangAwakened5/14/2025

Rarely post but this is the first time hooks and skills actually clicked. Bookmarked.

Deepa Brooksaura farming5/15/2025

Useful primer. The second edge case point is the real one. Everyone builds the hook for the happy path and then the skill leaks state into it the first time something retries. Would have liked one concrete broken example, but the definitions are right.