Claude-skill maken: SKILL.md schrijven in 10 minuten

We testen Claude skills voor de kost, inmiddels honderden, en het patroon is deprimerend: de meeste skills die onze review niet doorstaan, faalden niet omdat de auteur geen instructies kon schrijven. Ze faalden omdat de skill nooit laadde, of laadde wanneer het niet moest, of drie skills in een trenchcoat was. Allemaal op te lossen tijdens het schrijven, geen van alle op te lossen achteraf met een mooiere README.

Dit is de tutorial die we willen dat elke indiener eerst had gelezen. Aan het eind heb je een werkende skill: een code-reviewchecklist die Claude voorbij "ziet er goed uit, hernoem deze variabele misschien" duwt naar het checken van randgevallen, foutpaden en dode code. Het is met opzet een echt voorbeeld. De beste community-skill in onze codingcategorie, Code Review Checklist, doet precies dit en scoort 8/10 op output. Die van jou verslaat hem niet op dag één, maar je begrijpt wel elke beslissing die de auteur van die skill heeft genomen.

De belofte van 10 minuten is eerlijk, met één sterretje. De eerste werkende versie schrijven duurt ongeveer 10 minuten. Hem goed testen duurt nog eens 30. Sla dat tweede deel over en je voegt je bij de helft van gepubliceerde skills die het contact met een verse sessie niet overleeft. We schreven de autopsie op in waarom de helft van Claude-skills niet werkt, en we voegen die van jou liever niet toe aan de dataset.

Als je nog nooit een skill hebt geïnstalleerd en niet weet wat het is, lees dan eerst wat Claude-skills zijn en hoe je ze installeert. Deze post gaat ervan uit dat je er minstens één hebt gebruikt.

Stap 1: beperk tot één taak

Voordat je een regel schrijft, bepaal wat je skill doet. Halveer dat vervolgens.

Het grootste faalpatroon dat we in tests zien, zijn skills die alles proberen te doen. "Helpt bij codekwaliteit" klinkt als een redelijke scope. Dat is het niet. Zo'n skill wil triggeren op reviews, refactors, testen schrijven, lintvragen en architectuurdiscussies, wat in de praktijk betekent dat Claude niet kan bepalen wanneer hij moet laden, dus laadt hij onvoorspelbaar of helemaal niet. Triggerproblemen zijn de nummer één reden dat een skill laag scoort in onze methodologie, vóór slechte instructies en kapotte installaties. Niet omdat triggeren het lastigste onderdeel van skill-authorship is, maar omdat scope creep stroomopwaarts het stroomafwaarts onoplosbaar maakt.

Eén skill, één taak. Hier is de test: kun je de zin "gebruik deze skill wanneer de gebruiker vraagt om ___" afmaken met één concrete werkwoordzin? "Een pull request of diff reviewen" slaagt. "Hun code verbeteren" faalt. Als jouw zin "en" of "of" bevat om ongerelateerde activiteiten te koppelen, schrijf je twee skills. Schrijf twee skills. Mappen zijn gratis.

Voor ons voorbeeld is de scope: een diff of PR reviewen op correctheidsbugs, met een vaste checklist, waarbij stijl-nitpicks onderdrukt worden. Niet "help bij reviews." Niet "review en fix." Reviewen, rapporteren, stoppen.

Stap 2: het SKILL.md-template

Een skill is een map met één verplicht bestand. De onze gaat in ~/.claude/skills/ voor persoonlijk gebruik, of .claude/skills/ binnen een repo als het hele team hem moet krijgen:

review-checklist/
  SKILL.md          ← verplicht, en vaak alles wat je nodig hebt
  reference/        ← optioneel, alleen geladen als Claude besluit het te lezen
  templates/        ← optioneel, bestanden waar je instructies naar verwijzen

Hier is de volledige SKILL.md die we gaan bouwen, geannoteerd. Kopieer hem, lees dan de annotaties, want twee van deze regels zijn veel belangrijker dan de rest:

