Een Claude Skill is een map met een bestand SKILL.md: bovenaan een naam en een korte beschrijving, daaronder de instructies, en eventueel scripts en naslagbestanden ernaast. Claude ziet van elke skill eerst alleen die naam en beschrijving. Pas als je vraag daarbij past, leest het de rest. Een perfecte skill begint dus bij één zin: de beschrijving die zegt wat de skill doet en wanneer Claude hem moet gebruiken. Daarna houd je SKILL.md kort, zet je details in aparte bestanden en test je of Claude hem echt kiest.

Deze gids is bijgewerkt in oktober 2026. Sinds de eerste versie van februari werken skills in elk Claude-abonnement, ook het gratis, zijn ze sinds 19 augustus 2026 uit bèta op de API en kan je ze testen met evals. Hieronder lees je hoe je er een bouwt die werkt, en hoe je weet dat hij werkt.

Wat is een Claude Skill precies?

Een skill is vastgelegde werkwijze. In plaats van in elk gesprek opnieuw uit te leggen hoe je een offerte opmaakt, een tekst nakijkt of een release voorbereidt, schrijf je dat één keer op. Claude laadt die kennis wanneer ze nodig is. Anthropic beschrijft het als het verschil tussen een prompt, die één taak stuurt, en een map die Claude op verzoek opent (Agent Skills overview).

Zo ziet een skill eruit:

  • SKILL.md (verplicht): YAML-frontmatter met minstens name en description, daarna de instructies in Markdown.
  • scripts/ (optioneel): code die Claude uitvoert, bijvoorbeeld een validatie of een conversie. Alleen de uitvoer komt in de context.
  • references/ (optioneel): naslag die Claude pas leest als een stap erom vraagt.
  • assets/ (optioneel): sjablonen, logo’s, voorbeeldbestanden.

Het formaat is een open standaard. Anthropic publiceerde het in december 2025 op agentskills.io, en intussen lezen ook Codex en ChatGPT hetzelfde SKILL.md-formaat, uit een map .agents/skills (documentatie van OpenAI). In Claude Code zijn de oude slash commands opgegaan in skills: .claude/commands/deploy.md en .claude/skills/deploy/SKILL.md geven allebei /deploy, maar alleen de skill kan bestanden meenemen en zelf door Claude gekozen worden.

Hoe Claude een skill kiest en laadt

Skills laden in drie lagen. Dat heet progressive disclosure, en het verklaart bijna elke ontwerpkeuze verderop.

  1. Naam en beschrijving staan altijd in de context, zo’n 100 tokens per skill. Daarmee beslist Claude of een skill past.
  2. De body van SKILL.md komt erbij zodra de skill gekozen wordt. Anthropic mikt op minder dan 5.000 tokens.
  3. Scripts en naslagbestanden kosten niets tot Claude ze opent of uitvoert.
Animatie: Claude leest van vijf skills alleen het etiket, kiest er één en opent daarna SKILL.md en pas later een naslagbestand
Je kan tientallen skills installeren, omdat Claude er tot het laatste moment alleen de beschrijving van leest. Tokenaantallen volgens de Agent Skills overview van Anthropic.

Het gevolg: een instructie die alleen in de body staat, helpt niet om de skill gekozen te krijgen. “Gebruik deze skill bij het nalezen van blogteksten” hoort in de beschrijving, niet onderaan in SKILL.md.

De beschrijving beslist of je skill ooit gebruikt wordt

De meeste skills die niet werken, falen hier. De beschrijving is geen samenvatting voor mensen. Het is het enige wat Claude ziet als het moet kiezen tussen al je skills. Volgens de best practices van Anthropic moet ze twee dingen zeggen: wat de skill doet, en wanneer Claude hem gebruikt.

  • Schrijf in de derde persoon. De beschrijving komt in de system prompt terecht. “Leest blogteksten na” werkt, “Ik help je met teksten” niet.
  • Gebruik de woorden die mensen zelf typen. Zeggen collega’s “nalezen”, “redigeren” of “klaarmaken voor publicatie”, zet die woorden erin.
  • Zet de belangrijkste toepassing vooraan. Claude Code kapt beschrijving en when_to_use samen af op 1.536 tekens in de lijst van skills. De standaard zelf laat maximaal 1.024 tekens toe.
  • Wees specifiek. “Helpt met documenten” of “utils” verliest van elke andere skill. “Vult PDF-formulieren in en voegt PDF’s samen. Gebruik bij PDF’s, formulieren of documentextractie” wint.
  • Voeg pas een uitsluiting toe als een test erom vraagt. “Niet voor vertalingen” zet je er alleen bij als de skill echt bij vertalingen opduikt.

