De complete gids voor het maken van Claude Skills

We gebruiken Claude elke dag. Voor content, voor code, voor analyses. Maar de echte doorbraak kwam pas toen we begonnen met het bouwen van claude skills. Niet losse chatgesprekken, maar een systeem van herbruikbare instructies dat Claude verandert van generalist naar specialist. In deze complete gids leer je wat skills zijn, hoe je ze bouwt, test, en deelt met je team.

Wat zijn Claude Skills precies?

Een claude skill is een set instructies, verpakt in een simpele map, die Claude leert hoe specifieke taken of workflows uit te voeren. In plaats van bij elk gesprek opnieuw uit te leggen wat je verwacht, leg je het eenmalig vast. Claude leest die instructies automatisch wanneer je in dat project werkt.

Vergelijk het met een nieuwe collega inwerken. Je legt eenmalig uit hoe jullie content schrijven, welke tone of voice je hanteert, en welke structuur je gebruikt. Daarna hoef je dat niet meer te herhalen. Een claude skill doet precies hetzelfde.

De technische structuur is simpel. Een skill is een map met minimaal een SKILL.md bestand:

content-writer/
├── SKILL.md          # Verplicht: de instructies
├── scripts/          # Optioneel: uitvoerbare code
├── references/       # Optioneel: documentatie
└── assets/           # Optioneel: templates, iconen

Het SKILL.md bestand bevat YAML frontmatter (metadata) en markdown instructies, vergelijkbaar met hoe CLAUDE.md als systeemprompt werkt. Claude leest de frontmatter altijd, en laadt de volledige instructies alleen wanneer de skill relevant is voor de huidige taak. Dat heet progressive disclosure en het zorgt ervoor dat Claude niet onnodig tokens verbruikt.

Waarom Claude Skills het verschil maken

Het grootste probleem met AI-tools is inconsistentie. De ene keer krijg je een goed resultaat, de andere keer moet je het halve antwoord herschrijven. Claude skills lossen dat op.

Consistentie. Met een goede skill krijg je elke keer dezelfde kwaliteit, dezelfde tone of voice, en dezelfde structuur. Voor content betekent het dat elk artikel dezelfde opmaak heeft. Voor code dat de conventies altijd kloppen.

Snelheid. Zonder skills herhaal je bij elk gesprek dezelfde context: wie je bent, wat je maakt, welke regels je hanteert. Met skills hoeft dat niet meer. Je opent Claude, noemt de taak, en gaat direct aan de slag.

Schaalbaarheid. Een skill werkt niet alleen voor jou. Stop hem in een gedeelde repo en het hele team gebruikt dezelfde instructies. De kennis zit dan in het systeem, niet in een persoon. Dat is precies hoe we werken: iedereen moet vervangbaar zijn, en dat betekent dat kennis gedocumenteerd is, niet opgesloten in iemands hoofd.

Bij Futy bedienden we 4.000 bedrijven met minder dan vier fte. Dat lukte omdat we alles automatiseerden wat geautomatiseerd kon worden. Claude skills zijn dezelfde filosofie, toegepast op AI-workflows. Eerst handmatig doen, vastleggen wat werkt, en dan automatiseren.

De drie niveaus van progressive disclosure

Claude laadt skills niet in een keer. Er zijn drie niveaus, en dat is bewust zo ontworpen.

Niveau 1: YAML frontmatter. Dit wordt altijd geladen in Claude's systeemprompt. Het bevat alleen de naam en een beschrijving. Genoeg voor Claude om te bepalen of de skill relevant is, zonder de volledige instructies te laden.

Niveau 2: SKILL.md body. Dit wordt geladen zodra Claude denkt dat de skill relevant is voor de huidige taak. Hier staan de volledige instructies, regels, en voorbeelden.

Niveau 3: Gelinkte bestanden. Aanvullende documentatie in de references/ map die Claude pas opent als het nodig is. Denk aan API-documentatie, stijlgidsen, of uitgebreide voorbeeldbestanden.