---
# 'name' is een identifier: kleine letters, koppeltekens, geen spaties.
# Claude ziet het, maar het stuurt de triggering NIET aan.
name: review-checklist

# 'description' is het ENIGE dat Claude leest bij het beslissen
# of deze skill geladen wordt. Alles onder de frontmatter is
# onzichtbaar tot na die beslissing. Schrijf het als een
# triggervoorwaarde, geen marketingtekst.
description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Runs a
  correctness-focused review checklist. Do NOT use for writing
  new code, fixing bugs the user already identified, or
  general refactoring requests.
---

# Code review checklist

When reviewing a diff or PR, work through this checklist in
order. Report only findings; do not fix anything unless asked.

## Procedure

1. Read the full diff before commenting on any line.
2. For each changed function, check:
   - Off-by-one risks at loop bounds and slice indices
   - Null/undefined paths: what happens when inputs are empty?
   - Error handling: are failures swallowed or logged and re-raised?
3. Check for dead code the change creates: unused imports,
   unreachable branches, orphaned helpers.
4. Check concurrency only if the diff touches shared state.
5. Verify new logic has test coverage. Missing tests are a
   finding, not a blocker.

## Reporting rules

- Max 10 findings, ordered by severity. If you found 30,
  report the 10 worst.
- Every finding needs a file, a line reference, and a one-line
  fix suggestion.
- Do NOT report: naming preferences, formatting, comment
  style, or anything a linter would catch.
- If the diff is clean, say so in one sentence. Do not invent
  findings to seem thorough.

Dat is de hele skill. Geen buildstap, geen manifest, geen registratie. Herstart je Claude-sessie en hij is live.

De frontmatter heeft precies twee velden die ertoe doen. name is boekhouding. description beslist alles, en hier is waarom: Claude houdt alleen de naam en beschrijving van elke geïnstalleerde skill in context. De body van je SKILL.md bestaat voor het model niet totdat het je beschrijving leest, besluit "dit past bij wat de gebruiker wil," en de rest laadt. Een briljante checklist van 200 regels achter een vage beschrijving is een briljante checklist van 200 regels die nooit wordt uitgevoerd. In onze scoringsrubriek weegt triggering even zwaar als outputkwaliteit, om precies deze reden. Een skill die 40% van de tijd afgaat, is een muntje opgooien met extra stappen.

Stap 3: schrijf de triggerbeschrijving

Omdat de beschrijving een triggervoorwaarde is, schrijf hem ook als zodanig. Noem de formuleringen die een echte gebruiker zou typen. Voeg de negatieve ruimte toe, oftewel de nabijgelegen verzoeken waarbij de skill stil moet blijven.

Naast elkaar, uit echte inzendingen die we hebben getest (licht geanonimiseerd):

Slecht:

description: A powerful skill that helps improve code quality
  and catch issues early in the development process.

Goed:

description: Use when the user asks to review code, review a
  PR, review a diff, or check a branch before merging. Do NOT
  use for writing new code or fixing already-identified bugs.

De slechte beschrijft het voordeel. De goede beschrijft het moment. Claude leest je beschrijving niet om overtuigd te worden; hij matcht patronen tegen de daadwerkelijke woorden van de gebruiker. "Review deze PR" deelt geen woordenschat met "helpt codekwaliteit verbeteren," dus slaapt de skill door zijn eigen use case heen. We testten een inzending die bijna identiek was aan dat slechte voorbeeld: die triggerde bij 1 van de 8 review-achtige prompts. Na het herschrijven van de beschrijving om formuleringen te noemen, met dezelfde body, triggerde hij bij 8 van de 8.

Nog een paar, deze keer over de negatieve ruimte:

Slecht:

description: Use for anything related to testing.

Goed:

description: Use when the user asks to write tests for
  existing code or asks what to test. Do NOT use when the
  user is doing TDD (writing tests before implementation) or
  debugging a failing test.