Er is nog een reden om kort en scherp te blijven. Claude Code reserveert voor de lijst van alle skills een budget van 1 % van het contextvenster. Heb je veel skills, dan vallen er beschrijvingen weg, en daarmee de woorden waarop Claude moest matchen (documentatie van Claude Code).

Voor de naam gelden harde regels: hooguit 64 tekens, alleen kleine letters, cijfers en koppeltekens, en de woorden “claude” en “anthropic” zijn verboden. Anthropic raadt een werkwoordsvorm aan zoals processing-pdfs. Vermijd namen als helper, tools of data.

Een goede SKILL.md, uitgewerkt

Hieronder een volledige skill die blogteksten naleest. Ze is bewust kort: Claude kent spelling al, de skill vertelt alleen wat Claude niet weet.

---
name: blog-nalezer
description: Leest Nederlandstalige blogteksten na op spelling, huisstijl en leesbaarheid. Gebruik wanneer de gebruiker vraagt een tekst na te lezen, te redigeren, te verbeteren of klaar te maken voor publicatie.
---

# Blogtekst nalezen

## Werkwijze
1. Lees de hele tekst één keer zonder iets te wijzigen.
2. Pas de regels uit references/huisstijl.md toe.
3. Corrigeer taal en stijl. Herschrijf de inhoud niet.
4. Geef de gecorrigeerde tekst, daarna een lijst van elke wijziging met de reden.

## Grenzen
- Feiten en cijfers wijzig je nooit. Twijfel je, zet er [CHECK] bij.
- Koppen krijgen geen hoofdletter per woord.

## Voorbeeld
Invoer: kop "Zo Maak Je Een Goede Prompt"
Uitvoer: kop "Zo maak je een goede prompt"
Wijziging: geen hoofdletter per woord in een Nederlandse kop.
Geannoteerde SKILL.md met frontmatter, werkwijze, grenzen, voorbeeld en een verwijzing naar een naslagbestand
Wat in de frontmatter staat, ziet Claude altijd. Wat eronder staat, pas na de keuze. De naslag in references/ alleen als stap 2 erom vraagt.

Wat deze skill goed doet, en wat je overneemt voor je eigen skills:

Stappen in plaats van wensen

“Schrijf goede teksten” geeft Claude niets. Een genummerde werkwijze met een duidelijke volgorde wel. Bij lange taken mag je een checklist meegeven die Claude kopieert en afvinkt.

Kies hoeveel vrijheid Claude krijgt

Anthropic spreekt van een smalle brug of een open veld. Een code review of een redactie mag ruime richtlijnen hebben. Een database-migratie of een factuurexport vraagt een vast script met een vast commando, met de zin “pas dit commando niet aan”.

Voorbeelden zeggen meer dan regels

Eén paar invoer en uitvoer toont het formaat beter dan drie alinea’s uitleg. Voor taken met een vaste vorm, zoals commitberichten of rapporten, geef je een sjabloon en zeg je of het strikt of flexibel is.

Houd SKILL.md onder 500 regels

Wat langer is, splits je op in bestanden waar SKILL.md rechtstreeks naar verwijst. Eén niveau diep: als bestand A naar B verwijst en B naar C, leest Claude C vaak maar half. Naslagbestanden van meer dan 100 regels krijgen bovenaan een inhoudstafel.

Laat scripts het foutgevoelige werk doen

Een script is betrouwbaarder en goedkoper dan Claude dezelfde code telkens opnieuw te laten schrijven. Zeg duidelijk of Claude het script moet uitvoeren of lezen, vang fouten op in het script zelf en geef getallen een reden. Een time-out van 47 seconden zonder uitleg is wat Anthropic een “voodoo constant” noemt. Gebruik altijd voorwaartse slashes in paden, ook als je op Windows werkt.

Bepaal wie de skill mag starten

In Claude Code regel je met extra velden in de frontmatter hoe en wanneer een skill draait. Die velden horen bij Claude Code, andere tools negeren ze. De belangrijkste (volledige lijst):

