Wat is een agent skill precies? Uitleg en werking
Ontdek hoe een agent skill werkt via een SKILL.md bestand en scripts. Leer waarom dit efficiënter is dan één grote prompt en hoe het verschilt van het MCP protocol.
Wat een agent skill daadwerkelijk is
Een agent skill is een map op de schijf met daarin een bestand genaamd SKILL.md. Dat bestand bevat een naam, een korte beschrijving en instructies geschreven in platte markdown. De agent laadt de beschrijving bij het opstarten en leest de instructies alleen wanneer uw verzoek overeenkomt met die beschrijving of wanneer u de skill bij naam aanroept. Vrijwel alles wat verder over skills te zeggen valt, vloeit voort uit deze twee zinnen.
De map kan meer bevatten dan alleen dat ene bestand. De Agent Skills-specificatie benoemt drie optionele mappen: scripts/ voor code die de agent uitvoert, references/ voor documenten die hij leest wanneer dat nodig is, en assets/ voor sjablonen en data. Geen van deze is verplicht. Een map met niets anders dan een SKILL.md is een volledige skill.
restore-drill/
SKILL.md
references/retention-policy.md
scripts/verify_snapshot.shDe beschrijving is het onderdeel dat mensen onderschatten. Het is de enige tekst die de agent ziet voordat hij besluit of hij de skill überhaupt opent. Daarom moet erin staan wat de skill doet en wanneer deze gebruikt moet worden, in de bewoordingen die een persoon daadwerkelijk zou typen.
Waarom een skill bijna niets kost totdat deze wordt gebruikt
Dit is het argument dat het begrijpen van dit formaat waardevol maakt; het draait om context, niet om functies. Het laden gebeurt in fasen, wat de specificatie progressieve onthulling noemt.
Bij het opstarten laadt de agent de name en description van elke geïnstalleerde skill en niets anders. De Agent Skills-specificatie stelt dit op ongeveer 100 tokens per skill (gepubliceerde richtlijnen, per oktober 2026). Installeer een dozijn skills en u heeft ongeveer de context van één lange alinea verbruikt.
Wanneer een verzoek overeenkomt met een beschrijving, leest de agent de body van die ene SKILL.md. De specificatie adviseert om de body onder de 5.000 tokens en het bestand onder de 500 regels te houden. Bestanden in references/ en scripts/ kosten op dit punt nog steeds niets. Een referentiebestand wordt alleen geladen als de instructies de agent ernaartoe sturen. Een gebundeld script werkt weer anders: de agent voert dit uit via de shell, waardoor de broncode van het script nooit in het contextvenster terechtkomt en alleen de output ervan wel.
Vergelijk dit nu met de methode waar mensen als eerste naar grijpen: één enorme prompt. Elke regel in een systeemprompt of een permanent actief instructiebestand wordt bij elk verzoek betaald, in elke sessie, ongeacht of de taak dit vereist of niet, en het concurreert om aandacht met de eigenlijke vraag. Tienduizend tokens aan vaste instructies is een rekening die u zelfs betaalt om te vragen hoe laat het is. Een dozijn skills kost ongeveer 1.200 tokens vóór activering, maar geladen instructies kunnen in de context blijven voor latere taken in hetzelfde gesprek. Dat is het volledige argument voor skills, en het is de reden waarom een kleine bibliotheek beter is dan een langere prompt.
Eén kanttekening brengt mensen in verwarring. In Claude Code blijft de body van een skill, zodra deze is geladen, in het gesprek gedurende latere beurten, dus een lange SKILL.md is een terugkerende kost en geen eenmalige. Compacting kan geladen skill-inhoud inkorten of verwijderen. Het verplaatsen van details naar references/ is geen kwestie van netheid. Het is het mechanisme dat werkt zoals ontworpen.
Een agent-skill is geen tool-call
Een tool, ook wel een function call genoemd, is iets wat het model kan aanroepen. De harness stuurt het model een schema: een naam, een beschrijving en de structuur van de argumenten. Het model genereert een aanroep, uw code voert deze uit en het resultaat komt terug als een bericht. Tools voeren acties uit. Beide helften van die uitwisseling behoren tot de harness, het programma dat de lus rondom het model uitvoert, wat tevens de component is die bij het opstarten uw skill-beschrijvingen leest en bepaalt wanneer er een moet worden geopend.
Een skill voert uit zichzelf niets uit. De agent leest de skill en handelt vervolgens met de tools die hij al bezat. Claude Code accepteert argumenten wanneer een skill wordt aangeroepen en voegt deze in de instructies in via placeholders zoals $ARGUMENTS. Wat een skill kan doen, is het model vertellen welke tools het moet gebruiken, in welke volgorde, en wat er daarna gecontroleerd moet worden. Een taak overdragen aan een tweede agent is het duidelijkste voorbeeld: één Claude Code-sessie kan al berichten sturen naar een andere, en de skill is de plek waar u vastlegt wanneer dat zinvol is en wat er verzonden moet worden.
Kort samengevat: een tool geeft een agent een nieuwe vaardigheid, en een skill geeft de agent vooral beoordelingsvermogen over vaardigheden die hij al heeft. Wanneer een skill wel een vaardigheid toevoegt, gebeurt dit via een gebundeld script dat de agent uitvoert met de shell waarover hij al beschikte. Als een stap elke keer een exact, gevalideerd resultaat moet opleveren, heeft u een tool of een script nodig. Als een stap vereist dat hetzelfde denkproces consistent wordt toegepast, heeft u een skill nodig. Een skill kan louter uit beoordelingsvermogen bestaan en toch de skill zijn die u het vaakst gebruikt, zoals Ponytail, dat een coding agent dwingt om de kleinst mogelijke wijziging door te voeren die werkt laat zien: het voegt geen nieuwe mogelijkheden toe en verandert alleen hoe de agent de bestaande vaardigheden inzet. Dat beoordelingsvermogen kan ook de andere kant op werken, en de unlazy-skill, die een Depth Tree doorloopt om te voorkomen dat een agent een taak voortijdig als voltooid markeert is dezelfde truc, gericht op grondigheid in plaats van terughoudendheid.
Een agent-skill is geen MCP-server
MCP (model context protocol) is een protocol om een agent te verbinden met een extern systeem. Een MCP-server is een proces dat draait, dat protocol spreekt en tools beschikbaar stelt aan de agent. Dit vereist doorgaans configuratie, inloggegevens en ofwel een lokaal commando of een netwerk-endpoint. Een skill is een map met daarin een markdown-bestand. Er is geen proces, geen poort en geen protocol.
De contextkosten verschillen op dezelfde manier. Elke tool die een MCP-server aanbiedt, bevat een naam, een beschrijving en een argumentschema. In een client die deze vooraf inlaadt, blijven deze gedurende de hele sessie in het verzoek staan, ongeacht of ze worden gebruikt. Claude Code werkt standaard niet langer op die manier: sinds oktober 2026 staat de tool-zoekfunctie standaard ingeschakeld. Hierdoor worden bij de start van de sessie alleen de toolnamen en serverinstructies geladen, terwijl de volledige definities pas worden opgehaald wanneer Claude ernaar zoekt. Een skill in ruststand is slechts één regel tekst.
Beide zijn complementair aan elkaar en de krachtigste configuraties gebruiken beide. De MCP-server biedt de toegang. De skill biedt de procedure: welke van die tools moeten worden aangeroepen voor de werkelijke workflow van uw team, in welke volgorde, en wat een goed resultaat inhoudt. Als u uw eigen servers host, behandelt het draaien van MCP-servers op een VPS dat aspect.
Een agent-skill is geen system prompt of een AGENTS.md
Beide zijn instructies in markdown, dus deze verwarring is begrijpelijk. Het verschil zit in het moment van laden. De system prompt en projectinstructies die bij het opstarten worden geladen, staan altijd aan; geneste AGENTS.md en CLAUDE.md bestanden laden wanneer de agent in hun mappen werkt. Een skill wordt op aanvraag geactiveerd. De outputstijlen van Claude Code bevinden zich aan het uiterste einde van het 'altijd aan'-spectrum, omdat het kiezen van een stijl de system prompt zelf aanpast, waardoor het elk antwoord in de sessie vormgeeft, inclusief de antwoorden waar geen enkele skill bij betrokken is.
De test is één vraag: zou het negeren van deze paragraaf fout zijn bij een taak die er niets mee te maken heeft? Huisstijl, het build-commando en de regel voor branch-naamgeving zijn van toepassing op elke taak, dus deze horen thuis in het 'altijd aan'-bestand, waar het laden bij elke actie juist de bedoeling is. De release-checklist die u twee keer per maand uitvoert, is niet op elke taak van toepassing en hoort daarom in een skill thuis. Wanneer een sectie van uw 'altijd aan'-bestand is uitgegroeid tot een genummerde procedure, is dat het signaal om deze te verplaatsen.
Deze bestanden hebben hun eigen conventies die het waard zijn om correct toe te passen. Zie wat in AGENTS.md thuishoort en wat in het menselijke bestand thuishoort en een design.md die de structuur van een codebase uitlegt voor de twee die wij gebruiken.
Hoe een minimale skill eruitziet
In Claude Code bevinden persoonlijke skills zich in ~/.claude/skills/<name>/SKILL.md en zijn deze van toepassing op al uw projecten op die machine, maar niet op Cowork- of cloud-sessies. Project-skills bevinden zich in .claude/skills/<name>/SKILL.md en worden naar git gecommit, zodat uw team ze ook ontvangt; cloud-threads in een Claude-project laden deze niet. GitHub Copilot en VS Code lezen project-skills uit .github/skills/ en .agents/skills/, evenals .claude/skills/. Het bestand daarin is hetzelfde bestand.
mkdir -p ~/.claude/skills/restore-drill---
name: restore-drill
description: Run a restic restore drill and report what was recovered. Use when the user asks to test backups, verify a restore, or check that a snapshot is readable.
---
# Restore drill
1. Run `restic snapshots` and pick the newest snapshot for the host in question.
2. Restore it into a scratch directory under `/tmp`, never over live data.
3. Compare the restored file count and total size against the snapshot summary.
4. Report the snapshot ID and anything that failed to restore.
If `restic snapshots` reports that it cannot open the config file, stop and report the full error instead of guessing the cause.Dat is een complete skill. De mapnaam wordt het commando dat u typt, dus deze is /restore-drill. In Claude Code toont het /skills-menu wat er is geïnstalleerd; dit is de snelste manier om te bevestigen dat het bestand is herkend. Als het ontbreekt in dat menu, controleer dan eerst de namen: het bestand moet SKILL.md heten, en de Agent Skills-specificatie vereist dat de naam bestaat uit kleine letters, cijfers en enkele koppeltekens, overeenkomend met de map. Dezelfde procedure, uitgeschreven als een stappenplan dat uw agent opnieuw kan uitvoeren, is een logische aanvulling op geplande restic-back-ups op een VPS, waarbij het uitvoeren van een back-up niet hetzelfde is als het herstellen ervan.
Wanneer een vaardigheid een script moet zijn
Elke stap die telkens hetzelfde juiste antwoord oplevert, moet een script zijn. De vaardigheid wordt dan gereduceerd tot een paar regels die aangeven wanneer het script uitgevoerd moet worden en hoe de output gelezen moet worden. Hiervoor zijn twee redenen, en beide zijn praktisch van aard.
Ten eerste komt de broncode van een script nooit in het contextvenster terecht. Een parser van 300 regels kost u alleen de output, terwijl dezelfde logica uitgeschreven als markdown-instructies bij elke keer dat de vaardigheid wordt geladen de volledige lengte kost.
Ten tweede geeft een script twee keer hetzelfde antwoord. Een model dat bij elke uitvoering opnieuw dezelfde log-parseerregel moet afleiden, zal deze op een slechte dag net iets anders formuleren, en u zult dit pas merken wanneer twee getallen niet met elkaar overeenstemmen.
Splits het werk daarom op basis van het type. "Parse de CSV en print elke rij waar het totaal niet overeenkomt met de individuele posten" is een script. "Bekijk de rijen die het script heeft geprint en leg uit welke eruitzien als een fout bij de gegevensinvoer" is een vaardigheidsinstructie. Het behouden van beoordelingsvermogen in markdown en determinisme in code is dezelfde discipline als het bouwen van een lus die een agent kan uitvoeren zonder dat u meekijkt.
Waarom wordt mijn skill nooit geactiveerd?
Omdat de description alleen beschrijft wat de skill doet en niet wanneer deze moet worden gebruikt. Die ene regel is alles waar de agent uw verzoek aan toetst. "Helpt bij databasewerkzaamheden" komt nergens specifiek mee overeen. "Voert een schema-migratie uit op de staging-database. Gebruik wanneer de gebruiker vraagt om een tabel te migreren, een kolom toe te voegen of een schema te wijzigen" bevat de woorden die een persoon daadwerkelijk typt, waardoor deze wel wordt geactiveerd.
Het tegenovergestelde probleem is een skill die constant wordt geactiveerd. Een beschrijving zoals "Gebruik voor alle codewijzigingen in deze repository" komt met alles overeen, waardoor de body bij elke taak wordt geladen en vervolgens in het gesprek blijft hangen tijdens latere interacties. Maak de beschrijving specifieker voor het beoogde gebruik. In Claude Code kunt u ook disable-model-invocation: true instellen in de frontmatter; dit voorkomt automatisch laden en houdt de skill beschikbaar wanneer u de naam ervan typt.
Het derde probleem is een skill die een tool dupliceert. Instructies die de agent opdragen om een API aan te curl die de MCP-server al aanbiedt, of om bestanden te doorzoeken met grep terwijl de omgeving al een zoektool heeft, zorgen voor een trager proces en twee sets instructies die met elkaar in conflict kunnen raken. Verwijder de dubbele instructie en beschrijf in plaats daarvan de intentie.
Gok niet welke van de drie problemen bij u speelt. Voer hetzelfde prompt twee keer uit in een nieuwe sessie: één keer met de skill beschikbaar en één keer uitgeschakeld, en vergelijk vervolgens de antwoorden. De nieuwe sessie is essentieel, omdat de sessie waarin u de skill schreef al alle informatie bevat die de skill zelf geeft, wat hiaten in de geschreven versie maskeert. De skill-creator-plugin van Anthropic automatiseert die vergelijking binnen Claude Code, inclusief het genereren van prompts die de skill wel en niet zouden moeten activeren en het meten hoe vaak dit gebeurt. Als de skill wel wordt geladen maar de agent alsnog niet doet wat er staat, ligt het probleem niet bij de beschrijving en zijn de redenen waarom een agent instructies negeert die hij al heeft gelezen de volgende plek om te onderzoeken.
Is dit een formaat van één leverancier of een standaard?
Anthropic publiceerde het formaat eind 2025 en bracht het vervolgens uit als een open standaard gehost op agentskills.io. Op 22 oktober 2026 kondigde Anthropic de overdracht van Agent Skills aan de Agentic AI Foundation onder de Linux Foundation aan. Sinds oktober 2026 definieert die specificatie de vereiste name en description velden, de optionele license, compatibility, metadata en allowed-tools velden, de drie optionele mappen en het gefaseerde laadgedrag. Het bevat ook een referentie-validator, zodat skills-ref validate ./my-skill een map controleert aan de hand van de specificatie voordat u deze deelt.
De lijst met clients is de echte graadmeter. Dezelfde map wordt onder andere gelezen door Claude Code, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands en opencode. Microsoft publiceert zijn eigen skills in dit formaat op github.com/microsoft/skills en levert een desktoptool genaamd Skill Recorder. Deze tool observeert u terwijl u een taak uitvoert, reconstrueert deze als een intentie met geordende stappen en schrijft het resultaat weg als een skill. Dat een leverancier een recorder bouwt waarvan het uitvoerformaat voldoet aan de specificatie van een ander, is een goed teken dat het formaat niet langer slechts een functie van één product is.
Wat u als eerste moet schrijven
Plan geen bibliotheek. Wacht tot u merkt dat u voor de derde keer dezelfde instructies in een chat plakt; verplaats die tekst dan naar een SKILL.md en verwijder de geplakte tekst. Herhaling die u zelf heeft ervaren, is de enige betrouwbare graadmeter voor een vaardigheid die het bewaren waard is. Een zoekprocedure is een goed begin, en een zoekvaardigheid ondersteund door uw eigen SearXNG-instantie laat zien hoe dit eruitziet.
Twee gewoontes houden de bibliotheek gezond. Lees elke vaardigheid die u niet zelf heeft geschreven voordat u deze installeert, inclusief scripts, omdat een vaardigheid bestaat uit instructies die uw agent zal volgen en code die deze kan uitvoeren: behandel het als het installeren van software van een onbekende. Houd inloggegevens buiten de map, aangezien een vaardigheid een tekstbestand is dat wordt gecommit en gedeeld. Geheimen weghouden bij uw agents beschrijft waar deze waarden thuishoren, en de routekaart voor het leren werken met agents dit jaar plaatst vaardigheden in de juiste volgorde ten opzichte van de rest van de configuratie.
FAQ
Wat is het verschil tussen een agent skill en een MCP server?
Een MCP (model context protocol) server is een actief proces dat tools via een protocol aan een agent aanbiedt. Dit vereist configuratie en inloggegevens. De volledige definitie van de tools neemt context in beslag voor de gehele sessie, tenzij de client deze uitstelt, zoals Claude Code nu standaard doet. Een agent skill is een map met een SKILL.md-bestand, zonder proces of protocol. Dit kost ongeveer 100 tokens totdat de agent besluit het te lezen. Gebruik een MCP server om een agent toegang te geven tot een systeem. Gebruik een skill om de agent de procedure te leren hoe die toegang effectief wordt gebruikt. Veel configuraties gebruiken beide.
Werken agent skills alleen met Claude Code?
Nee. Anthropic heeft het formaat ontwikkeld en vervolgens als open standaard uitgebracht op agentskills.io. Dezelfde map wordt gelezen door Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Goose, OpenHands en andere clients. Het verschil zit in de locatie waar elke client zoekt en welke aanvullende frontmatter-velden worden ondersteund. Claude Code leest ~/.claude/skills/ en .claude/skills/, terwijl GitHub Copilot en VS Code .github/skills/, .claude/skills/ of .agents/skills/ in de repository lezen. Het SKILL.md-bestand zelf is uitwisselbaar tussen deze clients.
Hoeveel skills kan ik installeren voordat het systeem trager wordt?
De beperking is het opstartbudget, niet het aantal. Elke geïnstalleerde skill draagt bij aan de context met zijn naam en beschrijving, wat volgens de gepubliceerde specificaties ongeveer 100 tokens kost. Dertig skills kosten dus ongeveer 3.000 tokens voordat er ook maar één wordt gebruikt. Wat als eerste verslechtert is de matching, niet de snelheid: veel skills met overlappende beschrijvingen maken het voor het model lastiger om de juiste te kiezen. Schrijf beschrijvingen die elkaar niet overlappen en verwijder de skills die u niet meer gebruikt.
Moet deze instructie in een skill of in AGENTS.md staan?
Vraag uzelf af of de instructie van toepassing is op elke taak in de repository. Build-commando's, huisstijl en naamgevingsregels zijn op alles van toepassing en horen daarom in het altijd actieve bestand, waar het laden bij elke sessie het doel is. Een procedure die u incidenteel uitvoert, zoals een checklist voor een release of een herstelprocedure, moet een skill zijn. Hierdoor kost het slechts de beschrijving van één regel voordat deze wordt geactiveerd. Zodra deze in Claude Code is geladen, blijven de instructies in het gesprek behouden gedurende latere interacties, ook bij niet-gerelateerde taken. Een sectie in AGENTS.md die is uitgegroeid tot genummerde stappen, is meestal een skill die wacht om verplaatst te worden.