CLAUDE.md, skills, hooks en agents: wat zet je waar?

Home → Knowledgebase → CLAUDE.md, skills, hooks en agents: wat zet je waar?

Hoe lang is jouw CLAUDE.md inmiddels? En hoeveel van die regels volgt Claude Code nog echt?

Claude Code kent verschillende mogelijkheden en niveaus om regels en instructies vast te leggen. Maar hoe richt je dat zo in dat het effectief en betrouwbaar werkt? Misschien heb je nu veel in de CLAUDE.md staan en ben je de skills aan het ontdekken. Misschien ben je al wel wat verder. Toch blijft de vraag: wat zet je waar? In deze bijdrage loop ik langs waar je instructies kwijt kunt en hoe en wanneer Claude Code ze gebruikt.

Waarom is dit zo belangrijk?

Een goede inrichting zorgt dat Claude sneller op de juiste plek in de code uitkomt en daar de juiste dingen doet. Door minder te hoeven zoeken en gokken, kost het proces minder tijd en minder context. Zonder gerichte instructies heeft Claude vaak een behoorlijk aantal grep en leesacties nodig om de goede bestanden te vinden. Daarnaast kun je via je inrichting ook afdwingen dat bepaalde scripts of acties worden uitgevoerd. Genoeg reden om je inrichting nog eens kritisch te bekijken.

De vijf opties

Er zijn vijf mogelijkheden waarmee je instructies aan Claude kunt geven of zaken kunt afdwingen. Dat zijn de volgende:

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

Het meest bekend is de CLAUDE.md, het bestand dat aan het begin van iedere sessie geladen wordt. Skills zijn de instructies die geladen worden op basis van hun beschrijving. Tot die tijd is hun inhoud onbekend. Hooks reageren op events en agents zijn bruikbaar voor specifieke taken.

Rules zijn minder bekend. Ze zijn geïntroduceerd als aanvulling op de CLAUDE.md. In .claude/rules maak je vrij Markdown-bestanden aan, in een eigen mappenstructuur. Zo kun je instructies per onderwerp opsplitsen en kunnen grotere teams ze apart beheren.

Een rule kan ook zo ingesteld worden dat deze alleen ingeladen wordt voor een bepaalde map, bestandsnaam of bestandsextensie. Daarvoor zet je bovenin de rule de YAML-key paths: met een patroon, bijvoorbeeld src/api/** of **/*.dfm. De rule wordt dan pas geladen zodra Claude een bestand leest dat aan dat patroon voldoet. Zonder deze paths-key zijn de bestanden qua werking echter volledig gelijk aan de CLAUDE.md.

Nieuw (sinds oktober 2026) zijn ook de mods. Ze staan hier aan hooks gekoppeld, omdat ze daar het meest op lijken. Het grote verschil is wel dat een mod zich als het ware nestelt in de Claude programmatuur. Een mod heeft ook meer mogelijkheden dan een hook. Hierover wordt nog een aparte bijdrage gepubliceerd.

Wanneer gebruik je welke optie

Aan de hand van vier vragen kun je al snel weten welke optie het meest geschikt is voor je doel. Het gaat om de volgende vragen:

1. Is de informatie of instructie altijd nodig?

Dit is je eerste vraag. En denk daar goed over na. Misschien is de instructie wel altijd nodig bij coderen, maar helemaal niet bij analyseren of bij uitzoekwerk. Misschien geldt het alleen voor bepaalde bestandstypes of voor bepaalde modules in de applicatie.

Je kunt de volgende antwoorden op deze vraag hebben:

1. Ja, het is altijd en zonder onderscheid nodig: dan is de centrale CLAUDE.md (of rules zonder paths-beperking) in je project een prima plaats. Deze instructies worden altijd geladen en worden dan in elke situatie meegenomen. Omdat dit elke sessie gebeurt, wil je de CLAUDE.md en de rules zo compact mogelijk houden.
2. Ja, altijd voor het geval er in een bepaalde map gewerkt wordt: Je kunt dan kiezen voor een CLAUDE.md in de betreffende map. Claude laadt dit bestand dan als er bestanden in die map worden gelezen. Deze plek heeft als voordeel dat de instructies dicht bij de code staan waar het over gaat. Een ander voordeel is dat ze altijd geladen worden als iemand Claude direct draait vanuit die map. In plaats van de CLAUDE.md kun je ook kiezen voor rules met een paths-key als je de instructies liever bij elkaar houdt op één plaats.
3. Nee, niet altijd, maar vooral in specifieke omstandigheden: Bijvoorbeeld als er een specifiek proces is, zoals het builden of releasen van software. Of als er specifieke kennis nodig is voor een onderdeel van de software. Is er een scenario te bedenken waarin een specifieke instructie of extra context handig is, dan komt eerder een skill, hook of agent in aanmerking dan een CLAUDE.md of rules.