Veld Wat het doet Gebruik het voor
disable-model-invocation: true Alleen jij start de skill met /naam Alles met gevolgen: deployen, committen, mails versturen
user-invocable: false Alleen Claude gebruikt de skill, hij staat niet in het menu Achtergrondkennis, zoals de conventies van je codebase
allowed-tools Tools die zonder vraag mogen tijdens die beurt Een vaste reeks commando’s, bijvoorbeeld Bash(npm run build *)
context: fork Voert de skill uit in een eigen subagent Zwaar zoekwerk dat je hoofdgesprek niet mag vullen
paths Laadt de skill alleen bij bijpassende bestanden Regels die enkel voor *.sql of één map gelden
hooks Registreert hooks zodra de skill start Regels die elke keer moeten gelden

Dat laatste is belangrijker dan het lijkt. Een skill is een instructie, geen garantie. Volgt Claude een regel na een paar beurten niet meer, en moet die regel altijd gelden, dan hoort hij in een hook. Na het comprimeren van een lang gesprek houdt Claude Code van elke gebruikte skill alleen de eerste 5.000 tokens bij, dus zet het belangrijkste bovenaan.

Skill, CLAUDE.md, subagent of MCP?

Bijna elke vraag op fora komt neer op deze keuze. Een vuistregel:

Je wil Kies
Feiten die altijd gelden in een project (stack, mappen, conventies) CLAUDE.md
Een werkwijze die Claude alleen bij bepaalde taken nodig heeft Skill
Een regel die zonder uitzondering moet gelden Hook
Een deeltaak in een aparte context, met eigen tools Subagent
Toegang tot een extern systeem of databron MCP-server

Ze vullen elkaar aan. Een skill kan uitleggen hoe je een MCP-tool gebruikt, met de volledige naam zoals GitHub:create_issue. Meer over de andere bouwstenen lees je in onze stukken over subagents in Claude Code, over MCP en over context engineering voor Claude 5.

Waar je skills gebruikt en deelt

Waar Hoe je een skill toevoegt Delen
Claude-app en Cowork Customize > Skills: laat Claude er een maken of upload een zip. Op alle abonnementen, ook Free, met code-uitvoering aan. Alleen op Team en Enterprise: delen met collega’s of publiceren naar de organisatie. Beheerders kunnen skills centraal uitrollen.
Claude Code ~/.claude/skills/ voor jezelf, .claude/skills/ in je project, of via een plugin Via git, een plugin-marketplace of managed settings. Skills uit je Claude-account laden mee vanaf versie 2.1.273.
Claude API Uploaden via /v1/skills en laden in de container-parameter, met de code execution tool. Sinds 19 augustus 2026 zonder beta-header. Voor de hele workspace

Een skill in de app verschijnt niet vanzelf in de API, en omgekeerd: daar upload je hem apart. Bronnen: help center van Claude, aankondiging van skills voor organisaties en de release notes. Werk je vooral in Cowork, lees dan ook onze uitleg over Claude Cowork.

Wie geen zin heeft om van nul te beginnen, vindt voorbeelden in de skills-repository van Anthropic, met onder meer de skills voor Word, Excel, PowerPoint en PDF. In Claude Code installeer je ze met /plugin marketplace add anthropics/skills.

Test je skill voor je hem vertrouwt

“Probeer hem uit en verbeter waar nodig” was het advies in februari. Nu kan het gerichter. Anthropic raadt aan om eerst evaluaties te schrijven en pas dan de skill:

  1. Laat Claude de taak doen zonder skill en noteer waar het misgaat.
  2. Maak minstens drie testgevallen die precies die fouten raken.
  3. Meet het resultaat zonder skill, schrijf dan de kleinste skill die het oplost, en vergelijk.
  4. Test met elk model dat je gebruikt. Haiku heeft soms meer uitleg nodig, Opus juist minder.

De skill-creator doet veel van dat werk sinds maart 2026, in de Claude-app, in Cowork en als plugin voor Claude Code. Hij schrijft testprompts, meet slaagkans, tijd en tokens met en zonder skill, laat twee versies blind tegen elkaar beoordelen en stelt een betere beschrijving voor op basis van prompts die de skill wel en niet zouden moeten starten. Anthropic verbeterde zo de triggering van vijf van zijn zes publieke document-skills.