Dit systeem houdt het tokenverbruik laag. Een skill kan uitgebreide referentiedocumentatie bevatten zonder dat dit allemaal bij elk gesprek wordt geladen.

Zo bouw je een Claude Skill stap voor stap

Het bouwen van een skill is geen technisch werk. Als je een briefing kunt schrijven voor een collega, kun je een skill schrijven voor Claude.

Stap 1: Identificeer een terugkerende taak

Begin met een taak die je regelmatig doet. Denk aan content schrijven, e-mails opstellen, code reviewen, of data analyseren. Kies de taak die je het meest doet en waarvoor je nu telkens dezelfde uitleg geeft aan Claude.

Anthropic onderscheidt drie categorieen skills:

1. Document- en assetcreatie. Consistente documenten, presentaties, designs of code genereren. Denk aan een skill die altijd dezelfde opmaak en stijl toepast.
2. Workflow-automatisering. Meerstaps-processen die baat hebben bij een vaste methodiek. Denk aan een skill voor sprintplanning of een onboardingproces.
3. MCP-versterking. Workflow-instructies die bovenop een MCP-server werken. De MCP geeft Claude toegang tot tools, de skill leert Claude hoe die tools het beste in te zetten.

Stap 2: Schrijf de frontmatter

De YAML frontmatter is het belangrijkste onderdeel. Hier beslist Claude of je skill geladen moet worden.

---
name: content-writer
description: Schrijft SEO-geoptimaliseerde blogartikelen in onze brand voice. Gebruik wanneer de gebruiker vraagt om content te schrijven, een blogartikel te maken, of een artikel op te stellen.
---

Twee velden zijn verplicht: name (in kebab-case, zonder spaties) en description. De beschrijving moet twee dingen bevatten: wat de skill doet, en wanneer Claude hem moet gebruiken. Wees specifiek. "Helpt met projecten" werkt niet. "Beheert Linear projectworkflows inclusief sprintplanning en taakcreatie. Gebruik wanneer de gebruiker sprint, taken, of projectplanning noemt." werkt wel.

Stap 3: Schrijf de instructies

Na de frontmatter volgen de daadwerkelijke instructies in markdown. Wees concreet. "Schrijf goede content" is geen instructie. "Schrijf in de tweede persoon enkelvoud, gebruik korte alinea's van maximaal vier zinnen, vermijd hype-taal, en eindig elk artikel met een FAQ-sectie" is dat wel.

Hier is een voorbeeld van een content-writer skill:

---
name: content-writer
description: Schrijft blogartikelen in onze brand voice. Gebruik bij vragen over content, blogs, of artikelen schrijven.
---

# Content Writer Skill

## Instructies

### Stap 1: Lees de context
Raadpleeg `references/brand-voice.md` voor tone of voice en woordkeuze.

### Stap 2: Schrijf het artikel
- Gebruik altijd "je/jij", nooit "u"
- Korte alinea's: maximaal 3-4 zinnen
- Actieve schrijfvorm
- Vermijd hype-woorden en vage beloftes
- Focus keyword in titel, eerste alinea en minimaal een H2

### Stap 3: Controleer
Valideer tegen `references/seo-checklist.md` voordat je het artikel oplevert.

## Troubleshooting
Fout: artikel klinkt niet als ons
Oorzaak: te formeel of te veel jargon
Oplossing: herlees brand-voice.md en herschrijf in spreektaal

Let op de structuur: stappen, concrete regels, referenties naar aanvullende bestanden, en troubleshooting. Dat zijn de bouwstenen van een goede skill.

Stap 4: Sla het bestand op

Maak een map aan in je project: .claude/skills/content-writer/. Sla de instructies op als SKILL.md (hoofdlettergevoelig). Claude leest dit bestand automatisch bij elk gesprek in dat project.

