Zelf een SKILL.md schrijven: de complete gids
Een skill is een tekstbestand dat een AI-assistent een werkwijze aanleert: wanneer hij in actie komt, welke stappen hij zet, wat hij oplevert en wat hij weigert. Wie er een goed schrijft, hoeft dezelfde instructies nooit meer te typen. Deze gids laat zien hoe je dat doet, van de frontmatter met triggerzinnen tot het weigeringenblok, met als voorbeeldmateriaal de best gelezen skill van deze site.
Wat een skill precies is lees je in wat zijn Claude skills, hoe je er een installeert in Claude skills installeren; dit artikel gaat over het schrijven zelf. En omdat een schrijfgids zonder gereedschap half werk is, staat hieronder een skill die het interview met je voert en de SKILL.md voor je uitschrijft.
- Pak de zip uit in
~/.claude/skills/(of.claude/skills/in je project). - Claude herkent de skill daarna vanzelf zodra je over een eigen skill begint.
- Direct aanroepen kan ook, met
/skill-md-generator.
- Ga naar Customize en dan Skills.
- Upload de zip daar als skill.
- Of plak de inhoud van SKILL.md in de projectinstructies van een Project.
- Open
AGENTS.mdin je repo. - Plak de inhoud van SKILL.md erin, of zet SKILL.md er als los bestand naast en verwijs ernaar vanuit
AGENTS.md. - Codex leest dat bij elke sessie mee.
Waar een SKILL.md uit bestaat
reg. S.001Elke goede skill heeft dezelfde bouw. Hieronder staat die bouw niet als theorie maar als echt bestand: de frontmatter en de kopjes van de AI Offerte Schrijver, de meest complete skill van deze site. De rest van dit artikel loopt deze onderdelen een voor een langs.
Waarom een los bestand werkt waar een lange prompt faalt
Wie vaak hetzelfde soort werk aan een AI-assistent vraagt, merkt na een paar weken hetzelfde: de instructies groeien. Eerst twee zinnen, dan een alinea met huisregels, dan een document dat je bij elk gesprek opnieuw plakt. Dat werkt, tot het niet meer werkt: je vergeet een keer een regel, een collega gebruikt een oudere versie, en niemand weet meer welke variant de goede was. Een skill lost precies dat op. Het is een tekstbestand met een vaste vorm dat je werkwijze op een plek vastlegt, en dat de assistent er zelf bij pakt op het moment dat de taak langskomt.
Dat zelf erbij pakken is het wezenlijke verschil met een prompt
Een assistent laadt niet al je skills tegelijk in; hij leest van elke skill alleen de naam en de description, en beslist op basis daarvan of de rest van het bestand relevant is voor wat jij zojuist vroeg. Pas bij een match wordt de volledige instructie geladen. Daarom kan een verzameling skills groot worden zonder dat gesprekken trager of rommeliger worden, en daarom is de description zo bepalend: een skill met een zwakke description bestaat technisch wel, maar wordt in de praktijk nooit gebruikt.
De vorm is bewust eenvoudig
Een SKILL.md is markdown: platte tekst met kopjes, leesbaar voor mensen en voor modellen, zonder code en zonder installatieprogramma. Bovenaan staat een blokje metadata tussen twee regels met drie streepjes, de frontmatter, en daaronder staat de eigenlijke instructie. Dezelfde opzet werkt in Claude Code, in Claude.ai en in Codex, zoals de drie stappenrijtjes bovenaan deze pagina laten zien. Wil je eerst breder begrijpen wat skills zijn en wat je ermee kunt, lees dan wat zijn Claude skills; op de skillspagina staan er 100 die je gratis kunt downloaden en als voorbeeld kunt openen, gemaakt in ons AI-lab.
De frontmatter: vier velden en één hoofdrol
De frontmatter heeft vier velden, en drie ervan zijn in een minuut klaar. name is de technische naam: kleine letters, koppeltekens in plaats van spaties, en beschrijf de taak in plaats van het gereedschap. Dus offerte-schrijver, niet gpt-helper. Onder die naam roep je de skill ook handmatig aan. version start op 1.0.0 en hoog je op als je het bestand wezenlijk verandert, zodat een team weet wie de nieuwste variant heeft. license is voor skills die je deelt: MIT is de gebruikelijke keuze en betekent dat iedereen de skill mag gebruiken en aanpassen. Alle skills op deze site dragen die licentie.
Het vierde veld is de hoofdrol
De description is niet de samenvatting die je voor een collega zou schrijven, maar het activatiemechanisme: de tekst waarmee het model beslist of jouw skill bij de vraag van dit moment hoort. Schrijf hem daarom in drie lagen. Eerst wat de skill doet en oplevert, in een of twee zinnen. Dan de triggerzinnen: de directe opdrachten die mensen typen, tussen aanhalingstekens, en daarna de spreektaal. Als laatste de grens: waarvoor de skill niet bedoeld is, met het alternatief erbij.
Die tweede laag verdient de meeste aandacht, want daar gaat het meestal mis
Mensen die een probleem hebben, kennen de vakterm vaak niet. Niemand typt "activeer de offerte-methodiek"; mensen typen dat ze niks meer terughoren na het versturen, of dat een klant alleen naar de laatste pagina bladert.
De AI Offerte Schrijver vangt daarom naast opdrachten als "voorstel schrijven" ook verzuchtingen als "ik ben elke keer een halve dag kwijt aan een offerte" en "ik durf mijn tarief niet te noemen". Dat oogt informeel voor een technisch bestand, maar het is de reden dat de skill activeert op momenten dat de gebruiker zelf niet aan een skill dacht. Mik voor een serieuze description op honderd tot tweehonderd woorden; ter vergelijking: die van de offerte-schrijver telt er ruim tweehonderd.
Drie lagen die bepalen of je skill ooit activeert
reg. S.002Een description schrijf je niet in een keer; je bouwt hem op in drie lagen. De voorbeelden hieronder komen letterlijk uit de frontmatter van de AI Offerte Schrijver, zodat je ziet hoe de lagen er in een echt bestand uitzien.
De opbouw: stappen, input en een vast outputformat
Na de frontmatter begint de instructie zelf, en die opent met een alinea die de rol neerzet: wie de skill is en wat hij oplevert, in twee tot vier zinnen, geschreven tegen het model in de jij-vorm.
Daarna volgt het hart van het bestand: wat de skill altijd doet
Dat zijn genummerde stappen in een vaste volgorde, en de kunst is om ze controleerbaar te maken. Niet "analyseer de input grondig", want daar kan niemand op toezien, maar "haal de letterlijke woorden van de klant uit de notities, want die gaan terug het document in". Elke stap moet zo geschreven zijn dat een buitenstaander kan vaststellen of hij is uitgevoerd. Vergelijk het met de acht stappen van de offerte-schrijver of de vaste vraagvolgorde van de 5 Waarom Analist: elk nummer is een handeling, geen intentie.
Direct daarna hoort een verplichte input checklist: wat de skill van de gebruiker nodig heeft voordat hij kan leveren
Notities, een doel, een tarief, een doelgroep, wat het ook is voor jouw taak. De belangrijkste regel daarbij is er een van gedrag: vraag alleen na wat ontbreekt, en stop daarna met vragen. Zonder die regel verandert een behulpzame skill in een verhoor. De Intake Samenvatting skill laat mooi zien hoe kort zo'n checklist kan zijn als de taak scherp is afgebakend.
Het derde vaste onderdeel is het outputformat: de exacte structuur van het antwoord, als genummerde lijst of als kopjesindeling
Dat voelt overdreven voor een taalmodel dat toch wel iets produceert, maar het format is wat twee runs met dezelfde input vergelijkbaar maakt, en het is wat een skill bruikbaar maakt voor een team: iedereen krijgt hetzelfde soort document.
Leg ook vast wat er bovenaan staat, wat afsluit, en waar de kanttekeningen voor de gebruiker terechtkomen
De SWOT-analyse skill levert bijvoorbeeld altijd eerst het raster en daarna pas de interpretatie, zodat je de feiten los van de duiding kunt beoordelen. Schrijfregels over toon en taal horen hier ook: welke aanspreekvorm, welke woorden verboden zijn, en dat er nergens em-dashes staan als je die huisregel hebt.
Weigeringen: het blok dat je skill betrouwbaar maakt
Als er een onderdeel is dat een goede skill scheidt van een middelmatige, dan is het dit. Een taalmodel is gebouwd om af te maken wat het begint: staat er een offerte zonder prijs, dan is de verleiding groot om er een te bedenken die redelijk klinkt. Bij een gedicht is dat een eigenschap, bij een zakelijk document een risico. Het blok wat de skill nooit doet keert dat gedrag expliciet om, en het werkt verrassend goed: een model dat acht keer heeft gelezen wat het niet mag, vult ontbrekende gegevens niet stilletjes in maar markeert ze.
De AI Offerte Schrijver is hierin het voorbeeld dat we zelf steeds terugpakken, met acht nooit-regels die in FIG.03 hieronder op een rij staan
Kijk vooral naar het patroon erachter. De eerste regels gaan over verzinnen: geen bedragen, geen klantnamen, geen referenties, geen garanties die de gebruiker niet zelf heeft aangeleverd. Ontbreekt een gegeven, dan schrijft de skill INVULLEN en laat hij de beslissing bij de mens.
Daarna komen de regels die de kwaliteit van het vak bewaken: geen aanname presenteren als uitspraak van de klant, niet twee vervolgstappen in een document, geen valse urgentie met een verzonnen deadline. En de laatste regel beschermt de methode zelf: nooit een offerte zonder het blok over wat er niet in zit, omdat juist dat blok discussies over meerwerk voorkomt.
Voor je eigen skill geldt dezelfde bouwlogica
Begin met de drie weigeringen die vrijwel elke skill nodig heeft: geen cijfers of bronnen verzinnen, geen garanties geven, ontbrekende gegevens markeren in plaats van invullen. Voeg daarna de grenzen van jouw vak toe: de dingen waarvan jij uit ervaring weet dat ze fout gaan als je ze aan het toeval overlaat. Wie zijn werkgebied kent, herkent deze aanpak van een pre-mortem: bedenk vooraf hoe het mis zou gaan, en zet daar een regel tegen. Daar bestaat overigens ook een skill voor, de Pre-Mortem Analist, die je op je eigen conceptskill kunt loslaten.
Acht keer nee, uit het echte bestand
reg. S.003De acht nooit-regels van de AI Offerte Schrijver, hier samengevat met de reden erbij. Niet om ze over te nemen, wel om het patroon te zien: elke regel dicht een gat waar een model uit zichzelf doorheen zou lopen.
Zet een voorbeeld in de skill zelf
Regels sturen gedrag, maar een voorbeeld stuurt het harder. Een model dat een uitgewerkt voorbeeld ziet van input en gewenste output, imiteert de vorm, de toon en het detailniveau daarvan, vaak preciezer dan het een lijst met regels volgt. Daarom hoort in elke serieuze skill minstens een verkort maar realistisch voorbeeld: een echte situatie, de input zoals een gebruiker die zou aanleveren, en de output zoals de skill hem hoort te maken.
De offerte-schrijver doet dat met een interieurbouwer van vijftien man: ruwe gespreksnotities van drie regels erin, en eruit een verkorte maar complete offerte, inclusief de plekken waar bewust INVULLEN staat omdat de gebruiker het bedrag nog niet had aangeleverd. Dat laatste is een detail om over te nemen: laat je voorbeeld ook de weigeringen demonstreren. Een voorbeeld waarin alles al perfect is ingevuld, leert het model dat er altijd iets ingevuld hoort te staan. Een voorbeeld met een zichtbare open plek leert het model dat een open plek de correcte uitkomst kan zijn.
Houd het voorbeeld verkort, een derde van de echte omvang is genoeg, en kies er een uit je eigen praktijk van vorige week in plaats van een verzonnen ideaalgeval. Echte voorbeelden bevatten de rafels waar het model van leert: een klant die twijfelt, een ontbrekend gegeven, een detail dat niet in het sjabloon past. Hoe zulke voorbeelden er in andere vakgebieden uitzien zie je in de Eisenhower Matrix Coach, die een complete voorbeeldweek prioriteert, en in de GROW Coach, die een half coachgesprek uitschrijft om de vraagstijl over te dragen.
De vier fouten die elke eerste skill maakt
reg. S.004Vier patronen die we in vrijwel elke beginnende skill tegenkomen, ook in onze eigen eerste versies. Herken je er een in je concept, dan staat de oplossing in het blok en de uitwerking in DOC.06 eronder.
De vier fouten uitgediept, met de reparatie erbij
Te vaag is de fout die het langst onzichtbaar blijft, omdat vage skills wel output leveren. Die output oogt bruikbaar, maar hij zou zonder de skill vrijwel hetzelfde zijn geweest. De test is simpel: neem een regel uit je skill en vraag je af welke output ermee in strijd zou zijn. Kan niets in strijd zijn met "wees concreet en to the point", dan is de regel decoratie. Vervang hem door de meetbare variant: maximaal vijf regels per resultaatblok, elk resultaat geformuleerd als iets dat de klant kan nakijken, geen bijvoeglijk naamwoord waar een cijfer kan staan.
Te breed herken je aan de checklist: als de verplichte input voor de ene helft van de taken totaal anders is dan voor de andere helft, zitten er twee skills in je bestand. Opknippen voelt als verlies maar is winst, want twee scherpe skills activeren allebei vaker en beter dan een grote die overal een beetje bij past. Kijk naar hoe de 100 skills op de skillspagina zijn ingedeeld: geen skill genaamd strategie-hulp, maar aparte skills per methode, elk met eigen triggers, eigen stappen en een eigen weigeringenblok.
Geen triggers is statistisch de grootste moordenaar van eerste skills
De schrijver kent zijn eigen skill en typt in tests automatisch de juiste woorden, dus in de eigen sessie werkt alles. Collega's formuleren anders en raken de description nooit.
De reparatie staat in FIG.02; de aanvulling hier is een gewoonte: houd de eerste week bij welke vragen je skill had moeten oppakken maar niet oppakte, en plak die formuleringen letterlijk in de description. Na een week echt gebruik is die laag spreektaal vanzelf gevuld. Blijf je puzzelen op een skill die nooit aanslaat, of juist op alles, dan kun je hem ook laten nakijken: de AI Skill Bouwer loopt een bestaande SKILL.md langs acht vaste toetsen en zegt welke laag ontbreekt.
Twee talen tot slot is verleidelijk omdat de wereld van AI Engels is en je klanten misschien Nederlands zijn
Kies toch. Een Nederlandse skill met Nederlandse triggers voor Nederlandse gebruikers, en desnoods een Engelse tweeling ernaast. Dit spiegelt wat we elders over taal en vindbaarheid schrijven: wie gevonden wil worden, schrijft in de taal waarin er gezocht wordt, of dat nu een zoekmachine is of een model dat descriptions scant. Dezelfde logica geldt voor je site zelf; hoe je die leesbaar maakt voor AI-systemen staat in het artikel over llms.txt.
Zo test je of je skill werkt
Een skill test je niet in het gesprek waarin je hem schreef. Daar staat het hele bestand nog in het werkgeheugen van de sessie, dus daar doet het model braaf wat je bedoelde, skill of geen skill. De echte test begint met een schone sessie: installeer de skill zoals beschreven in Claude skills installeren, open een nieuw gesprek en stel de vraag zoals een collega hem zou stellen, zonder de naam van de skill of de methode te noemen. Activeert de skill, dan werkt je description. Activeert hij niet, dan weet je meteen wat je moet repareren, en je hebt er zelfs de eerste nieuwe triggerzin bij: de formulering die je zojuist zelf gebruikte.
Test daarna niet alleen het gewenste gedrag maar ook de grenzen
Overtreed bewust een weigering: vraag om een verzonnen referentie, om een garantie, om het gegeven dat je expres niet hebt aangeleverd. Een goede skill weigert dan zichtbaar en markeert de open plek; een zwakke vult stilletjes iets redelijks in. Controleer ook het format door dezelfde input twee keer in twee sessies aan te bieden: de inhoud mag verschillen, de structuur niet. En geef de skill een casus die er net buiten valt, zoals een aanbesteding aan de offerte-schrijver, om te zien of laag drie van de description zijn werk doet.
Daarna begint de fase die het verschil maakt: een week echt gebruik
Houd bij waar je handmatig ingrijpt, welke vragen de skill had moeten pakken, en welke output je achteraf herschreef. Elke ingreep is een regel, een trigger of een weigering die nog mist. Werk het bestand bij, hoog de versie op en test opnieuw. Skills zijn geen software die af is; het zijn werkafspraken die je onderhoudt zoals je een goede checklist onderhoudt. Wil je dit met je hele team leren, inclusief het bouwen van een gedeelde skillbibliotheek, dan is dat precies wat we doen in onze AI-trainingen.
De template, en de skill die hem voor je invult
Alles uit deze gids samengevat in een skelet dat je kunt kopiëren. Vervang de tekst tussen haken, schrap wat je taak niet nodig heeft, en houd de volgorde aan:
name: [taak-in-kleine-letters-met-koppeltekens]
description: [Wat de skill doet en oplevert, in twee zinnen. Gebruik deze skill ALTIJD wanneer iemand vraagt om] "[opdracht 1]", "[opdracht 2]", "[minimaal acht]". [Ook triggeren bij verzuchtingen als] "[spreektaal 1]", "[spreektaal 2]". [Niet gebruiken voor] [de grens, met het alternatief erbij].
version: 1.0.0
license: MIT
---
# [Naam van de skill]
[Wie de skill is en wat hij levert, twee tot vier zinnen, jij-vorm.]
## Wat de skill altijd doet
[Genummerde stappen, elk controleerbaar geformuleerd.]
## Verplichte input checklist
[Wat er nodig is; vraag alleen na wat ontbreekt.]
## Outputformat
[De exacte structuur van elk antwoord.]
## Schrijfregels
[Taal, toon, verboden woorden, één taal per skill.]
## Wat de skill nooit doet
[Minimaal: niet verzinnen, niet garanderen, ontbrekende gegevens markeren als INVULLEN. Plus de grenzen van jouw vak.]
## Verkort voorbeeld
[Echte input, echte output, inclusief een zichtbare open plek.]
Wie liever praat dan typt, gebruikt de download bovenaan deze pagina
De skill-md-generator is zelf een skill die deze gids uitvoert: hij interviewt je over je taak, vraagt expliciet hoe collega's de vraag zouden formuleren, en schrijft daarna de complete SKILL.md uit, inclusief de drie triggerlagen, controleerbare stappen en een weigeringenblok dat hij nooit overslaat.
Hij heeft ook een eigen grens, in de geest van deze gids: skills die misleiding of spam als doel hebben, zoals nepreviews of verzonnen keurmerken, weigert hij te schrijven en hij legt uit waarom. Hoe zo'n gegenereerde skill zich verhoudt tot de handgeschreven exemplaren zie je op deze site zelf: elke blog in de kennisbank levert er tegenwoordig een mee, van de kostenraming bij het linkbuilding-artikel tot de checklist-skill bij de lokale SEO-gids. Vragen over een skill die je aan het bouwen bent? Stuur hem gerust mee via contact, meekijken kost niets.
Veelgestelde vragen over het schrijven van een SKILL.md
Wat is het verschil tussen een SKILL.md en een gewone prompt?
Een prompt schrijf je per gesprek en verdwijnt daarna; een SKILL.md is een bestand dat je werkwijze permanent vastlegt en dat de AI er zelf bij pakt zodra de taak langskomt. Het grootste praktische verschil zit in de description: die vertelt het model wanneer de kennis relevant is, zodat je er niet elke keer om hoeft te vragen. Daarnaast dwingt het format keuzes af die in een losse prompt meestal ontbreken: vaste stappen, een outputformat en weigeringen. Je schrijft hem een keer goed en profiteert er elke sessie van.
Hoe lang moet een SKILL.md zijn?
Er is geen verplichte lengte, wel een werkbare bandbreedte. De skills op theseo.nl zitten rond een mediaan van ongeveer 1.300 woorden: groot genoeg voor triggers, stappen, weigeringen en een voorbeeld, klein genoeg om in een keer gelezen te worden. Korter dan een A4 wordt al snel te vaag om gedrag echt te sturen, en bij heel lange bestanden verwatert de kern. Groeit je skill ver boven de 2.500 woorden, knip hem dan op in twee skills met elk een eigen taak en eigen triggerzinnen.
Schrijf ik mijn SKILL.md in het Nederlands of in het Engels?
Kies de taal van je gebruikers en houd je eraan, want de description matcht op hoe mensen hun vraag formuleren. Een Nederlandse gebruiker die om een offerte vraagt, wordt slecht gematcht door een Engelse description, en andersom. Mengen is de slechtste optie: dan is de skill in beide talen een halve match. Vaktermen die iedereen in het Engels gebruikt laat je gewoon staan, maar de zinnen eromheen, de stappen en de weigeringen schrijf je in een taal. Wil je beide talen bedienen, maak dan twee varianten met elk hun eigen triggers.
Waarom heeft een skill weigeringen nodig?
Omdat een taalmodel van nature aanvult wat ontbreekt, en dat is bij zakelijke documenten precies wat je niet wilt. Zonder expliciete grenzen verzint een model desnoods een prijs, een referentie of een garantie om het document af te maken. Een blok met wat de skill nooit doet, zoals de acht nooit-regels van de AI Offerte Schrijver, keert dat om: ontbreekt een gegeven, dan komt er INVULLEN te staan en blijft de beslissing bij jou. Weigeringen maken een skill niet strenger, ze maken de output bruikbaar zonder dat je elke regel op verzinsels hoeft na te lopen.
Werkt dezelfde SKILL.md in Claude Code, Claude.ai en Codex?
Ja, hetzelfde bestand werkt op alle drie, alleen de installatie verschilt. In Claude Code pak je de zip uit in de map ~/.claude/skills/ of .claude/skills/ in je project, waarna de skill automatisch wordt herkend op het onderwerp. In Claude.ai upload je de zip via Customize en dan Skills, of je plakt de inhoud in de projectinstructies van een Project. Voor Codex plak je de inhoud van SKILL.md in AGENTS.md, of je zet het bestand los in je repo en verwijst ernaar; Codex leest dat bij elke sessie mee. De drie routes staan ook onder de downloadknop bovenaan deze pagina.
Hoe test ik of mijn skill echt wordt opgepakt?
Test in een nieuwe sessie, niet in het gesprek waarin je de skill schreef, want daar staat alles nog in het werkgeheugen. Stel de vraag zoals een collega hem zou stellen, zonder de naam van de skill of de methode te noemen. Activeert de skill niet, dan is de description te smal en voeg je de formulering toe die je zojuist zelf gebruikte. Test daarna de weigeringen door er bewust een te overtreden, bijvoorbeeld door om een verzonnen cijfer te vragen, en controleer of de skill netjes weigert. Herhaal dat een week lang bij echt gebruik en vul de triggerzinnen aan met wat je in de praktijk typt.
Begin klein, maar begin met alle zeven blokken
Je eerste skill hoeft niet mooi te zijn; hij moet compleet zijn. Een kleine skill met een echte description, vijf controleerbare stappen, drie weigeringen en een verkort voorbeeld verslaat elke ambitieuze halve. Pak de template uit DOC.08 of laat de generator bovenaan het interview doen, kies de taak die je deze week drie keer hebt uitgevoerd, en schrijf hem vanmiddag. Kijk daarna hoe de vaklui het doen: de offerte-schrijver voor het weigeringenblok, de 100 voorbeelden op de skillspagina voor je eigen vakgebied, en wat zijn Claude skills als je iemand anders wilt uitleggen waar je mee bezig bent. De rest van het vak, van vindbaarheid tot AI, staat zoals altijd in de kennisbank.