Wat is een agent-skill precies?

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. 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.sh

De 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 de beschrijving aangeven 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 de moeite waard 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 augustus 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 wordt verwerkt.

Vergelijk dit nu met de methode waar mensen als eerste naar grijpen: één enorme prompt. Elke regel in een systeem-prompt of een permanent actief instructiebestand wordt bij elk verzoek betaald, in elke sessie, of de taak het nu nodig heeft 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 in ruststand en breidt alleen uit voor de specifieke taak die ze nodig heeft. Dat is het volledige argument voor skills, en het is de reden waarom een kleine bibliotheek beter is dan een langere prompt.

Eén waarschuwing waar mensen vaak tegenaan lopen: zodra een skill is geladen, blijft de body in de context voor de rest van de sessie. Een lange SKILL.md is dus een terugkerende kost en geen eenmalige. Het verplaatsen van details naar references/ is geen kwestie van opruimen. 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.

Een skill voert uit zichzelf niets uit. De agent leest de skill en handelt vervolgens met behulp van de tools die hij al bezat. Het model kan geen argumenten doorgeven aan een skill op de manier waarop het argumenten doorgeeft aan een tool. Wat een skill wel kan, is het model vertellen welke tools het moet gebruiken, in welke volgorde en wat er daarna gecontroleerd moet worden.

Kort gezegd: een tool geeft een agent een nieuwe vaardigheid, en een skill geeft de agent beoordelingsvermogen over een vaardigheid die hij al heeft. 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 meest gebruikte methode zijn, zoals Ponytail, dat een coding-agent dwingt om de kleinst mogelijke werkende wijziging door te voeren laat zien: het voegt geen nieuwe functionaliteit toe en verandert alleen de manier waarop de agent de bestaande vaardigheden inzet.

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. Standaard bevinden deze zich gedurende de gehele sessie in het verzoek, ongeacht of ze worden gebruikt. Sommige clients zijn begonnen met het op aanvraag ophalen van tool-schema's, maar het vooraf laden ervan is nog steeds de standaard. Een skill in ruststand is slechts één regel tekst.

Beide zijn complementair en de krachtigste opstellingen gebruiken ze allebei. 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 server 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. AGENTS.md, CLAUDE.md en de system prompt staan altijd aan. Een skill wordt op verzoek geladen.

De test is één vraag: zou het negeren van deze paragraaf fout zijn bij een taak die er niets mee te maken heeft? De huisstijl, het build-commando en de regel voor branch-naamgeving zijn van toepassing op elke taak, dus deze horen thuis in het altijd actieve 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 actieve 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 hoort in AGENTS.md en wat hoort in het menselijke bestand en een design.md dat 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 ze van toepassing op al uw projecten. Project-skills bevinden zich in .claude/skills/<name>/SKILL.md en worden naar git gecommit, zodat elke persoon en elke agent die in die repository werkt erover beschikt. GitHub Copilot en VS Code lezen workspace-skills in plaats daarvan uit .github/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` prints `Fatal: unable to open config file`, the repository path or the password is wrong. Stop and report that instead of guessing.

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, is een naam onjuist: het bestand moet SKILL.md heten en de mapnaam mag alleen bestaan uit kleine letters, cijfers en enkele koppeltekens. Dezelfde procedure, geschreven 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 terugzetten 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 beschrijft wat de skill doet, maar 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 de rest van de sessie in de context blijft staan. 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 al door de MCP-server wordt aangeboden, 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 het doel.

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 heeft geschreven al alle informatie bevat die de skill zelf geeft, wat de tekortkomingen 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 van de frequentie waarmee dit gebeurt.

Is dit het formaat van één leverancier of een standaard?

Anthropic publiceerde het formaat eind 2025 en bracht het vervolgens uit als een open standaard die wordt gehost op agentskills.io. Sinds augustus 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 het echte signaal. 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 plus geordende stappen en schrijft het resultaat weg als een skill. Een leverancier die een recorder bouwt waarvan het uitvoerformaat toebehoort aan de specificatie van iemand anders, 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 draaiend proces dat tools via een protocol aan een agent aanbiedt. Dit vereist configuratie en inloggegevens, en de tooldefinities nemen doorgaans de hele sessie lang context in beslag, ongeacht of ze worden gebruikt. Een agent skill is een map met een SKILL.md-bestand, zonder proces of protocol. Het 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 benut. 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 extra frontmatter-velden deze ondersteunt. Claude Code leest ~/.claude/skills/ en .claude/skills/, terwijl GitHub Copilot en VS Code .github/skills/ in de repository lezen. Het SKILL.md-bestand zelf is uitwisselbaar zonder wijzigingen.

Hoeveel skills kan ik installeren voordat het systeem trager wordt?

De beperking is het opstartbudget in plaats van het aantal. Elke geïnstalleerde skill draagt bij met zijn naam en beschrijving, ongeveer 100 tokens volgens de gepubliceerde richtlijnen van de specificatie. 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 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 actie juist de bedoeling is. Een procedure die u incidenteel uitvoert, zoals een checklist voor een release of een herstelprocedure, moet een skill zijn. Zo kost het niets bij taken waarvoor het niet nodig is. Een sectie in AGENTS.md die is uitgegroeid tot genummerde stappen, is meestal een skill die wacht om verplaatst te worden.