Test triggering en uitvoering apart. Wordt de skill niet gekozen, dan zit het probleem in de beschrijving. Wordt hij wel gekozen maar is het resultaat matig, dan helpt een andere beschrijving niet en moet de body beter. In Claude Code toont /skills wat geladen is, laat claude --debug fouten in de frontmatter zien en vertelt /skill-doctor welke skills context kosten zonder ooit gebruikt te worden.

Installeer niet zomaar elke skill

Een skill draait met dezelfde rechten als je agent. Hij kan scripts uitvoeren, bestanden lezen en, in Claude Code, het internet op. Dat maakt skills uit onbekende bron een risico. Snyk scande in februari 2026 3.984 skills van ClawHub en skills.sh: 13,4 % had minstens één kritiek beveiligingsprobleem en 76 waren bevestigd kwaadaardig, bijna allemaal met prompt injection (onderzoek van Snyk).

  • Gebruik skills die je zelf schreef of die van een bron komen die je vertrouwt.
  • Lees vóór de installatie alles: SKILL.md, de scripts en elke URL die de skill ophaalt.
  • Wees extra voorzichtig met skills die met API-sleutels, betalingen of klantdata werken.
  • Claude Enterprise kan skills scannen, maar alleen die via de app of Cowork binnenkomen. Wat via de API binnenkomt, valt erbuiten.
  • Skills vallen niet onder zero data retention-afspraken. Houd daar rekening mee bij gevoelige data.

Fouten die we het vaakst zien

  • De trigger staat in de body. Claude leest de body pas na de keuze. Zet het “wanneer” in de beschrijving.
  • Eén skill die alles doet. Componenten maken, testen, documenteren en deployen in één skill geeft een vage beschrijving en een lange body. Splits op.
  • Uitleg die Claude al kent. Elke regel kost tokens zodra de skill draait. Vraag bij elke alinea of Claude ze echt nodig heeft.
  • Te veel keuzes. Geef één standaardaanpak met een uitweg, niet vijf bibliotheken om uit te kiezen.
  • Datums die verouderen. “Vóór augustus gebruik je de oude API” klopt na augustus niet meer. Zet oude werkwijzen in een aparte sectie.
  • Wisselende termen. Kies “veld” of “kolom”, niet allebei.
  • Nooit opnieuw bekeken. Moeten collega’s na elke run hetzelfde corrigeren, dan hoort die correctie in de skill.

Veelgestelde vragen

Zijn Claude Skills gratis?

Ja. Skills werken op alle abonnementen, ook Free, zolang code-uitvoering en het maken van bestanden aan staan. Skills delen met collega’s of publiceren naar je organisatie kan alleen op Team en Enterprise.

Wat is het verschil tussen een skill en een project of CLAUDE.md?

Projectinstructies en CLAUDE.md laden altijd. Een skill laadt alleen als de taak erom vraagt. Wat altijd moet gelden, zet je dus in CLAUDE.md of je project, een werkwijze voor specifieke taken in een skill.

Werkt mijn Claude Skill ook in ChatGPT of Codex?

Grotendeels. Naam, beschrijving, instructies en bijgevoegde bestanden volgen de open standaard en werken ook in Codex en ChatGPT. Velden die alleen Claude Code kent, zoals context: fork of allowed-tools, werken daar niet.

Hoeveel skills kan ik installeren?

Er is geen vast maximum, maar elke skill kost zo’n 100 tokens zodra een gesprek start. In Claude Code gaan beschrijvingen verloren als de lijst te lang wordt voor het budget. Ruim skills op die je niet gebruikt.

Hoe weet ik of Claude mijn skill gebruikt?

Het zekerst meet je dat met de skill-creator: die test bij welke prompts je skill start en bij welke niet. In Claude Code vraag je “What skills are available?”, gebruik je /skills of start je een skill zelf met /naam.

De beste skill durf je ook te schrappen

Bewaar je testgevallen, ook als de skill af is. Elk nieuw model dat uitkomt, laat je ze opnieuw draaien. Gaat het slechter, dan weet je het voor je collega’s het merken. Haalt het nieuwe model je tests ook zonder skill, dan heeft die skill zijn werk gedaan en mag hij weg. Zo blijft je verzameling klein, scherp en goedkoop, en houdt de lijst die Claude bij elke vraag leest alleen wat er echt toe doet. Dat is ook waarom je eigen context meer waard is dan het model dat je huurt: de skills en tests zijn van jou, het model wissel je.