AI & AutomationAI-generated

Wat zijn Claude Code skills eigenlijk? Van markdown-bestand tot werkende workflow

In eerdere posts heb ik geschreven over skills die mijn aandelenportefeuille coachen en skills die zichzelf verbeteren via een feedback-loop. Wat ik daarbij heb overgeslagen is de basale vraag: wat is een skill nou eigenlijk? Een paar lezers stelden die vraag en ze hebben gelijk dat het verwarrend kan zijn. Skills lijken op slash-commando's, op plugins, op MCP-servers, en toch is het iets eigens. Tijd om dat recht te zetten.

Een skill is gewoon een map met een markdown-bestand

Dat is de hele uitleg. Een Claude Code skill is een map ergens op je schijf met daarin een SKILL.md bestand en eventueel ondersteunende bestanden. Geen code, geen build-stap, geen plugin-systeem. Open de map in Finder en je ziet letterlijk een tekstbestand met markdown-instructies.

Concreet voorbeeld. Mijn portfolio-briefing skill leeft hier:

~/.claude/skills/portfolio-briefing/
├── SKILL.md
├── helpers/
│   ├── flex-fetch.js
│   └── tradingview-helpers.js
└── templates/
    └── briefing-template.md

Het hart van die map is SKILL.md. Dat is een markdown-document dat Claude leest wanneer ik de skill aanroep. De helpers en templates worden alleen geladen als de instructies in SKILL.md ernaar verwijzen.

Hoe de SKILL.md eruitziet

Een skill-bestand begint met frontmatter, gevolgd door instructies in normale markdown. Het minimale voorbeeld:

---
description: Geeft een korte weersamenvatting en de eerste drie afspraken van mijn agenda. Gebruik wanneer ik 's ochtends om een briefing vraag.
---

# Morning briefing

Wanneer ik een morning briefing vraag:

1. Haal het weer op via de weather MCP tool.
2. Lees de eerste drie afspraken uit Google Calendar.
3. Schrijf een korte samenvatting in twee paragrafen.
4. Sluit af met één concrete tip voor de dag.

Dat is de hele skill. Geen API-keys, geen plugin-registratie, geen npm-install. De mapnaam wordt automatisch de naam van de skill (morning-briefing), dus die hoef je niet apart in de frontmatter te zetten. Sla het op als ~/.claude/skills/morning-briefing/SKILL.md en Claude weet dat de skill bestaat.

Hoe Claude een skill ontdekt en oproept

Hier wordt het interessant. Claude Code laadt aan het begin van elke sessie de lijst met beschikbare skills in. Alleen de namen en beschrijvingen, niet de volledige inhoud. Die lijst is wat Claude in zijn context heeft tijdens een gesprek met jou.

Wanneer ik typ "geef me een morning briefing", scant Claude die lijst, ziet dat de description van mijn skill matcht, en laadt op dat moment de volledige SKILL.md in. Pas dan kent hij de stappen die ik heb opgeschreven, en gaat hij die uitvoeren.

Anthropic noemt dit principe "progressive disclosure": niet alles vooraf in context laden, maar pas op het moment van behoefte. Dat is wat skills bruikbaar maakt op schaal.

Dit ontwerp lost twee problemen tegelijk op:

  • Context blijft schoon: je kunt 50 skills hebben zonder dat je context volloopt. Alleen de gekozen skill wordt geladen.
  • Skills triggeren op intentie, niet op syntax: ik hoef geen vast commando te typen. "Geef me een briefing", "wat staat er op de agenda vanochtend" en "morning summary please" werken allemaal, mits de description in de skill goed beschrijft wanneer hij van toepassing is.

Daarnaast kun je een skill ook expliciet aanroepen met een slash. Typ ik /morning-briefing, dan laadt Claude direct die skill zonder de match-stap. Handig voor skills die je vaak gebruikt.

De description is het belangrijkste veld

Omdat Claude skills selecteert op basis van de description, is dat veld de sleutel. Een vage beschrijving zoals "doet portfolio dingen" wordt niet gematcht. Een precieze beschrijving zoals "geeft dagelijkse coaching op het US hoog-dividend portfolio, haalt IBKR data op, checkt alle posities tegen spelregels" wordt wél consistent gevonden.

Mijn vuistregel: schrijf de description alsof je iemand uitlegt wanneer hij de skill moet pakken, niet wat de skill doet. "Gebruik wanneer ik om X vraag" werkt beter dan "deze skill doet X".

Skills vs slash-commando's vs plugins vs MCP

Hier loop ik vaak tegen verwarring aan, dus rij voor rij:

Slash-commando's in Claude Code zijn ingebouwde shortcuts zoals /help, /clear, /init. Custom slash-commando's en skills waren ooit twee aparte systemen, maar Anthropic heeft ze inmiddels samengevoegd. Een bestand op .claude/commands/deploy.md en een skill op .claude/skills/deploy/SKILL.md maken allebei het commando /deploy aan en werken functioneel hetzelfde. Skills zijn de rijkere variant: ze ondersteunen een eigen map met ondersteunende bestanden en frontmatter om automatische invocation te regelen.

