Skills, hooks and slash commands

What it isCopy Anchor Link

A skill is a folder with a SKILL.md and optional scripts. The agent sees only its name and description until the task matches, then loads the rest. This keeps context small while making specialized procedures available. A hook is a script the harness runs at a fixed point, such as before a tool call or after a file edit. It is deterministic, so it enforces what a prompt can only request. A slash command is a reusable prompt you trigger by name.

Choosing between themCopy Anchor Link

If the agent should know how to do something when relevant, write a skill. If something must happen every time without exception, such as formatting on save or blocking a commit with secrets in it, write a hook. If you keep typing the same request, make a command. Prompts ask, hooks guarantee.

A worked example: choosingCopy Anchor Link

Goal: always format files after the agent edits them. Not a skill (the agent might forget) and not a command. A hook runs the formatter after every edit, guaranteed. Goal: teach the agent your release checklist, only when someone says "prepare a release". A skill, because it loads only when relevant. Goal: you often type "review the last commit for security issues". Make it a command and run it with one word.

How each one runsCopy Anchor Link

A skill works by loading on demand. At the start, the agent sees a one-line description of each skill. When your request matches, it reads the full file and follows it. The match is a judgment by the model, so a vague description may never trigger, or may trigger at the wrong time.

A hook is different. The harness, not the model, runs it when an event happens, such as "after a file is edited". The model cannot skip it. If a before-the-action hook exits with the code the tool treats as blocking (exit 2 in Claude Code), the harness stops the action and shows the message to the agent. Other error codes usually let the action go ahead, so check your tool's docs.

A command is a saved prompt that you start yourself, so it runs when you type its name and not otherwise.

A second example: choosing wronglyCopy Anchor Link

You want to stop the agent from ever committing a file called secrets.env. You write a skill saying "never commit secrets". This relies on the model remembering and matching. One day it does not load. A hook that checks the staged files before each commit and fails if that file appears is the right tool, because it runs every time. Now the opposite: you want the agent to know your team's review style. A hook cannot teach style. That is a skill.

Trade-offsCopy Anchor Link

Hooks are strict, so a faulty one blocks work: a before-edit check that blocks too often stops the agent from getting anything done. Keep hooks fast and test them by hand. Skills cost little context but need precise descriptions. Too many skills with similar descriptions confuse the choice.

What goes wrongCopy Anchor Link

Skill never triggers: the description does not match how you phrase requests, so rewrite it using your own words. Hook does nothing: the event or the file pattern is wrong, so run the script by hand and check its exit code. Hook slows everything: it does heavy work on every edit, so move that work to a commit-time check.

Try it yourselfCopy Anchor Link

Create a command or skill that does one small job, such as summarising the last commit in three lines.

1. Run it.
2. Change the wording of the description and see whether it still gets picked.

Expect small wording changes to change when a skill triggers.

Common mistakeCopy Anchor Link

Using the prompt for rules that must never break. Prompts ask. Hooks enforce.