2. Wil je de actie altijd op een vast moment?

De vraag is hier of je wat je wilt bereiken kunt vastpinnen op specifieke momenten in je werkproces. Momenten die niet afhankelijk zijn van het redeneren of denken van Claude zelf. Bijvoorbeeld: iedere keer als een bepaald bestand gewijzigd wordt, of er een agent opgestart wordt of als een sessie begint. Oftewel, is dit moment te koppelen aan één van de events die beschikbaar zijn voor een Claude hook.

En je kunt meer met deze events dan wellicht op het eerste gezicht lijkt. In een hook kun je namelijk diverse dingen instellen of controleren. Er is bijvoorbeeld geen event voor een git push. Maar je kunt via het PreToolUse-event wel controleren of in een Bash-commando een git push wordt gegeven.

Een hook is de enige optie waarvan je zeker weet dat die op het vastgestelde event uitgevoerd wordt. Dat is met geen van de andere opties het geval. Daar blijft het uitvoeren van de instructie of het toepassen van een skill of agent afhankelijk van Claude.

Via een hook kun je op dit moment vijf verschillende acties uitvoeren.

1. Een shellcommando: vaak gebruikt om een script uit te voeren, maar een echo naar een logbestand kan ook.
2. Een HTTP-request: roep een URL aan of stuur een request via HTTP.
3. Een MCP-server aanroepen: gebruik een tool van een specifieke MCP-server.
4. Een prompt uitvoeren: laat iets in gewone taal controleren of uitvoeren.
5. Een agent starten: laat een agent een specifieke taak uitvoeren.

3. Kan Claude het zelf herkennen als het nodig is?

We hebben de vraag al beantwoord of het altijd moet of op vaste en herkenbare momenten. Nu is de vraag of er situaties kunnen optreden waarbij het handig is dat Claude zelf ziet dat er meer informatie beschikbaar is en het pas op dat moment inleest.

Een heel eenvoudig voorbeeld is coding guidelines. Die zijn niet altijd nodig en passen ook niet in de CLAUDE.md omdat je die graag compact wilt houden. Ze hoeven pas gelezen en toegepast te worden bij coderen.

Een ander voorbeeld kan zijn een stappenplan om een release te maken, of instructies voor een commit. Een toepassing kan ook richtinggevende documentatie over de code zijn aan de hand van bepaalde functionaliteiten of onderwerpen. Bijvoorbeeld in het geval iets voor facturatie gedaan moet worden. Dan kan informatie beschikbaar komen die beschrijft wat in welke bestanden zit en waar specifiek rekening mee gehouden moet worden. Informatie die niet generiek beschikbaar hoeft te zijn, maar ook niet aan vaste momenten te koppelen is.

Voor deze toepassingen zijn de skills uitermate geschikt. Elke skill heeft een eigen description. Claude kent de skills en hun descriptions. Op basis daarvan besluit Claude om een skill tijdens een sessie te gebruiken. Vraag je om een commit in je sessie, dan wordt de commit-skill getriggerd. Wil je de facturatie uitbreiden, dan wordt automatisch de facturatie-skill getriggerd. En niet alleen voor het coderen, ook voor het plannen maken of uitzoeken van iets.

Let bij het definiëren van de skill op het volgende:

1. Beschrijf wanneer, niet wat: Het gaat om de triggering, wanneer wil je dat Claude deze skill gaat gebruiken. Wat de inhoud is, is minder spannend.
2. Juist woordgebruik: Gebruik de woorden die je zelf ook gebruikt in je chats.
3. Verwijs naar locaties of bestanden: Neem concrete verwijzingen op naar locaties of bestanden waar Claude zaken kan vinden.
4. Wees creatief, gebruik alle opties: Skills kunnen ook scripts bevatten en die uitvoeren. Of het lezen van documentatie triggeren. Je kunt een shellcommando laten uitvoeren en de output daarvan meenemen in de skill. Een skill kan op een ander model draaien, agents starten en zoveel meer.
5. Ook handmatig te gebruiken: Standaard is een skill ook handmatig te starten met het /-commando. Met disable-model-invocation: true voorkom je dat het model de skill zelf start.