Plugins zijn pakketten die meerdere dingen tegelijk leveren: skills, hooks, MCP-servers, agents. Een plugin is een soort schil eromheen. Wat erin zit, kan een skill zijn. Een losse skill is dus geen plugin, maar een plugin kan skills bevatten.

MCP-servers (Model Context Protocol) zijn iets fundamenteel anders. Dat zijn aparte processen die Claude verbinden met externe systemen zoals databases, API's, of tools. Een skill kan een MCP-server gebruiken (mijn portfolio-briefing skill roept de TradingView MCP aan voor live koersen), maar de skill zelf is alleen instructies, geen draaiend proces.

Hooks zijn shell-commando's die uitgevoerd worden bij gebeurtenissen, bijvoorbeeld na elke tool-call of voor elke commit. Hooks gaan in settings.json, niet in skills.

De korte samenvatting: een skill is instructies in markdown. Alles wat draait, code uitvoert, of buiten Claude leeft is iets anders.

Waar leven skills

Twee plekken, met verschillende scope:

  • ~/.claude/skills/: user-skills, beschikbaar in elk project
  • <project-root>/.claude/skills/: project-skills, alleen beschikbaar in dat project

Ik gebruik beide. Mijn portfolio-briefing en crypto-briefing leven user-wide, want die wil ik overal kunnen aanroepen. Project-specifieke skills, zoals een test-runner voor een bepaalde codebase, leven binnen die projectmap.

Plugins die je via marketplaces installeert leven weer ergens anders (~/.claude/plugins/), maar functioneel werken hun skills hetzelfde.

Een minimale skill van begin tot eind

Voor wie nu wil beginnen: maak deze drie regels op je terminal aan en je hebt een werkende skill.

mkdir -p ~/.claude/skills/hello
cat > ~/.claude/skills/hello/SKILL.md << 'EOF'
---
description: Begroet de gebruiker uitgebreid in een willekeurige taal. Gebruik wanneer ik om een hello vraag.
---

Begroet de gebruiker in vijf verschillende talen, één per regel. Sluit af met de vraag in welke taal ik vandaag wil werken.
EOF

Start een nieuwe Claude Code sessie en typ /hello. Hij doet het. Voeg een paar zinnen toe aan SKILL.md en de skill verandert mee, zonder herstart van wat dan ook.

Waarom skills handig zijn

De voor de hand liggende reden is herhaalbaarheid. Een workflow die je vaak doet, leg je vast en de volgende keer is het één commando. Dat geldt voor saaie dingen zoals een dagelijkse briefing genereren, en voor complexere dingen zoals een aandeel stresstesten volgens jouw eigen criteria.

De minder voor de hand liggende reden is dat je je denken codificeert. Mijn portfolio-briefing skill is niet alleen een tool die data ophaalt. Het is de neergeschreven versie van hoe ik over mijn portfolio nadenk: welke spelregels gelden, in welke volgorde ik dingen check, wanneer ik wat moet zien. De skill is een soort externalisatie van mijn eigen workflow, en dat heeft als bijeffect dat ik 'm scherper formuleer dan in mijn hoofd alleen.

Voor wie wel eens een procedure of een runbook heeft geschreven: dat is het, behalve dat het runbook nu door iemand wordt uitgevoerd. Dat scheelt veel ergernis.

Wanneer is iets géén goede skill

Niet alles hoeft een skill te zijn. Wat ik probeer te vermijden:

  • Eenmalige taken. Schrijf de instructies in chat, klaar.
  • Heel korte workflows van twee stappen. Sneller om te typen dan om een skill te maken.
  • Workflows die elke keer net iets anders zijn. Een skill wordt dan een spaghetti aan condities.

Een skill is op zijn best als je de stappen al een paar keer hebt gedaan en steeds dezelfde volgorde aanhoudt. Dan is het tijd om ze vast te leggen.

Hoe ik mijn skills aanstuur

Inmiddels heb ik er een stuk of vijftien. Sommige draai ik elke dag (portfolio-briefing, crypto-briefing), andere af en toe (stock-verify, scan-clipping, sanity-check). Een paar zijn metaskills geworden: skills die andere skills aansturen of verbeteren.

De meeste skills hebben inmiddels een feedback-loop ingebouwd, zoals ik in een eerdere post beschreef. Daardoor verbeteren ze zichzelf, met mijn goedkeuring, gebaseerd op de wrijving die ik tijdens het gebruik ervaar.

Voor wie hier kennis mee wil maken: begin met één skill voor een workflow die je nu een paar keer per week handmatig doet. Schrijf de stappen op in een SKILL.md. Probeer hem. Pas hem aan als hij iets verkeerd doet. Binnen een paar dagen heb je je eerste werkende AI-procedure, zonder ook maar één regel code te hebben geschreven.

Dat is voor mij de echte belofte van skills. Niet zozeer "AI automatiseert mijn werk", maar "ik beschrijf hoe ik werk en de AI volgt mee".