Een MCP-toolbeschrijving is een zin die aan één aanroepbare functie hangt: wat
hij doet, wat hij aanneemt, of hij iets verandert. Hij reist mee met elk verzoek
dat de client naar het model stuurt, naast de beschrijving van elke andere tool.
Een skill is een map met daarin een SKILL.md-bestand met een procedure — doe
dit, controleer dan dat, vraag het na voordat u dat andere doet — en de inhoud
daarvan wordt pas geladen zodra het model besluit dat uw verzoek erbij past.
Dat is het hele verschil, en het gaat over wanneer de tekst in de context staat, niet over wat de tekst zegt. Beschrijvingen zijn het entreegeld: u betaalt voor allemaal, bij elke beurt, voor altijd. De instructies van een skill zijn gratis totdat ze ter zake doen. Daarom is een alinea die in een toolbeschrijving onverdedigbaar zou zijn — driehonderd woorden over hoe u een stapel opgenomen vergaderingen wegwerkt — in een skill volstrekt redelijk.
Dit artikel gaat over de vraag welke instructie waar hoort. Is het protocol zelf nieuw voor u, dan behandelt wat een MCP-server is eerst het vocabulaire, en MCP versus plug-ins en integraties laat zien waar MCP staat ten opzichte van de oudere manieren om dingen te koppelen.
In de MCP-specificatie heeft een tooldefinitie een kleine, vaste vorm. Ze draagt
een name, een optionele voor mensen leesbare title, een description, een
inputSchema dat de argumenten beschrijft, een optioneel outputSchema en
annotations — optionele eigenschappen die het gedrag van de tool beschrijven,
bijvoorbeeld of hij alleen leest. De client haalt de hele lijst op met een
tools/list-aanroep en legt die voor aan het model; dat is wat MCP-tools
modelgestuurd maakt: het model kiest er een op basis van het gesprek.
Die vorm is precies in één ding goed: een model vertellen wat één aanroep doet, zodat het de juiste kiest. In drie andere dingen is ze structureel slecht.
Ze kan geen volgorde beschrijven. Niets in een tooldefinitie kan zeggen:
"roep list_channels aan vóór share_to_channel, want het kanaal moet bestaan
en de gebruiker moet het kiezen". Elke beschrijving is een eiland.
Ze kan niet veel bevatten. Elke beschrijving staat in de context bij elk verzoek in elk gesprek, ook in alle gesprekken die die tool nooit zullen aanraken. Een server met vijftien tools en een alinea per tool heeft een merkbaar deel van het contextvenster uitgegeven voordat de gebruiker iets heeft getypt.
Ze kan uw oordeel niet vastleggen. "Label de opname in plaats van hem te delen zolang niet duidelijk is wie hem mag zien" is beleid, niet de beschrijving van een functie. Twee verschillende teams zouden van dezelfde tool twee verschillende regels willen.
Het protocol kent één overdrukventiel: een server mag bij het verbinden een
instructions-tekst teruggeven, die de client aan de systeemprompt mag
toevoegen — vóór de toollijst. Dat is de juiste plek voor een korte oriëntatie:
wat deze server is, waar hij aan vastzit, waar u voorzichtig mee moet zijn. Twee
kanttekeningen. Het blijft tekst per sessie, dus hij blijft kort. En de
specificatie zegt dat clients het veld mogen gebruiken in plaats van dat ze
het moeten, dus of het daadwerkelijk aan het model wordt getoond verschilt per
client.
Een skill is een map met een SKILL.md-bestand: YAML-frontmatter met een name
en een description, daarna instructies in markdown. Ernaast mag van alles
worden meegeleverd — scripts/ voor uitvoerbare code, references/ voor
uitgebreide documentatie, assets/ voor sjablonen — en de agent haalt die er
alleen bij wanneer de instructies hem erheen sturen.
Het laadmodel heet progressive disclosure, geleidelijke onthulling, en de specificatie legt het in drie fasen uit:
name en de
description van elke beschikbare skill — begroot op ongeveer 100 tokens per
skill. Genoeg om te weten wanneer ze van pas kan komen, en meer niet.SKILL.md in de context. De aanbeveling is om onder
ongeveer 5.000 tokens te blijven, en het hoofdbestand onder 500 regels.De kosten van twintig geïnstalleerde skills zijn dus twintig korte beschrijvingen. De kosten van twintig lange toolbeschrijvingen zijn twintig lange toolbeschrijvingen, bij elke beurt. Die asymmetrie is de reden dat deze laag bestaat.
Het formaat is niet clientgebonden. Agent Skills is ontwikkeld door Anthropic en
uitgebracht als open standaard, gepubliceerd op agentskills.io; de
clientvitrine daar noemt tientallen producten die dezelfde map lezen, waaronder
Claude Code, Claude, ChatGPT en Codex, Cursor, VS Code, GitHub Copilot, Gemini
CLI, Goose, Roo Code, Kiro, Junie, Amp, Factory, Tabnine, Snowflake Cortex Code
en Databricks Genie Code. Gecontroleerd op 14 augustus 2026.
De verplichte frontmatter is bewust dun. name mag tot 64 tekens lang zijn, met
kleine letters, cijfers en koppeltekens, en moet gelijk zijn aan de naam van de
bovenliggende map. description mag tot 1.024 tekens lang zijn en hoort zowel te
zeggen wat de skill doet als wanneer u haar gebruikt — want die tekst is de
hele basis waarop een agent besluit het bestand te openen. Optionele velden zijn
license, compatibility, metadata en het experimentele allowed-tools.
Dat beschrijvingsveld verdient meer zorg dan het meestal krijgt. "Helpt met vergadernotities" zal nooit betrouwbaar ergens bij passen; "beoordeelt en archiveert recente opnamen — labelt ze, benoemt de sprekers, deelt de opnamen die in een teamkanaal thuishoren; te gebruiken wanneer de gebruiker vraagt om opruimen, sorteren of bijwerken" wel.
Tussen beschrijvingen per aanroep en skills op afroep zit een laag die geen van beide is: bestanden die een agent aan het begin van een sessie leest, ongeacht wat u hebt gevraagd.
AGENTS.md is de eenvoudigste variant — standaard markdown, geen verplichte velden, gelezen uit het dichtstbijzijnde bestand omhoog in de mappenboom. De eigen site meldt gebruik door ruim 60.000 opensourceprojecten en noemt ondersteuning in OpenAI Codex, Google Jules en Gemini CLI, Claude-agents, de coding agent van GitHub Copilot, Aider, VS Code, Cursor, Zed, Warp, Factory, goose, Roo Code, Devin en Junie. Gecontroleerd op 14 augustus 2026.
Cursor-regels zijn hetzelfde idee met een schakelaar erop. Ze staan in
.cursor/rules als .mdc-bestanden, en drie frontmatter-velden bepalen wanneer
een regel wordt meegenomen: alwaysApply: true zet hem in elke chatsessie; een
description laat de agent de relevantie beoordelen; globs koppelen hem aan
een geopend bestand dat past; en staat geen van die drie ingesteld, dan komt de
regel pas binnen wanneer u hem met @ noemt. Cursor ondersteunt ook AGENTS.md
en inmiddels rechtstreeks Agent Skills — skills staan in .cursor/skills/ of
.agents/skills/ — met een migratietool die geschikte dynamische regels en
slash-opdrachten omzet naar skills. Gecontroleerd op 14 augustus 2026.
Leest u die twee alinea's nog eens, dan is het patroon duidelijk: de formaten
zijn naar elkaar toe gegroeid, de laadmodellen niet. Iedereen leest inmiddels
SKILL.md. Maar een alwaysApply-regel en een blok in AGENTS.md gelden voor
de sessie, en een skill geldt voor de taak, en geen enkele formaatcompatibiliteit
verandert daar iets aan.
Het praktische gevolg is een vuistregel die meer waard is dan de formaatdetails:
| Waar het hoort | Wat erin thuishoort | Wat het kost |
|---|---|---|
description van een tool |
Eén zin: wat deze aanroep doet, wat hij verandert | Elk verzoek, voor altijd |
instructions van de server |
Een korte oriëntatie op de hele server | Elke sessie op deze server |
AGENTS.md, altijd toegepaste regels |
Feiten die gelden voor elke taak in deze repository | Elke sessie in dit project |
SKILL.md |
Procedures, beleid, uitgewerkte voorbeelden, oordeel | Alleen als de taak past |
Alles wat lang is, alles wat voorwaardelijk is, alles wat maar soms waar is:
skill. De valkuil waar mensen in lopen is honderdvijftig regels
productspecifieke procedure in een globale AGENTS.md zetten, waar ze in de
context blijven staan terwijl ze de hele middag aan een backend werken die er
niets mee te maken heeft.
Speak-Y levert een MCP-server mee, en dat is een aardige illustratie, omdat beide lagen zichtbaar verschillend werk doen.
De toolbeschrijvingen dekken de aanroepen: opnamen doorzoeken, een transcript,
een samenvatting of de actiepunten lezen, kanalen en labels opsommen — en, met
de app actief, een opname labelen, een spreker hernoemen, de titel wijzigen,
opnieuw laten transcriberen of in een teamkanaal opbergen. Elke aanroep draagt
een annotatie die zegt of hij leest of verandert; dat is wat een client in staat
stelt om te vragen voordat hij de veranderende aanroepen uitvoert, en wat
--read-only één schakelaar maakt in plaats van een lijst toolnamen om te
onthouden. Lezen gebeurt lokaal tegen de bibliotheek op uw eigen machine; de
veranderende opdrachten lopen via de draaiende app en worden daar gelogd, zoals
wat schrijftoegang via MCP veilig maakt
uitgebreider beschrijft.
De skill dekt het werk. Wanneer u de integratie installeert via
Instellingen → Integraties, schrijft Speak-Y een ordenende skill naast de
serverconfiguratie: waar te beginnen bij een stapel opnamen, wanneer een label
het juiste antwoord is en wanneer een kanaal, welke acties eerst bevestigd
moeten worden. Beschrijvingen kunnen dat niet bevatten, en de
instructions-tekst van de server hoort dat niet te proberen.
Ze is ook geschreven op de manier die het laadmodel beloont. Eén uitgewerkt
bestand staat op één plek, en elke client krijgt daar een korte verwijzing naar
in het formaat dat die client leest — een SKILL.md voor Claude Code, een
.mdc-regel voor Cursor, een gemarkeerd blok in AGENTS.md voor Codex, een
gemarkeerd blok in GEMINI.md voor Gemini CLI. De clients met sessiebereik
krijgen juist een verwijzing omdát ze sessiebereik hebben: honderdvijftig regels
over vergadernotities horen niet in het geheugen te staan terwijl u de backend
van iemand anders debugt. De blokken staan tussen markeringen, zodat opnieuw
installeren alleen die sectie vervangt en de rest van het bestand met rust laat.
De MCP-server zelf is gratis op elk abonnement, ook op Free. De installatie met één klik en de handmatige configuratie per client staan beschreven onder AI-assistenten (MCP).
Drie vragen, in deze volgorde.
Beschrijft de instructie één aanroep? Dan is het een toolbeschrijving, en hoort ze in één of twee zinnen te passen. Merkt u dat u aan een derde begint, dan hebt u een skill gevonden.
Geldt ze voor elke sessie, ongeacht de taak? Dan kan ze in AGENTS.md of in
een altijd toegepaste regel — maar controleer het deel "ongeacht de taak"
eerlijk. "Deze repository gebruikt pnpm" telt. "Dit is ons proces voor het
sorteren van vergaderingen" niet.
Beschrijft ze een procedure met stappen, keuzes of uitzonderingen? Skill.
Leg de naam en de beschrijving langs een strenge meetlat, want die twee teksten
doen al het routeren, en zet alles wat lang is in een bestand in references/
naast de SKILL.md in plaats van erin.
Gaat het mis in de goedkope richting, dan heeft uw agent een opgeblazen context en een lagere trefkans bij elke vraag die er niets mee te maken heeft. Gaat het mis in de dure richting — procedure geperst in toolbeschrijvingen — dan leest het model uw beleid bij elke beurt en volgt het het misschien alsnog niet, omdat een beschrijving wordt gelezen als documentatie van een functie, niet als een op te volgen instructie.
Wilt u het verschil concreet zien, dan is de snelste proef om één skill te schrijven voor een klus die u echt herhaalt, en die te vergelijken met de prompts die u eerder plakte. Prompts voor uw AI-assistent over uw vergaderingen zijn een redelijke bron van kandidaten: de prompts die u vaker dan twee keer gebruikt, zijn de prompts die in een bestand horen.
Een toolbeschrijving is één zin die bij één aanroepbare functie hoort, geschreven door de maker van de server en bij elk verzoek als onderdeel van de toollijst naar het model gestuurd. Een skill is een map met een SKILL.md-bestand waarin een procedure staat — meerdere stappen, meerdere tools, afwegingen — en alleen de naam en de beschrijving staan in de context totdat het model besluit dat de taak erbij past. Beschrijvingen beantwoorden de vraag wat deze aanroep doet; skills beantwoorden de vraag hoe u deze klus uitvoert.
Niet voor taken van één aanroep. U hebt er een nodig wanneer een klus meerdere tools in een bepaalde volgorde kost, wanneer de juiste keuze tussen twee tools afhangt van context die de beschrijvingen niet kunnen meedragen, of wanneer u dezelfde procedure in elke sessie identiek herhaald wilt zien. Goede beschrijvingen maken elke afzonderlijke aanroep juist; een skill maakt een reeks aanroepen consistent.
Nee. Agent Skills is ontwikkeld door Anthropic en uitgebracht als open standaard, gepubliceerd op agentskills.io, en de clientvitrine daar noemt tientallen producten die het overnemen — waaronder Claude Code, ChatGPT en Codex, Cursor, VS Code, GitHub Copilot, Gemini CLI, Goose, Roo Code, Kiro, Junie en Factory. Gecontroleerd op 14 augustus 2026.
AGENTS.md is gewone markdown zonder verplichte velden, die een agent leest uit het dichtstbijzijnde bestand omhoog in de mappenboom, en die voor de hele sessie wordt geladen ongeacht wat u hebt gevraagd. De inhoud van een skill wordt pas geladen nadat de agent uw verzoek bij de beschrijving heeft laten passen. Beide zijn nuttig, maar alles wat lang is hoort in een skill, omdat de inhoud van AGENTS.md in elke sessie context inneemt, ook in de sessies die er niets mee te maken hebben.
De specificatie van Agent Skills raadt aan het hoofdbestand SKILL.md onder 500 regels en onder ongeveer 5.000 tokens te houden, en uitgebreid naslagmateriaal naar aparte bestanden te verplaatsen die de agent alleen laadt wanneer hij ze nodig heeft. Voor de naam en de beschrijving staat ongeveer 100 tokens begroot, want dat is wat elke sessie betaalt.