"Alles wat met testen te maken heeft" is hoe je een debugsessie kaapt. Overtriggeren is stiller dan ondertriggeren en net zo schadelijk: de gebruiker krijgt checklist-achtige antwoorden op vragen die iets anders nodig hadden, geeft het model de schuld, en verwijdert de skill.

Mechanische regels die overal opgaan in wat we hebben getest: noem drie tot vijf concrete gebruikersformuleringen, voeg minstens één "do NOT use"-clausule toe, blijf onder ruwweg 500 tekens, en gebruik nooit de woorden "powerful," "comprehensive," of "helps with." Die woorden correleren zo consistent met falende triggerscores in onze data dat we er inmiddels van ineenkrimpen.

Stap 4: schrijf een body die Claude echt volgt

Zodra de skill laadt, is de body de instructieset. Het faalpatroon hier is subtieler dan triggering maar net zo vaak voorkomend: instructies die inspireren in plaats van beperken. "Schrijf een grondige, doordachte review" is een motivatieposter. Claude wil al grondig en doordacht zijn; dat is het standaardgedrag dat je probeert te vormen, niet de vorm zelf.

De skills die bovenaan onze ranglijst staan, zijn lijsten met beperkingen. Test-Driven Development verbiedt implementatie voordat er een falende test bestaat, punt uit. Onze voorbeeldskill maximeert bevindingen op 10 en verbiedt stijl-nitpicks ronduit. Let op hoeveel regels beginnen met "do not." Dat is bewust. Modellen genereren standaard te veel, dus de meest waardevolle instructies zijn meestal aftrekkend.

Vuistregels voor de body:

1. Genummerde procedures verslaan proza. "Werk dit op volgorde door" geeft Claude een ruggengraat; alinea's geven vibes.
2. Benoem de stopvoorwaarde. Onze skill zegt: rapporteer bevindingen, fix niet. Zonder die regel gaat Claude behulpzaam de code herschrijven, wat niemand vroeg.
3. Legisleer het outputformaat. Maximumaantallen, verplichte velden, hoe een schoon resultaat eruitziet. "Als de diff schoon is, zeg dat" voorkomt verzonnen bevindingen, een fout die we constant tegenkomen bij review-achtige skills.
4. Zet zelden benodigde details in reference/-bestanden. Als je skill een stijlgids van 300 regels heeft die eens per maand van toepassing is, plak die dan niet in SKILL.md waar het context verbrandt bij elke activatie. Sla het op als reference/style-guide.md en schrijf "als de gebruiker vraagt over X, lees eerst reference/style-guide.md." Claude laadt het on demand.

Wanneer voeg je scripts en templates toe? Alleen wanneer instructies de taak niet kunnen klaren. Een skill die een specifiek configbestand genereert, moet een templates/config.yaml meeleveren en zeggen "kopieer dit, pas dan aan." Een skill die deterministisch gedrag nodig heeft, zeg het parsen van een lockfile-formaat, moet een script meeleveren en Claude instrueren dat uit te voeren in plaats van het telkens uit het geheugen te herbouwen. Maar de meeste skills hebben geen van beide nodig. Onze voorbeeldskill heeft geen van beide nodig. Elk bestand in de map is iets wat je nu onderhoudt, dus verdien elk bestand.

Stap 5: test hem lokaal

Je bent niet klaar als hij één keer werkt. "Het werkte toen ik het probeerde" is de teststandaard van elke kapotte skill die we ooit hebben afgekeurd. Hier is de minimale testreeks, en die komt sterk overeen met wat onze methodologie draait op inzendingen:

