Claude Code will build you a skill, a subagent or a hook if you simply ask, so the hard part is choosing the right mechanism, not building it. The names don’t help much: “skill” sounds like a talent, “subagent” like a junior spy, and “hook” like something from a tackle box. The choice comes down to two things the name doesn’t show – who starts the mechanism and how much room it takes up in your conversation. Here is when each of them earns its place.
Two questions instead of three names
The first question when choosing between a skill, a subagent and a hook is: who should start the mechanism? You start a skill yourself by typing a slash and its name, or Claude Code starts it on its own when it decides the skill’s description fits the task. A subagent is usually called by Claude Code itself while it works, although you can also name it directly. A hook needs neither you nor Claude Code: it runs by itself on the event it was attached to.
The second question is: how much room will the mechanism take up in the context, meaning everything Claude Code has in front of it in the current conversation? According to the documentation, when the context fills up with too much information, Claude starts skipping your rules or fails to reach for the right skill.
| Who starts it | What takes up room in the conversation | When it fits | |
|---|---|---|---|
| Skill | you or Claude Code | its description in every conversation, the full content from the moment it runs | a procedure you repeat every so often |
| Subagent | usually Claude Code, but you can also name it directly | its description in every conversation, plus the result – the subagent does the work itself in a separate context | a task that means reading a lot when a short result is enough |
| Hook | nobody – it runs by itself on an event, for example when you send a message or the AI agent finishes its work | nothing, unless the hook passes something into the conversation | something that should happen every time, the same way |
First check whether one rule in CLAUDE.md is enough
Claude Code reads the CLAUDE.md file in full at the start of every conversation, so whatever it holds always takes up room. CLAUDE.md is the place for short rules that apply in every conversation: the date format, the language of replies, a ban on touching a particular folder without asking. A skill would be overkill for things like that. How to decide whether a rule belongs in CLAUDE.md is covered in our Tip on instructions in the chat and in a file. It comes down to one question: tomorrow, working on something else, will you type the same thing again?
The line between a rule in CLAUDE.md and a skill runs where the rule turns into a procedure. The Claude Code documentation suggests that by the third time you paste the same list of steps into the chat, it’s time to save it as a skill.
A repeatable procedure you run on demand: skill
A skill is a saved procedure you reach for every so often – for example when, once a month, you put together a spreadsheet of costs for your accountant from the invoices in one folder. It’s the same few steps every time, but you only need them once a month. That’s why a skill takes up little room in the conversation: at the start, Claude Code sees only its name and the short description at the top of the file, loads the full content only once the skill runs, and keeps it in the conversation from then on.
You don’t write the skill file by hand – you ask Claude Code for it, ideally at the end of a conversation in which the task has just gone well. A skill is still an instruction, though: Claude Code interprets its steps, so the result can come out a little different each time.
Besides your own skills, you can use the ones built into Claude Code, the ones that come with plugins, and the ones from your claude.ai account. They all work the same way. Custom commands from the commands folder, which you may come across in older guides, are skills today too, just stored in the old folder.
The lesson on your first skill shows how to ask Claude Code for your first skill and how a global skill differs from a local one.
A heavy task that clogs up the conversation: subagent
A subagent is useful when a lot of files need reading and a short summary is all you need. Say you have a few dozen proposals sent out over the past year and want one table of the services, the amounts and which proposals were accepted. If the AI agent read those proposals in the main conversation, their content would stay in the context, even though the table is all you need for the rest of the work. A subagent reads everything in its own context and passes only the summary back into the conversation.
In practice, a subagent is a separate AI that Claude Code starts for a single task. It doesn’t see your conversation: it starts from scratch, with its own instructions and the CLAUDE.md file, and knows only as much about the task as Claude Code writes in its brief. When it’s done, it hands Claude Code only the result, without everything it read and checked along the way. Every time it runs again, the subagent starts from scratch and doesn’t remember its previous brief. The exception is when you ask Claude Code to continue the work of the same subagent – then the subagent comes back with its whole earlier history. That’s why a subagent copes well with a task you can describe in a few sentences, and less well with one that requires knowing your whole conversation.
You don’t write the subagent file by hand either – you describe to Claude Code what the subagent should take care of and what result it should hand back, and Claude Code prepares the file. Claude Code also has a few built-in subagents it starts without your involvement, for example to search through files quickly.
A subagent saves room in the conversation, but it doesn’t make your Claude plan’s usage limit last any longer. Its requests count towards the same limit as the requests in the main conversation.
The lesson “Skill and subagent – splitting the work” shows which model to choose for a subagent and how to hand it part of the task a skill performs.
Something that should always happen, without anyone remembering it: hook
A hook is a mechanism for more advanced users – if you’re still getting used to skills, you can skip this part and come back to it later. Hooks are attached to events while Claude Code works, such as the start of a session, you sending a message, the AI agent finishing its work, or the moment just before a file is changed. Every time such an event happens, Claude Code runs the hook attached to it. A hook is usually a script, a command for the computer that runs without any AI involved. That’s why it uses no tokens, even if it runs with every message you send.
A hook differs from a rule written in CLAUDE.md in that it doesn’t depend on whether the AI remembers the rule. The sentence “don’t change anything in the folder with signed contracts” in CLAUDE.md is a request that Claude Code usually sticks to. A hook blocking such a change runs every time Claude Code reaches for its file-editing tool, whatever the AI has in its context at that moment – the documentation puts it plainly: an instruction is a request, a hook enforces the rule. A hook reacts only to the event it was attached to, though: if Claude Code changes the file with a command in the terminal, a hook attached to the file-editing tool won’t catch that change. And since a hook works outside the conversation, it takes up no room in it, unless the hook itself adds something to it.
A hook is hard to write by hand: it’s an entry in a settings file, often with a command tailored to your system, and one stray comma is enough to stop it working. All the more reason to ask Claude Code for it. In our workshops, the first two hooks we show are these: one adds the current date and time to every message you send, so the AI always knows what time it is, and the other plays a short sound when the AI agent finishes its work.
A hook runs with your permissions and without asking, so only ask for hooks whose behaviour you understand. Some hooks also come bundled with plugins.
In short
Before you ask Claude Code for a new mechanism, answer two questions: who should start it, and how much room should it take up in the conversation? A single sentence that should always apply goes into CLAUDE.md. A procedure of a few steps that you reach for every so often is a skill. When a lot needs reading and a short result is enough, hand it to a subagent. And if something should happen every time a specific event occurs, without anyone having to remember it, set up a hook.