Stap 5: Test en itereer

Test de skill op een echte taak. Kijk wat goed gaat en wat niet klopt. Pas de instructies aan. Je eerste versie is zelden de beste versie.

Plan een iteratiecyclus: gebruik de skill tien keer, noteer wat je steeds corrigeert, en voeg die correcties toe aan de instructies. Na tien iteraties heb je een skill die echt werkt. Dit principe staat bekend als de plan-instantiate-learn loop. Meer over iteratief verbeteren lees je in onze aparte gids.

Design patterns voor Claude Skills

Anthropic heeft vijf patronen geidentificeerd die goed werken in de praktijk. Afhankelijk van je use case kies je het patroon dat past.

Sequentiele workflow-orkestratie

Voor processen die in een vaste volgorde moeten verlopen. Denk aan klant-onboarding: eerst account aanmaken, dan betaling instellen, dan abonnement activeren, en tot slot een welkomstmail versturen. Elke stap hangt af van de vorige, en bij elke stap beschrijf je validatie en foutafhandeling.

Iteratieve verfijning

Voor taken waarbij de kwaliteit verbetert door herhaling. Denk aan rapportages: eerst een concept genereren, dan een kwaliteitscheck uitvoeren, problemen oplossen, opnieuw valideren, en herhalen tot het resultaat goed genoeg is. De skill beschrijft expliciete kwaliteitscriteria en wanneer je moet stoppen met itereren.

Contextafhankelijke toolselectie

Voor situaties waarin hetzelfde doel op verschillende manieren bereikt kan worden. De skill bevat een beslisboom: als het bestand groter is dan 10MB, gebruik cloud storage. Als het een collaboratief document is, gebruik Notion. Als het code is, gebruik GitHub. Claude kiest automatisch het juiste pad.

Domeinspecifieke intelligentie

Voor taken die specialistische kennis vereisen. Denk aan financiele compliance of juridische controles. De skill bevat de domeinregels zodat Claude ze consequent toepast, zonder dat de gebruiker ze elke keer hoeft te specificeren.

Multi-MCP coordinatie

Voor workflows die meerdere diensten omvatten. Bijvoorbeeld een design-naar-development handoff: eerst assets exporteren uit Figma, dan uploaden naar Google Drive, vervolgens taken aanmaken in Linear, en tot slot een notificatie sturen via Slack. De skill beschrijft de fasering en de data die tussen de stappen wordt doorgegeven.

Testen en verbeteren van je skills

Testen kan op drie niveaus, afhankelijk van hoe kritisch de skill is.

Handmatig testen in Claude.ai. Voer queries uit en observeer het gedrag. Snel te itereren, geen setup nodig. Dit is voldoende voor persoonlijke skills.

Geautomatiseerd testen in Claude Code. Schrijf testcases die je herhaaldelijk kunt uitvoeren. Handig als je de skill regelmatig aanpast en wilt controleren of alles nog werkt.

Programmatisch testen via de Skills API. Bouw evaluatiesuites die systematisch draaien tegen gedefinieerde testsets. Dit is voor skills die door duizenden gebruikers worden ingezet.

Ongeacht welk niveau je kiest, test altijd deze drie aspecten:

1. Triggering. Laadt de skill op de juiste momenten? Test met voor de hand liggende vragen, maar ook met geparafraseerde verzoeken. En test of de skill niet triggert bij onverwante onderwerpen.
2. Functionaliteit. Levert de skill de juiste output? Kloppen de resultaten? Werkt de foutafhandeling?
3. Prestatie. Is het resultaat beter dan zonder skill? Vergelijk het aantal berichten, de hoeveelheid tokens, en het aantal fouten met en zonder skill.

Een praktische tip van Anthropic: begin met een enkele uitdagende taak en itereer tot Claude die consistent goed uitvoert. Pas daarna breid je uit naar meerdere testcases.

Onze Claude Skills in de praktijk

