Agent skill

Wat is een agent skill?

Een agent skill is een mapje met instructies, scripts en documenten dat een AI-agent inleest zodra de taak erom vraagt. In dat mapje zit minstens één bestand, SKILL.md: bovenaan wat YAML-metadata, daaronder gewone Markdown-tekst die vertelt hoe het werk hoort te gebeuren.

GitHub vat het in de Copilot-documentatie samen als mappen met instructies, scripts en documenten die de agent inlaadt wanneer ze relevant zijn. Meer zit er niet achter. Je schrijft op hoe een klus bij jullie verloopt, je zet dat in een map, en de agent volgt het.

De metadata blijft kort:

---
name: maandrapportage
description: Bouwt de maandrapportage voor de klant op volgens onze huisregels. Gebruik dit bij vragen over maandcijfers, rapportagesjablonen of de oplevering aan de klant.
---

Alleen name en description zijn verplicht. Die beschrijving doet twee dingen tegelijk: ze zegt wat de skill doet en wanneer je hem nodig hebt. Dat tweede stuk is waar de agent jouw vraag tegenaan legt.

Progressive disclosure: waarom dit werkt

De hele reden om met skills te werken zit in progressive disclosure, het gefaseerd inlezen. Dat gebeurt in drie stappen.

Ontdekken. Bij het opstarten laadt de agent enkel de naam en de beschrijving van elke geïnstalleerde skill in, zo'n honderd tokens per stuk, en houdt die bij in zijn system prompt. Verder wordt er niets gelezen.

Activeren. Past een vraag bij een beschrijving, dan leest de agent de volledige tekst van SKILL.md van schijf. Pas dan komt de werkwijze in het context window terecht. De specificatie raadt aan om die tekst onder de 5.000 tokens en onder de 500 regels te houden.

Uitvoeren. De agent volgt de instructies en haalt er onderweg bij wat hij nodig heeft. Een naslagbestand kost pas tokens op het moment dat het geopend wordt. Een script kost er zelfs helemaal geen: dat draait via de shell en enkel het resultaat komt terug, de code zelf komt nooit in het venster.

Het gevolg is dat dertig skills installeren je ongeveer dertig zinnen kost. Het engineeringteam van Anthropic schrijft dat de hoeveelheid context die je in een skill stopt daardoor in de praktijk onbegrensd is.

Wat zit er in zo'n map?

Naast SKILL.md ligt de indeling vrij, maar drie mapnamen komen steeds terug. In scripts/ zet je code die de agent uitvoert in plaats van zelf te schrijven, handig voor werk dat elke keer identiek moet verlopen. In references/ komt documentatie die hij er op aanvraag bijhaalt: een datamodel, een API-beschrijving, een stijlgids. In assets/ zitten sjablonen en vaste bestanden, bijvoorbeeld een rapportsjabloon in de huisstijl.

Aan de metadata kan je nog een licentie meegeven, een compatibility-veld voor wat de omgeving moet hebben, en een vrij in te vullen metadata-blok.

Agent skill, system prompt, fine-tuning of MCP?

Tegenover een system prompt

Een system prompt zit er altijd bij. Alles wat je erin schrijft, betaal je bij elke vraag opnieuw, en hoe meer regels je stapelt, hoe minder gewicht elke regel krijgt. Een skill komt er alleen bij wanneer hij nodig is. De werkwijze voor een maandafsluiting en die voor het schrijven van een DAX-meting staan zo naast elkaar zonder elkaar te verwateren.

De verdeling is dus simpel: wat altijd geldt hoort in de system prompt, wat bij één soort taak hoort gaat in een skill.

Tegenover fine-tuning

Bij fine-tuning pas je de gewichten van het model zelf aan. Dat vraagt trainingsdata, budget en tijd, en bij een overstap naar een nieuwer model begin je opnieuw. Een skill is een tekstbestand in een repository. Je past het aan, je commit het, en de volgende keer draait de agent met de nieuwe versie. Gaat het erom dat een agent jullie werkwijze volgt en niet om een vaardigheid die het model mist, dan wint het bestand.

