Hoe maak je een Claude Code-skill in 2026: een praktische handleiding

Een Claude Code-skill is een map met daarin een SKILL.md-bestand: YAML-frontmatter die Claude vertelt wanneer de skill te gebruiken, en Markdown-instructies voor wat te doen zodra hij afgaat. Dat is het hele model. Om er een te maken, maak je de map aan, schrijf je het tweedelige bestand, en Claude laadt hem óf automatisch wanneer je verzoek bij de beschrijving past, óf je roept hem direct aan met /skill-name. Geen plugin-build, in de meeste gevallen geen herstart. We draaien de volledige contentpijplijn van deze site als één enkele Claude Code-skill, dus de uitleg hieronder heeft dezelfde vorm als wat we in productie gebruiken, geen speelgoedvoorbeeld.

Skills zijn belangrijk omdat ze datgene vervangen wat elke intensieve Claude Code-gebruiker uiteindelijk gaat doen: telkens opnieuw dezelfde checklist of meerstappenprocedure in de chat plakken. Verplaats die procedure één keer naar een skill en het wordt een herbruikbare, versiebeheerde capaciteit die alleen laadt wanneer hij relevant is. Volgens Anthropic's engineering-artikel volgen skills een open standaard die zo is ontworpen dat een agent expertise op aanvraag binnenhaalt, in plaats van die de hele tijd in context mee te dragen.

Wat is een Claude Code-skill?

Een skill is de kleinste eenheid van een herbruikbare procedure in Claude Code. Structureel is het een map met één verplicht bestand, SKILL.md, plus eventuele optionele ondersteunende bestanden. De frontmatter bevat een name en een description; de body bevat de instructies die Claude volgt wanneer de skill draait. Volgens de Claude Code-documentatie wordt de mapnaam het slash-commando dat je typt, en is de beschrijving wat Claude leest om te bepalen of hij de skill automatisch laadt. In 2026 zijn custom commands samengevoegd met skills: een bestand op .claude/commands/deploy.md en een skill op .claude/skills/deploy/SKILL.md creëren beide /deploy en gedragen zich op dezelfde manier, behalve dat de skill-map ook scripts en referentiebestanden kan bundelen. Als je eerder een slash-commando hebt geschreven, ken je al 80% van de skills.

Waar skills leven

Waar je de map plaatst, bepaalt de scope. Er zijn drie niveaus, en de keuze gaat over wie de skill zou moeten zien:

Niveau	Pad	Beschikbaar in
Persoonlijk	~/.claude/skills/<name>/SKILL.md	Al je projecten
Project	.claude/skills/<name>/SKILL.md	Alleen deze repo (commit hem om met het team te delen)
Plugin	<plugin>/skills/<name>/SKILL.md	Overal waar de plugin is ingeschakeld

Als namen botsen, overschrijft persoonlijk het project, en beide overschrijven een gebundelde skill met dezelfde naam, dus een project-code-review-skill vervangt de ingebouwde /code-review. Projectskills laden ook vanuit geneste .claude/skills/-mappen, waardoor een package in een monorepo skills kan meeleveren die alleen gelden wanneer je binnen dat package werkt. Voor een team is projectniveau met een commit naar git bijna altijd de juiste keuze: iedereen krijgt automatisch dezelfde vangrails, op dezelfde manier waarop een gedeeld AGENTS.md-bestand het gedrag van agents over een repo heen standaardiseert.

Hoe je stap voor stap een Claude Code-skill maakt

Hier is de volledige cyclus voor een echte, bruikbare skill die je niet-gecommitte wijzigingen samenvat. Maak eerst de map aan in je persoonlijke skills-map:

mkdir -p ~/.claude/skills/summarize-changes

Sla dit vervolgens op als ~/.claude/skills/summarize-changes/SKILL.md:

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff before committing.
---

Run `git diff` and `git status` to see staged and unstaged changes.
Summarize what changed, grouped by file, in plain language.
Flag anything risky: secrets, deleted tests, large deletions, or config changes.
End with a suggested Conventional Commit message.

Dat is alles. Open een git-project, maak een aanpassing, en vraag óf "wat heb ik veranderd?" (Claude laadt de skill automatisch omdat het verzoek bij de beschrijving past) óf typ /summarize-changes om hem direct uit te voeren. Claude Code houdt skill-mappen in de gaten op wijzigingen, dus aanpassingen onder ~/.claude/skills/ of een project-.claude/skills/ worden binnen de sessie van kracht. Alleen het aanmaken van een gloednieuwe top-level skills-map die bij het opstarten nog niet bestond, vereist een herstart.

Waarom de beschrijving het hele spel is

De allervaakst voorkomende reden dat een skill nooit afgaat, is een zwakke description. Het is geen documentatie, het is de trigger: bij het opstarten laadt Claude alleen de naam en beschrijving van elke skill, en gebruikt vervolgens die tekst om te beslissen wat hij binnenhaalt. Een vage beschrijving als "Dashboard builder" laat Claude gissen. Anthropic's eigen skill-creator adviseert om beschrijvingen bewust "opdringerig" te maken en ze vol te proppen met triggercontexten: schrijf in plaats van "How to build a dashboard" liever "...use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a dashboard." Zet zowel wat de skill doet als elke context waarin hij zou moeten afgaan in de beschrijving. Alle informatie over "wanneer te gebruiken" hoort daar thuis, nooit verstopt in de body. Als je skill niet triggert, repareer dan de beschrijving voordat je iets anders aanraakt.

Progressive disclosure: waarom skills goedkoop blijven