4. Heb je alleen het resultaat nodig, niet de weg ernaartoe?

Als je werkt in een Claude-sessie is vaak de hele context van belang. De stappen die in de sessie genomen worden, ook door het model, dragen bij aan verrijking van de context en helpen om het juiste resultaat te bereiken. Soms is dat echter niet zo. Dan leidt die extra context alleen tot vervuiling of is hij gewoon niet relevant. In zulke gevallen zet je een agent in, zelf of automatisch via de description.

Denk bijvoorbeeld aan het buildproces. Voor de hoofdsessie is het alleen belangrijk of het wel of niet gelukt is en wat de hints en warnings zijn. Of als je wilt weten in welke bestanden een bepaalde term gebruikt wordt. Alle grep-commando’s zijn niet zo relevant, alleen het lijstje met bestanden en regelnummers.

Een agent kan ook ingezet worden voor parallel werken of omdat je een ander model wilt gebruiken. Bijvoorbeeld Haiku voor eenvoudige zoekacties.

Let bij het definiëren van een agent op het volgende:

1. Beschrijf wanneer, net als bij een skill: Claude besluit op basis van de description of hij de agent gaat starten. Beschrijf de situatie waarin de agent ingezet moet worden.
2. Geef alleen de tools die nodig zijn: In de definitie van een agent kun je vastleggen welke tools wel en niet gebruikt mogen worden. De begrenzing is daarmee sterker dan mogelijk via alleen maar een instructie.
3. Bepaal de output: Het resultaat van de agent komt als enige terug naar je hoofdsessie. Schrijf expliciet voor hoe dat eruitziet.
4. De agent weet niets: Een agent kent je gesprek niet en ook de afspraken die je onderweg hebt gemaakt niet. In de agentdefinitie kun je ook vastleggen welke skills geladen moeten worden bij het starten van de agent.
5. Kies het model bewust: Met de model-key in de definitie van de agent kun je aangeven welk model je wilt gebruiken.
6. Eén agent, één taak: Agents renderen het meest en werken het best als ze een gerichte taak uitvoeren.

Een agent is niet altijd de beste keuze. Hij begint zonder de kennis uit je gesprek en gebruikt in totaal meer tokens dan wanneer je het zelf in je sessie doet. Werk dat veel heen-en-weer of gedeelde context vraagt, houd je daarom in je eigen sessie.

Aanvullend over de context

Belangrijk is wanneer iets in de context geladen of geactiveerd wordt. De afbeelding hieronder vat dat samen.

Voor de CLAUDE.md geldt dat er verschillende plaatsen zijn waar je er één kunt hebben. Let op: ze worden niet in plaats van elkaar geladen, maar naast elkaar. Organisatie, gebruiker en project laden bij de start, een geneste CLAUDE.md zodra Claude in die map leest. Spreken ze elkaar tegen, dan weet je niet welke instructie Claude volgt. Voorkom dus tegenstrijdige instructies.

Organisatie van al deze opties

Als je met meerderen samenwerkt in een team of bedrijf, dan is het goed om na te denken over de organisatie van de verschillende CLAUDE.md-bestanden, skills, hooks en alle andere mogelijkheden.

Eén van de zaken die je kunt inzetten is een eigen marketplace met eigen plugins. Plugins kunnen skills, hooks en agents bevatten. Een marketplace kun je lokaal koppelen aan Claude Code via een lokale map of direct aan een git repository. Heb je het in een git repo dan kun je de marketplace ook in je organisatie instellen zodat deze automatisch beschikbaar is in Cowork (zowel desktop als webversie).

Op deze manier kun je zaken delen die overkoepelend zijn voor alle projecten. Denk bijvoorbeeld aan coding guidelines. Eén ding kan helaas (nog) niet via een plugin: de CLAUDE.md en rules.

Onderhoud van je instructies, skills, hooks en agents

Vraag regelmatig aan het einde van een sessie aan Claude om te reflecteren. Waar zaten instructies in de weg, waar werden ze juist gemist, deed de agent correct zijn werk, wat kan geoptimaliseerd worden.

Onderhoud, zowel in uitbreiding als in beperking, gaat niet vanzelf. Houd in de gaten of opties nog steeds goed werken. Wees alert op je eigen gedrag. Typ je vaak dezelfde instructie, dan is het wellicht tijd voor een skill.

Vraag vooral Claude zelf om te komen met voorstellen en ze uit te werken. Dit levert vaak goede resultaten op. Deel inzichten ook met collega’s en inspireer elkaar om steeds weer het werken met Claude te verbeteren.