Tegenover een MCP-server

Dit is het verschil dat het vaakst misloopt. Een MCP-server geeft een agent tools: hij mag daardoor een databank bevragen, een ticket aanmaken, een agenda lezen. Een skill geeft een agent instructies: welke van die tools hij inzet, in welke volgorde, en wanneer het werk hier als afgewerkt telt.

Ze vullen elkaar aan. Een MCP-server ontsluit jullie datawarehouse; een skill legt vast dat elke nieuwe meting een omschrijving krijgt, getest wordt tegen de cijfers van vorige maand en pas oplevert nadat de naamgeving nagekeken is. Tools zonder werkwijze betekent dat de agent zelf iets verzint. Werkwijze zonder tools betekent dat hij niets heeft om mee te werken.

Jullie manier van werken vastleggen

Voor een klein team zit de winst niet in de documentvoorbeelden waarmee de leveranciers uitpakken. Ze zit in het opschrijven van wat iedereen al weet maar niemand ooit heeft uitgetypt.

Neem jullie rapportagestandaard. Er bestaan afspraken over hoe een Power BI-model eruitziet: stervormig model, metingen in een aparte tabel, geen impliciete metingen, een datumtabel die als dusdanig gemarkeerd staat, Nederlandse veldnamen in het financiële model en Engelse elders. Die kennis zit meestal in het hoofd van wie het vorige model bouwde. Als skill staat ze in een bestand en past elke agentrun ze toe, ook wanneer niemand eraan denkt om ernaar te vragen.

Hetzelfde geldt voor een checklist bij een nieuwe klant, de naamgeving van jullie pipelines, de formulering van de verwerkersovereenkomst of de manier waarop jullie commits schrijven. Elk daarvan is een klein mapje. Voor geen enkel moet er iets hertraind worden, en elk is in een minuut bijgewerkt wanneer de afspraak verandert.

Omdat een skill een gewoon bestand is, komt hij ook gewoon in versiebeheer terecht. Je ziet achteraf wanneer de standaard wijzigde en door wie, en dat is meer opvolging dan de meeste interne procedures ooit krijgen.

Waar moet je op letten bij het gebruik van een agent skill

Behandel een skill als software die je installeert. Een skill mag de agent code laten uitvoeren en tools laten aanroepen. Anthropic raadt aan om enkel skills te gebruiken van bronnen die je vertrouwt, en om elk meegeleverd bestand na te kijken voor je er eentje van elders binnenhaalt. Skills die inhoud van externe adressen ophalen verdienen extra aandacht, want in wat terugkomt kunnen instructies verstopt zitten.

Een vage beschrijving betekent dat de skill nooit afgaat. "Helpt met rapporten" geeft de agent niets om op te matchen. Benoem de situatie en de woorden die een collega echt zou gebruiken, anders blijft het mapje ongelezen liggen.

Laat SKILL.md geen handleiding worden. De tekst wordt volledig ingelezen zodra de skill afgaat, dus een bestand van duizend regels haalt de hele opzet onderuit. Zet de details in references/ en laat de agent het stuk halen dat hij nodig heeft.

FAQ over agent skills

1. Werkt een skill ook buiten Claude?
Ja. Anthropic gaf het formaat eind 2025 vrij als open standaard op agentskills.io. Onder meer GitHub Copilot, VS Code, Cursor, Gemini CLI en OpenAI Codex lezen dezelfde mapstructuur.

2. Verhuist een skill mee tussen tools?
Het formaat is overdraagbaar, de installatie niet. In Claude Code staat een skill gewoon op schijf, via de API laad je hem op naar een workspace, en in de chatomgeving hangt hij aan één account vast. Dezelfde map, drie keer plaatsen.

3. Hoeveel skills mag ik installeren?
Er is geen vast plafond. Zolang elke beschrijving één zin blijft, betaal je per skill ongeveer honderd tokens tot hij effectief gebruikt wordt. De praktische grens ligt eerder bij de agent die uit twintig gelijkende beschrijvingen de juiste moet kiezen, dus schrijf ze scherp genoeg om uit elkaar te houden.