De reden dat een skill een enorme procedure kan bevatten zonder je context op te blazen, is progressive disclosure, een laadmodel met drie niveaus. Niveau 1 is metadata (naam + beschrijving, ~100 woorden) die altijd in context zit. Niveau 2 is de body van SKILL.md, die alleen laadt wanneer de skill triggert. Niveau 3 zijn gebundelde bronnen (scripts, referentiedocumenten, templates) die alleen laden wanneer de body Claude ernaartoe verwijst. Zo kost een skill met een migratiereferentie van 2.000 regels je ongeveer 100 tokens tot het moment dat je hem echt nodig hebt. De praktische regel uit de documentatie: houd de body van SKILL.md onder de 500 regels, en verplaats detail naar aparte bestanden en link ernaar zodra hij daaroverheen groeit.

summarize-changes/
├── SKILL.md          # required: frontmatter + core instructions
└── references/       # optional: loaded only when SKILL.md points here
    └── risk-rules.md

Dit is hetzelfde principe dat MCP-servers composeerbaar houdt: stel capaciteitsmetadata goedkoop beschikbaar, laad het zware detail op aanvraag.

Bepalen wie een skill mag aanroepen

Standaard kunnen jij en Claude beide elke skill aanroepen. Voor alles met bijwerkingen is dat niet wat je wilt, en je moet er niet op vertrouwen dat Claude besluit te deployen omdat de code er "klaar uitziet". Voeg disable-model-invocation: true toe aan de frontmatter en alleen jij kunt de skill triggeren, door zijn slash-commando te typen:

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Gebruik dit voor /commit, /deploy, /send-slack-message en elke onomkeerbare actie. Twee gerelateerde velden geven fijnere controle: allowed-tools somt tools op die de skill mag gebruiken zonder een toestemmingsprompt, en disallowed-tools haalt tools uit de pool zolang de skill actief is (handig voor een achtergrondloop die de gebruiker nooit een vraag zou moeten stellen). Grijp hier bewust naar, niet standaard.

Skill vs CLAUDE.md vs MCP: welke heb je nodig?

Deze drie overlappen genoeg om mensen in de war te brengen, dus hier is de verdeling:

Aanpak	Laadt	Het best voor
CLAUDE.md	Altijd in context	Korte, altijd-ware feiten over de repo
Skill	Op aanvraag, wanneer relevant	Herhaalbare procedures en checklists
MCP-server	Toolschema's, op aanvraag	Verbinden met externe systemen en data

Het kenmerk van een skill is een procedure: als een sectie van je CLAUDE.md is uitgegroeid van een feit tot een meerstappenhandleiding, wil het een skill worden, waar het niets kost totdat het wordt gebruikt. Een feit blijft in CLAUDE.md. Een live verbinding met Jira of een database is een MCP-server. Veel echte opstellingen gebruiken alle drie samen, en goed kiezen is onderdeel van diezelfde tooling-geletterdheid die de AI-codeertools die het waard zijn in 2026 onderscheidt.

Veelgestelde vragen

Wat is een SKILL.md-bestand? Het is het enige verplichte bestand in een skill-map. Het heeft YAML-frontmatter (minimaal name en description) tussen ----markeringen, gevolgd door Markdown-instructies die Claude volgt wanneer de skill draait. De mapnaam wordt het /slash-commando, en de beschrijving vertelt Claude wanneer hij de skill uit zichzelf moet laden.

Waar plaats ik een Claude Code-skill? In ~/.claude/skills/<name>/SKILL.md voor een persoonlijke skill die beschikbaar is in al je projecten, of .claude/skills/<name>/SKILL.md voor een projectskill die je commit en met je team deelt. Plugins kunnen ook skills bundelen. Persoonlijke skills overschrijven projectskills met dezelfde naam.

Moet ik Claude Code herstarten nadat ik een skill heb toegevoegd? Meestal niet. Claude Code houdt skill-mappen in de gaten en pikt toegevoegde, aangepaste of verwijderde skills binnen de huidige sessie op. De uitzondering is het aanmaken van een top-level skills-map die niet bestond toen de sessie startte, wat een herstart vereist zodat de nieuwe map in de gaten kan worden gehouden.

Waarom triggert mijn skill niet? Bijna altijd de beschrijving. Claude beslist alleen op basis van naam en beschrijving of hij een skill laadt, dus een vage beschrijving betekent dat hij niet kan zien dat je verzoek een match is. Herschrijf de beschrijving zodat die de exacte taken en frases benoemt die hem zouden moeten triggeren, en wees expliciet dat hij moet afgaan zelfs wanneer de gebruiker het voor de hand liggende sleutelwoord niet gebruikt.

Kan ik voorkomen dat Claude een skill automatisch uitvoert? Ja. Voeg disable-model-invocation: true toe aan de frontmatter. Dan kun alleen jij de skill aanroepen door zijn slash-commando te typen, wat is wat je wilt voor alles met bijwerkingen zoals deployen of een bericht versturen.

Sources

• Claude Code Docs — Extend Claude with skills: de gezaghebbende referentie voor de structuur van SKILL.md, frontmatter-velden, skill-locaties, aanroepcontrole en live wijzigingsdetectie.
• Anthropic Engineering — Equipping agents for the real world with Agent Skills: de ontwerprationale voor skills en de open standaard.
• anthropics/skills — skill-creator SKILL.md: first-party best practices voor het schrijven van beschrijvingen, het structureren van SKILL.md en progressive disclosure.
• Agent Skills open standard: de tooloverstijgende standaard die Claude Code-skills volgen.