1. Verse sessie. Herstart Claude Code volledig. Skills laden bij sessiestart; testen in de sessie waarin je hem schreef, bewijst niets.
2. Triggertest, positief. Probeer drie verschillende formuleringen die een echte gebruiker zou typen: "review deze PR," "kun je deze diff checken voor ik merge," "kijk naar mijn wijzigingen." Alle drie zouden de skill moeten activeren. Je herkent dat hij afging doordat de output je regels volgt (een gemaximeerde, op ernst geordende bevindingenlijst lijkt nergens op een standaardreview). Twijfel je, vraag Claude dan rechtstreeks of hij de skill gebruikte.
3. Triggertest, negatief. Probeer drie aanpalende verzoeken die hem NIET zouden moeten activeren: "fix deze bug," "schrijf een functie die datums parst," "waarom faalt deze test?" Als je reviewchecklist opduikt in een debugsessie, heeft je beschrijving een "do NOT use"-clausule nodig.
4. Baseline-vergelijking. Draai dezelfde reviewprompt in een sessie met de skill en één zonder. Kun je de outputs niet uit elkaar houden, dan verdient de skill zijn context niet en moet je de beperkingen aanscherpen. Dit is onze favoriete test omdat hij meedogenloos is. Ongeveer een derde van de skills die we reviewen, faalt hierop.
5. Schone-installatietest. Als je van plan bent te publiceren: kopieer de map naar een andere machine (of verwijder en kloon opnieuw), volg je eigen README letterlijk, en kijk of het werkt. Ontbrekende dependency-notities sneuvelen hier.

De hele testreeks kost 30 minuten. Het filtert ongeveer 80% van de fouten die we zien, wat een sterk rendement is op een half uur.

Stap 6: haal hem door de validator

Voordat je publiceert, plak je SKILL.md in onze gratis skill-validator. Die scoort volgens dezelfde rubriek die we in reviews gebruiken: lengte en specificiteit van de beschrijving, aanwezigheid van concrete triggerformuleringen, negatieve-ruimte-clausules, beperkingsdichtheid in de body, formaatlegislatie, evidente anti-patronen zoals "powerful" en "anything related to."

Het is statische analyse, behandel het dus zo. Het vangt de fouten die zichtbaar zijn in de tekst, wat in onze ervaring de meeste zijn, maar het kan je skill niet tegen live prompts laten draaien. Een validatorpass plus de testreeks van stap 5 is de echte lat. Een validatorpass alleen is een gelinte skill die nog steeds niet hoeft te triggeren.

Wil je liever interactieve hulp dan een checker, dan is Anthropics Skill Creator het gereedschap dat we aanraden. Hij scoorde 9,6 in onze tests, bouwt de map op, en zijn beschrijvingsoptimalisatiestap verbeterde meetbaar de triggering van onze eigen interne skills. Een skill gebruiken om skills te schrijven klinkt als een grap en werkt toch.

Stap 7: publiceer en dien in

Publiceren is een normale GitHub-repo. Layoutconventie:

your-repo/
  README.md           ← wat het doet, installatiecommando, één voorbeeld
  review-checklist/
    SKILL.md
    reference/

Zet het installatiecommando als kopieerbaar blok in de README, waarbij het standaardpatroon git clone plus cp -r review-checklist ~/.claude/skills/ is. Voeg dan de tag claude-skills toe aan de repo. Dit is geen decoratie: de tag is hoe onze crawler en elke andere directory nieuwe skills ontdekken. Een niet-getagde skillrepo is in de praktijk onzichtbaar.

Een README die het schrijven waard is, heeft vier dingen: één zin over wat de skill doet, het installatieblok, één voor/na-voorbeeld, en eventuele dependencies. Het voor/na-voorbeeld doet meer voor adoptie dan al het andere samen, omdat het het enige onderdeel is dat laat zien in plaats van beweert.

