Een SKILL.md-bestand is het hart van elke Claude Skill — een Markdown-bestand dat begint met een korte YAML-header (een naam en een beschrijving) en gevolgd wordt door de instructies die Claude moet volgen. De beschrijving vertelt Claude wanneer de skill gebruikt moet worden; de inhoud vertelt hoe.
Als je de term hebt gezien en je afvroeg wat er eigenlijk in zit, hier is de opbouw van een SKILL.md, waarom elk deel belangrijk is, en hoe je er een schrijft die werkt.
Wat SKILL.md is
Een Claude Skill is een map, en SKILL.md is het verplichte bestand in de hoofdmap. Het is gewone Markdown, dus het opent in elke teksteditor. Claude leest het om een vaardigheid te leren — de stappen, regels en best practices voor één soort taak. Optionele extra’s (templates, scripts, referentiebestanden) kunnen ernaast in dezelfde map staan, maar het SKILL.md is het enige bestand dat elke skill moet hebben.
De twee delen van een SKILL.md
1. De frontmatter (metadata)
Bovenaan staat een klein YAML-blok tussen --- markeringen. Het bevat de essentiële metadata — minimaal een naam en een beschrijving:
---
name: weekly-report
description: Formatteert ruwe notities naar ons standaard wekelijkse rapport. Gebruik wanneer de gebruiker vraagt om een wekelijkse update, statusrapport, of om "de week op te schrijven."
---Dit blok is speciaal: wanneer een sessie start, laadt Claude alleen de naam en beschrijving van elke geïnstalleerde skill — niet het hele bestand. Dat houdt het contextvenster licht en is waarom de beschrijving zo belangrijk is.
2. De inhoud (instructies)
Onder de frontmatter, in gewone Markdown, schrijf je wat Claude daadwerkelijk moet doen — bij voorkeur als duidelijke, genummerde stappen met regels of voorbeelden:
## Stappen
1. Groepeer de notities onder Wins, In Progress en Blockers.
2. Houd elke opsomming tot één zin, verleden tijd.
3. Eindig met een één-regelige "Volgende week" samenvatting.
4. Bedenk nooit statistieken die niet in de notities staan.Waarom de beschrijving de belangrijkste regel is
Het activeren hangt volledig af van de beschrijving. Terwijl je werkt, vergelijkt Claude je verzoek met de beschrijving van elke skill en laadt het volledige bestand alleen als het overeenkomt. Een vage beschrijving ("helpt met rapporten") wordt zelden geactiveerd. Een specifieke ("gebruik wanneer de gebruiker vraagt om een wekelijkse update of statusrapport") werkt betrouwbaar. Als je één regel onthoudt, laat het deze zijn: schrijf de beschrijving voor wanneer de skill gebruikt moet worden, niet alleen wat het is.
Hoe Claude het bestand gebruikt
- Bij opstarten: Claude leest de naam + beschrijving van elke skill.
-
Tijdens de taak: als je verzoek overeenkomt met een beschrijving, laadt Claude het volledige
SKILL.mdvan die skill (en eventuele bijbehorende bestanden). - Vervolgens: Claude volgt de instructies in de inhoud om het werk te voltooien.
Deze "laad het alleen wanneer nodig" aanpak heet progressive disclosure, en zo kun je veel skills geïnstalleerd houden zonder het contextvenster te overladen.
Een goede SKILL.md schrijven
- Schrijf een duidelijke beschrijving. Geef helder aan wanneer de skill geactiveerd moet worden.
- Houd de eerste versie klein. Vijf tot tien regels duidelijke stappen zijn beter dan een uitgebreid document.
- Wees concreet. Genummerde stappen, expliciete regels, een kort voorbeeld.
- Test met echte taken. Breid alleen uit als Claude iets mist.
Moet je er zelf een schrijven?
Nee. Zelf schrijven is ideaal voor workflows die uniek voor jou zijn, maar als je alleen het resultaat wilt, worden kant-en-klare skills geleverd met hun SKILL.md al gemaakt en getest. Blader door de KissMySkills bibliotheek met 300+ skills, prompt packs en agents, of de Claude Code skills collectie. Wil je er eerst één in actie zien? Probeer een gratis generator of pak een gratis skill.
Veelgestelde vragen
Is SKILL.md gewoon Markdown?
Ja — het is een standaard Markdown-bestand met een YAML frontmatter-blok bovenaan. Het opent in elke teksteditor, geen speciale software nodig.
Wat is vereist in een SKILL.md?
Minimaal een frontmatter-blok met een naam en een beschrijving. De inhoud met instructies maakt de skill nuttig, maar de metadata maakt het vindbaar en activeerbaar.
Waar komt het SKILL.md-bestand te staan?
In de hoofdmap van de skill. In Claude Code staan skills in ~/.claude/skills/<naam>/ voor persoonlijk gebruik of .claude/skills/<naam>/ binnen een project, met het SKILL.md in de hoofdmap.
Kan ik de inhoud van een SKILL.md gebruiken in ChatGPT of Gemini?
Ja. De instructies zijn draagbaar — plak de inhoud in de aangepaste instructies van ChatGPT of Gemini voor hetzelfde gedrag. Automatisch activeren via frontmatter is een Claude-functie.
Begin met een werkend voorbeeld
De snelste manier om SKILL.md te begrijpen is door een goede te lezen. Pak een gratis skill, open het bestand en zie de frontmatter-plus-stappen structuur in actie — en lees daarna hoe je het installeert in drie minuten.