We hebben inmiddels meer dan tien skills die samen ons content- en ontwikkelproces aansturen.

De content-writer skill schrijft blogartikelen in onze brand voice. De skill kent onze tone of voice, weet welke woorden we vermijden, en weet hoe we MDC-componenten gebruiken voor interactieve elementen. Elk artikel dat via deze skill wordt geschreven, heeft dezelfde structuur en klinkt als ons.

De seo-analyst skill analyseert zoekwoorden en concurrenten. We geven een onderwerp op, en de skill levert een gestructureerde analyse met zoekvolumes, concurrentieniveau, en aanbevelingen voor clustering.

De developer skill kent onze Nuxt 4-conventies tot in detail. Welke composables we gebruiken, hoe we collectienamen opbouwen, waarom we nooit queryContent() gebruiken. Een nieuwe bijdrage aan de codebase volgt automatisch de juiste patronen.

Wat al deze skills gemeen hebben: de kennis zit in het systeem, niet in onze hoofden. Als morgen iemand anders aan dit project werkt, pakt hij de skills op en kan direct productief zijn.

Veelgemaakte fouten (en hoe je ze voorkomt)

Te vage beschrijvingen. De description in je frontmatter bepaalt of Claude je skill laadt. "Helpt met projecten" triggert op alles en niets. Noem specifieke taken en trigger-zinnen die gebruikers daadwerkelijk zeggen.

Te veel in SKILL.md proppen. Houd de hoofdinstructies beknopt. Verplaats gedetailleerde documentatie naar references/ bestanden en verwijs ernaar. Dat is progressive disclosure in de praktijk. Anthropic adviseert om SKILL.md onder de 5.000 woorden te houden.

Niet itereren. Je eerste versie is een startpunt, geen eindpunt. Gebruik de skill actief, noteer wat je steeds moet corrigeren, en verwerk die correcties in de instructies. Na tien iteraties heb je een skill die echt werkt.

Niet delen. Een skill die alleen jij gebruikt, is de helft waard. Stop je skills in de gedeelde projectrepository. Dan profiteert het hele team. Dat is ook hoe je kennis van individuen naar systemen verplaatst. Het delen van skills is daar een concreet beginpunt.

Over- of undertriggering. Als je skill te vaak laadt bij onverwante vragen, voeg dan negatieve triggers toe aan de beschrijving. Bijvoorbeeld: "Gebruik NIET voor simpele data-exploratie." Als de skill juist te weinig triggert, voeg meer synoniemen en trigger-zinnen toe.

Skills delen en distribueren

Je kunt claude skills op verschillende manieren delen.

Via een gedeelde repository. De eenvoudigste aanpak. Sla je skills op in de .claude/skills/ map van je projectrepository. Iedereen die het project opent, heeft automatisch toegang tot alle skills. Zo doen wij het ook.

Via Claude.ai. Upload een gezipte skill-map via Settings, Capabilities, Skills. Handig als je een skill wilt gebruiken buiten een specifiek project.

Op organisatieniveau. Beheerders kunnen skills uitrollen voor een hele organisatie. Automatische updates, centraal beheer. Ideaal voor teams die consistentie willen afdwingen.

Via de API. Voor programmatische use cases. Je kunt skills toevoegen aan API-requests, versiebeheer toepassen, en skills integreren in geautomatiseerde pipelines.

Van losse tool naar vast teamlid

Claude Skills zijn hoe je die stap maakt. Niet als abstracte belofte, maar als concreet bestand dat je vandaag kunt schrijven.

Begin met een terugkerende taak. Schrijf de instructieset. Test hem. Pas aan. Deel met het team. Herhaal.

Je bouwt zo stap voor stap een systeem waarbij AI niet een losse tool is die je soms gebruikt, maar een vaste schakel in je workflow. Of je nu content schrijft of code reviewt, skills maken het proces herhaalbaar en schaalbaar.