CLAUDE.md, skills, hooks and agents: what goes where?

Home → Knowledgebase → CLAUDE.md, skills, hooks and agents: what goes where?

How long is your CLAUDE.md by now? And how many of those rules does Claude Code still actually follow?

Claude Code offers several options and levels for recording rules and instructions. But how do you set this up so that it works effectively and reliably? Perhaps you have a lot in your CLAUDE.md right now and you are discovering skills. Perhaps you are already a bit further along. Still, the question remains: what goes where? In this article I go through the places where you can put instructions, and how and when Claude Code uses them.

Why does this matter so much?

A good setup helps Claude get to the right place in the code faster and do the right things there. Because there is less searching and guessing, the process takes less time and less context. Without targeted instructions, Claude often needs quite a few grep and read actions to find the right files. Your setup also lets you enforce that certain scripts or actions are run. That is reason enough to take another critical look at your setup.

The five options

There are five ways to give Claude instructions or to enforce things. They are:

1. CLAUDE.md
2. Rules
3. Skills
4. Hooks
5. Agents / mods

The best known is CLAUDE.md, the file that is loaded at the start of every session. Skills are instructions that are loaded based on their description. Until then, their content is unknown. Hooks respond to events, and agents are useful for specific tasks.

Rules are less well known. They were introduced as an addition to CLAUDE.md. In .claude/rules you can freely create Markdown files, in your own folder structure. This lets you split instructions by topic, and larger teams can manage them separately.

A rule can also be set up so that it is only loaded for a certain folder, file name or file extension. To do this, you put the YAML key paths: at the top of the rule with a pattern, for example src/api/** or **/*.dfm. The rule is then only loaded once Claude reads a file that matches that pattern. Without this paths key, however, the files work exactly the same as CLAUDE.md.

Mods are also new (since October 2026). I group them with hooks here, because that is what they resemble most. The big difference is that a mod embeds itself in the Claude software, so to speak. A mod also has more possibilities than a hook. A separate article about this will follow.

When to use which option

Four questions quickly tell you which option suits your goal best. They are the following:

1. Is the information or instruction always needed?

This is your first question, and think about it carefully. Maybe the instruction is always needed when coding, but not at all when analysing or investigating. Maybe it only applies to certain file types or to certain modules in the application.

You can have the following answers to this question:

1. Yes, it is always needed, without exception: then the central CLAUDE.md (or rules without a paths restriction) in your project is a fine place. These instructions are always loaded and are taken into account in every situation. Because this happens in every session, you want to keep CLAUDE.md and the rules as compact as possible.
2. Yes, always when work is done in a certain folder: you can then choose a CLAUDE.md in that folder. Claude loads this file when files in that folder are read. This location has the advantage that the instructions sit close to the code they are about. Another advantage is that they are always loaded when someone runs Claude directly from that folder. Instead of a CLAUDE.md, you can also choose rules with a paths key if you prefer to keep the instructions together in one place.
3. No, not always, but mainly in specific circumstances: for example, when there is a specific process, such as building or releasing software. Or when specific knowledge is needed for one part of the software. If you can think of a scenario in which a specific instruction or extra context is useful, a skill, hook or agent is a better candidate than CLAUDE.md or rules.

2. Do you always want the action at a fixed moment?

The question here is whether you can pin what you want to achieve to specific moments in your work process. These are moments that do not depend on Claude’s own reasoning or thinking. For example: every time a certain file is changed, when an agent is started or when a session begins. In other words, can this moment be linked to one of the events available for a Claude hook?

And you can do more with these events than it may seem at first sight. In a hook you can set up or check various things. For example, there is no event for a git push. However, you can use the PreToolUse event to check whether a Bash command contains a git push.

A hook is the only option that you know for certain will run on the specified event. That is not the case with any of the other options. With those, whether the instruction is carried out, or a skill or agent is applied, still depends on Claude.

At the moment, a hook can carry out five different actions.

1. A shell command: often used to run a script, but an echo to a log file also works.
2. An HTTP request: call a URL or send a request over HTTP.
3. Call an MCP server: use a tool from a specific MCP server.
4. Run a prompt: have something checked or done in plain language.
5. Start an agent: have an agent carry out a specific task.

3. Can Claude recognise for itself when it is needed?

We have already answered whether something must always happen, or at fixed and recognisable moments. The question now is whether situations can arise where it is useful for Claude to see for itself that more information is available, and to read it only at that moment.