Dien hem dan in bij SkillProof in. Testen en vermelden zijn gratis. We laten de inzending door hetzelfde proces gaan als al het andere in de catalogus: schone installatie vanuit je README, triggertestreeks, baseline-vergelijking, outputscoring. Als hij slaagt, wordt hij vermeld met een score, en kun je een "SkillProof getest"-badge in je README zetten. Voor een onbekende auteur met een repo van twee dagen oud is een onafhankelijk testoordeel het verschil tussen "willekeurige SKILL.md van het internet" en iets wat een vreemde daadwerkelijk installeert. Slaagt hij niet, dan krijg je de faalnotities, fix je hem, en dien je opnieuw in. Genoeg vermelde skills hebben twee rondes doorlopen.

Veelgemaakte fouten die we in inzendingen zien

Na een paar honderd reviews komen steeds dezelfde vijf terug.

Vage beschrijvingen. Nog steeds ruimschoots op nummer één. Als je beschrijving drie andere skills zou kunnen beschrijven, beschrijft hij er geen enkele.

De kitchen-sink-skill. Eén SKILL.md die reviews, commits, refactors en documentatie afhandelt. Elke taak verwatert de trigger voor de andere. Splits hem.

Modelstandaarden herhalen. Een body die zegt "wees duidelijk, wees accuraat, denk stap voor stap" voegt niets toe. Dat doet Claude toch al. Zou het verwijderen van een regel de output niet veranderen, verwijder de regel dan.

Geen negatieve beperkingen. Skills die alleen zeggen wat te doen, nooit wat te laten. De "do NOT"-regels zijn waar het meeste gedragsverandering zit.

Ongeteste installatie-instructies. De README zegt: kopieer één map; de skill hangt stiekem af van een tweede skill of een Python-pakket. Sneuvelt elke keer bij onze schone-installatiestap, en het is de meest vermijdbare fout op deze lijst.

Veelgestelde vragen

Moet ik kunnen programmeren om een Claude-skill te maken? Nee. Een SKILL.md is markdown met een YAML-header. Als je skill helper-scripts meelevert, moet je die wel schrijven, maar instructie-only skills, wat de meeste zijn, zijn puur schrijfwerk. De skill in deze post bevat geen enkele regel code.

Hoe lang moet een SKILL.md zijn? Zo kort mogelijk terwijl het nog steeds gedrag beperkt, doorgaans 30 tot 150 regels. Onder ongeveer 20 regels voegt het meestal niets toe boven de standaardwaarden; boven een paar honderd zou je detail moeten verplaatsen naar reference/-bestanden. Lengte is een kost per activatie, geen kwaliteitssignaal.

Waarom triggert mijn skill niet? Bijna altijd de beschrijving. Check of hij formuleringen noemt die een gebruiker daadwerkelijk typt in plaats van voordelen te beschrijven, en bevestig dat je de sessie hebt herstart na installatie, want skills laden bij sessiestart. Triggert hij bij sommige formuleringen en niet bij andere, voeg de ontbrekende dan expliciet toe aan de beschrijving.

Wat is het verschil tussen een skill en een MCP-server? Een skill is instructies: markdown die vormgeeft hoe Claude zich gedraagt, zonder code die ergens draait. Een MCP-server is een programma dat Claude nieuwe mogelijkheden geeft, zoals het bevragen van je database. Is je idee "Claude moet X anders aanpakken," dan is het een skill. Is het "Claude heeft toegang tot Y nodig," dan is het MCP. Uitgebreidere versie in Claude skills vs MCP.

Kan ik geld vragen voor een Claude-skill? Er is geen ingebouwd betaalmechanisme; skills zijn bestanden, en het publieke ecosysteem draait op open repo's. Sommige auteurs verkopen private skill-packs aan teams als consultancy-deliverable, wat werkt omdat de waarde in de gecodeerde expertise zit, niet in het bestand. Alles bedoeld voor de publieke catalogus moet open gelicentieerd zijn, want niemand installeert een skill die hij niet kan lezen.

Beperk tot één taak, schrijf de trigger als een regex in proza, beperk in plaats van te inspireren, en test in een verse sessie voordat je het iemand vertelt. Dat is het hele vak. De rest is iteratie, en de inzendingenwachtrij staat open.