A very simple example is coding guidelines. They are not always needed, and they do not fit in CLAUDE.md because you want to keep that compact. They only need to be read and applied when coding.

Another example could be a step-by-step plan for creating a release, or instructions for a commit. Another use is guiding documentation about the code, organised by certain features or topics. For example, when something needs to be done for invoicing. Information can then become available that describes what is in which files and what needs special attention. This is information that does not need to be available in general, but that cannot be linked to fixed moments either.

Skills are extremely well suited to these uses. Each skill has its own description. Claude knows the skills and their descriptions. Based on these, Claude decides to use a skill during a session. If you ask for a commit in your session, the commit skill is triggered. If you want to extend the invoicing, the invoicing skill is triggered automatically. And not only for coding, but also for making plans or investigating something.

When defining a skill, pay attention to the following:

1. Describe when, not what: It is about triggering: when do you want Claude to use this skill? What it contains matters less.
2. Use the right words: Use the words you use yourself in your chats.
3. Refer to locations or files: Include concrete references to locations or files where Claude can find things.
4. Be creative, use all the options: Skills can also contain scripts and run them. Or trigger the reading of documentation. You can have a shell command run and include its output in the skill. A skill can run on a different model, start agents and much more.
5. Can also be used manually: By default, a skill can also be started manually with the / command. With disable-model-invocation: true you prevent the model from starting the skill by itself.

4. Do you only need the result, not the way to get there?

When you work in a Claude session, the whole context is often important. The steps taken in the session, including those by the model, enrich the context and help to reach the right result. Sometimes, however, that is not the case. Then the extra context only leads to clutter, or it is simply not relevant. In such cases you use an agent, either yourself or automatically through its description.

Take the build process, for example. For the main session, the only things that matter are whether it succeeded and what the hints and warnings are. Or say you want to know in which files a certain term is used. All the grep commands are not very relevant; only the list of files and line numbers is.

An agent can also be used to work in parallel, or because you want to use a different model. For example, Haiku for simple searches.

When defining an agent, pay attention to the following:

1. Describe when, just like with a skill: Claude decides, based on the description, whether to start the agent. Describe the situation in which the agent should be used.
2. Give only the tools it needs: In the definition of an agent you can specify which tools may and may not be used. This sets a firmer limit than an instruction alone can.
3. Define the output: The result of the agent is the only thing that comes back to your main session. Write down explicitly what it should look like.
4. The agent knows nothing: An agent does not know your conversation, nor the agreements you made along the way. In the agent definition you can also specify which skills must be loaded when the agent starts.
5. Choose the model deliberately: With the model key in the agent definition you can specify which model you want to use.
6. One agent, one task: Agents pay off most and work best when they carry out a focused task.

An agent is not always the best choice. It starts without the knowledge from your conversation, and in total it uses more tokens than if you do the work yourself in your session. So keep work that needs a lot of back and forth or shared context in your own session.

More about the context

What matters is when something is loaded into the context or activated. The image below summarises this.

For CLAUDE.md, there are several places where you can have one. Note: they are not loaded instead of each other, but alongside each other. Organisation, user and project load at the start, and a nested CLAUDE.md loads as soon as Claude reads in that folder. If they contradict each other, you do not know which instruction Claude will follow. So avoid conflicting instructions.

Organising all these options

If you work with several people in a team or company, it is good to think about how to organise the various CLAUDE.md files, skills, hooks and all the other options.

One thing you can use is your own marketplace with your own plugins. Plugins can contain skills, hooks and agents. You can connect a marketplace to Claude Code locally through a local folder, or directly to a git repository. If it is in a git repo, you can also set up the marketplace in your organisation so that it is automatically available in Cowork (both the desktop and the web version).

This way you can share things that apply across all projects. Coding guidelines are a good example. Unfortunately, one thing cannot be done through a plugin (yet): CLAUDE.md and rules.

Maintaining your instructions, skills, hooks and agents

Regularly ask Claude to reflect at the end of a session. Where did instructions get in the way, where were they missing, did the agent do its job correctly, and what can be optimised?

Maintenance, both adding and removing, does not happen by itself. Keep an eye on whether the options still work well. Be alert to your own behaviour. If you often type the same instruction, it may be time for a skill.

Above all, ask Claude itself to come up with proposals and to work them out. This often gives good results. Also share insights with colleagues, and inspire each other to keep improving the way you work with Claude.