Hoe schrijf ik een eigen agent skill?

Schrijf uw eigen agent-skill op basis van een reële fout

De beste manier om uw eigen agent-skill te schrijven, is door deze te distilleren uit een reële fout. Zoek een taak die uw coding agent twee keer foutief heeft uitgevoerd, noteer de correctie die u beide keren heeft ingevoerd en sla die correctie op als een SKILL.md-bestand dat de agent zelf kan laden. Alles daarna is mechanisch: de bestandsindeling en de ene regel die bepaalt of de skill ooit wordt geactiveerd.

Die volgorde is van belang. Een skill die vanuit de verbeelding is geschreven, documenteert een probleem dat u nooit heeft gehad en kost in elke sessie context. Een skill die is gedistilleerd uit een fout die u heeft waargenomen, wordt geleverd met een eigen test: vraag hetzelfde opnieuw en kijk of de agent het deze keer wel goed doet. Als het formaat zelf nieuw voor u is, lees dan eerst wat agent-skills zijn en hoe een agent deze laadt, en kom daarna terug om er een te schrijven.

Begin bij een taak die de agent twee keer fout heeft gedaan

Eén keer is toeval. Twee keer is een patroon, en een patroon is een bestand waard.

Hier is een fout die zich op echte servers herhaalt. U vraagt de agent om een reverse proxy-blok toe te voegen aan Nginx. Deze bewerkt /etc/nginx/conf.d/app.conf en voert vervolgens sudo systemctl restart nginx uit. De bewerking bevat een typefout, waardoor Nginx weigert te starten en de site offline is totdat u dit herstelt:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

U corrigeert dit in de chat. Test de configuratie met sudo nginx -t voordat u de service aanraakt, en pas deze vervolgens toe met reload in plaats van restart. Een week later, bij een andere taak, maakt de agent dezelfde fout. Die tweede keer is het signaal.

Noteer twee dingen terwijl de fout nog voor u ligt: het verzoek dat u typte en de correctie die u gaf, in de woorden die u gebruikte. Die twee regels worden de vaardigheid. Het verzoek vertelt u waaraan de trigger moet voldoen. De correctie is de volledige inhoud.

De eigen richtlijnen voor auteurs van Anthropic plaatsen dit op de eerste plaats. Laat de agent representatieve taken uitvoeren zonder vaardigheid, noteer waar het misgaat en schrijf vervolgens de minimale instructies die deze fouten herstellen. De fouten vormen de specificatie; een vaardigheid die u niet kunt herleiden naar een fout is meestal een vaardigheid die niemand nodig had.

Voor een uitgewerkt voorbeeld van dezelfde distillatie kunt u Ponytail die één herhaalde fout, een agent die veel meer herschrijft dan u vroeg, omzet in een vaardigheid van begin tot eind lezen voordat u uw eigen vaardigheid schrijft.

De anatomie van een skill

Een skill is een map met daarin één verplicht bestand.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md opent met een frontmatter-blok, een aantal instellingen geschreven in YAML (hetzelfde configuratieformaat dat Docker Compose-bestanden gebruiken) tussen ----markers, gevolgd door de instructies in markdown. Hieronder staat de volledige skill voor de bovenstaande fout.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

Dat bestand is minder dan twintig regels lang en vormt een complete skill. De onderdelen:

• name: maximaal 64 tekens, uitsluitend kleine letters, cijfers en koppeltekens; het mag niet de woorden claude of anthropic bevatten. In een persoonlijke of project-skill is dit enkel het weergavelabel. Het commando dat u typt is afgeleid van de mapnaam, dus deze reageert op /nginx-config-changes.
• description: wat de skill doet en wanneer u deze gebruikt, maximaal 1.024 tekens. Deze regel voert het eigenlijke werk uit en de volgende sectie gaat uitsluitend hierover.
• De body: de instructies, die alleen worden geladen wanneer de skill daadwerkelijk wordt geactiveerd.
• reference/: extra bestanden die de agent op verzoek leest. Link ernaar vanuit SKILL.md en houd de links op één niveau diep, omdat een bestand dat wordt verwezen vanuit een ander verwezen bestand vaak slechts gedeeltelijk wordt gelezen.
• scripts/: bestanden die de agent uitvoert in plaats van leest. Alleen de output hiervan kost context, dus een script van 300 regels is goedkoop.

Een skill groeit uit naar de volledige lay-out wanneer het gedrag dat deze corrigeert hardnekkig genoeg is om dit te vereisen, en de niet-luie skill besteedt die ruimte aan een Depth Tree, een set gates-bestanden en een PLAN.md-contract om te voorkomen dat een agent meldt dat het werk klaar is terwijl hele takken van het werk ongemoeid zijn gelaten.

De locatie van de map bepaalt wie de skill ontvangt.

• .claude/skills/<name>/SKILL.md in de repository: alleen dit project, en het gaat mee naar iedereen die de repo kloont.
• ~/.claude/skills/<name>/SKILL.md: elk project op uw machine, en van niemand anders.
• <plugin>/skills/<name>/SKILL.md: meegeleverd in een plugin, beschikbaar overal waar die plugin is ingeschakeld.

Maak er een aan met mkdir -p .claude/skills/nginx-config-changes en schrijf het bestand. Claude Code houdt deze mappen in de gaten, dus het bewerken van een bestaande skill heeft direct effect in de actieve sessie. Het aanmaken van een skills-map op het hoogste niveau die nog niet bestond toen de sessie begon, vereist een herstart, omdat er niets was om te monitoren toen de sessie startte.

Het beschrijvingsveld is de regel met de meeste impact in het bestand

Bij het opstarten laadt de agent de name en description van elke beschikbare skill in zijn context. De inhoud wordt niet geladen. Wanneer uw verzoek binnenkomt, vormt die ene regel de volledige basis voor de beslissing of deze skill relevant is. Een perfecte inhoud achter een vage beschrijving wordt dus nooit gelezen.

Schrijf de beschrijving in de derde persoon. "Test en herlaadt nginx veilig" werkt. "Ik kan u helpen met nginx" werkt niet, omdat de tekst in de systeemprompt wordt ingevoegd, waar de eerste persoon leest alsof het model over zichzelf spreekt.

Verwerk twee zaken in de beschrijving: wat de skill doet en onder welke voorwaarde deze van toepassing is. Plaats de belangrijkste use case vooraan, omdat Claude Code de lijstvermelding inkort op 1.536 tekens. Er is een optioneel when_to_use-veld voor extra triggerfrases en voorbeeldverzoeken; dit wordt onder diezelfde limiet aan de beschrijving toegevoegd.

Gebruik vervolgens de woorden die u daadwerkelijk zult typen. description: Helps with nginx komt met niets overeen, omdat niemand "helpt met" typt. De bovenstaande versie noemt /etc/nginx, server block, reverse proxy en TLS (transport layer security) certificate path, wat ongeveer de woordenschat is van elk verzoek dat de skill zou moeten activeren.

Dit is de test voor een beschrijving. Geef die ene regel aan iemand die de inhoud nog nooit heeft gezien, samen met het verzoek dat u van plan bent te typen, en vraag of de skill van toepassing is. Als zij het niet kunnen bepalen, kan het model dat ook niet.

Houd de body compact, omdat deze in de context blijft

Wanneer een skill wordt aangeroepen, wordt de gegenereerde inhoud onderdeel van het gesprek en blijft daar voor de rest van de sessie. Claude Code leest het bestand niet opnieuw in bij latere interacties. Elke regel die u schrijft, brengt kosten met zich mee voor de gehele sessie, niet slechts voor één antwoord.

Anthropic adviseert om SKILL.md onder de 500 regels te houden en details te verplaatsen naar afzonderlijke bestanden. Compaction laat zien waarom dat getal niet willekeurig is. Wanneer het gesprek wordt samengevat om context vrij te maken, koppelt Claude Code de meest recente aanroep van elke skill opnieuw, behoudt slechts de eerste 5.000 tokens van elk, en vult een gecombineerd budget van 25.000 tokens, beginnend bij de meest recent aangeroepen skill. Een lange skill wordt halverwege afgekapt. Meerdere lange skills verdringen elkaar volledig.

Schrijf daarom alleen wat het model nog niet weet. Het weet wat Nginx is en wat een reverse proxy doet. Het weet niet wat uw interne regel is over reload boven restart, en die regel is de enige reden dat dit bestand bestaat.

Als de skill de agent opdraagt een gebundeld script uit te voeren, specificeer het pad dan met ${CLAUDE_SKILL_DIR} zodat het wordt opgelost waar de skill ook is geïnstalleerd, en geef vooraf toestemming voor hetzelfde commando zodat de uitvoering niet stopt bij een autorisatievraag.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

De toestemming geldt voor de beurt waarin de skill werd aangeroepen en vervalt zodra u uw volgende bericht verstuurt, zodat het niet ongemerkt een permanente machtiging wordt.

Hoe u bewijst dat de skill wordt geactiveerd

Het observeren van het laden van een skill bevestigt dat de agent deze heeft gevonden. Het geeft echter niet aan of het antwoord is veranderd. Controleer beide aspecten en doe dit in een nieuwe sessie. De sessie waarin u de skill heeft geschreven, bevat namelijk nog alle context van uw schrijfproces. Die achtergebleven context maskeert eventuele tekortkomingen in het bestand.

1. Start een nieuwe sessie met claude in het project.
2. Typ het verzoek zoals u dat op een normale werkdag zou doen, in uw eigen woorden, zonder de naam van de skill te noemen.
3. Let op de aanroeping. Als de skill niet wordt geactiveerd, pas dan de beschrijving aan. De inhoud is op dit moment nog niet het probleem.
4. Roep de skill handmatig aan met /nginx-config-changes als controlemiddel. Correct gedrag bij handmatige aanroeping in combinatie met onjuist gedrag bij een verzoek, bevestigt dat er sprake is van een triggerprobleem in plaats van een instructieprobleem.
5. Voer hetzelfde verzoek uit met de skill uitgeschakeld en vergelijk de twee antwoorden. Markeer de skill in het /skills-menu, druk op Space om de status te wijzigen naar off en vervolgens op Enter om op te slaan. Dit schrijft een skillOverrides-vermelding naar .claude/settings.local.json. Druk nogmaals op Space om de status terug te zetten naar on wanneer u klaar bent.
6. Schrijf een aantal verzoeken die de skill niet zouden moeten activeren en controleer of deze inderdaad niet reageert.

Installeer de skill-creator-plugin vanuit de officiële marketplace om deze cyclus te automatiseren.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Als de installatie-output Run /reload-plugins to activate. aangeeft, voer dan dat commando uit. Vraag vervolgens aan Claude om uw skill op naam te evalueren. De plugin slaat testgevallen op in evals/evals.json binnen de skill-directory en voert elk geval uit in een eigen subagent, zodat elke uitvoering met een schone context begint. Vervolgens schrijft de plugin een vergelijking tussen de resultaten met en zonder de skill. Dit is het eerlijke cijfer: de verbetering in het slagingspercentage afgezet tegen de tokens en de tijd die de skill kost.

Een skill kan ook zijn eigen bewijslast met zich meedragen in plaats van dit over te laten aan een afzonderlijke evaluatie, zoals de Old Coder-skill doet wanneer deze de agent een bewijsrapport laat genereren dat u zelf opnieuw kunt uitvoeren.

Foutmodus: de skill wordt nooit geactiveerd

U voert het verzoek in, de agent voert de oude, onjuiste actie uit en er verschijnt geen skill-regel. Doorloop deze stappen in de juiste volgorde.

• De beschrijving vermeldt wat de skill doet, maar niet wanneer deze moet worden gebruikt, waardoor niets in uw verzoek overeenkomt.
• De beschrijving bevat niet de woorden die u typt. Als u "nginx" zegt, moet de beschrijving ook nginx bevatten.
• disable-model-invocation: true is ingesteld in de frontmatter. Hierdoor wordt de beschrijving volledig buiten de context van het model gehouden en is de skill alleen door u aanroepbaar met /name.
• Een paths glob in de frontmatter beperkt de activering tot overeenkomende bestanden, en het bestand waaraan u werkt komt niet overeen.
• De skill bevindt zich in een geneste .claude/skills/ directory onder uw startdirectory. Deze worden pas geladen nadat de agent een bestand in die subdirectory heeft gelezen of bewerkt; tot die tijd is de skill helemaal niet beschikbaar.

Foutmodus: de skill wordt constant geactiveerd

Het tegenovergestelde probleem is een beschrijving die zo breed is dat de skill bij irrelevante taken wordt geactiveerd. "Gebruik bij werkzaamheden aan de server" komt overeen met vrijwel elk verzoek in een server-repository. De body wordt vervolgens geladen voor taken waarbij de skill niet kan helpen, en deze blijft in de context voor de rest van de sessie.

Maak de beschrijving specifieker voor de voorwaarde die er werkelijk toe doet en benoem de bestanden of commando's die eronder vallen. Voeg een paths glob toe wanneer de skill alleen van toepassing is op bepaalde bestanden. Stel voor alles met bijwerkingen, zoals een deploy of een commit, disable-model-invocation: true in en roep deze zelf aan met /name, zodat de agent nooit zelfstandig beslist dat het een goed moment is om te deployen.

Foutmodus: de vaardigheid hoort thuis in uw regelsbestand

Een regelsbestand zoals CLAUDE.md of AGENTS.md wordt aan het begin van elke sessie geladen en is van toepassing op elke taak. De inhoud van een vaardigheid wordt alleen geladen wanneer de vaardigheid wordt geactiveerd. De frequentie is hierbij de doorslaggevende factor. Een feit dat voor elke taak in de repository geldt, zoals de pakketbeheerder die u gebruikt, hoort thuis in het regelsbestand. Een procedure die slechts op een klein deel van de taken van toepassing is, zoals de bovenstaande nginx-regel, hoort thuis in een vaardigheid, waar deze geen resources verbruikt op dagen dat niemand nginx bewerkt.

De werkelijke fout is om deze op beide plaatsen op te nemen. Twee kopieën gaan na verloop van tijd uiteenlopen, en wanneer de agent de verkeerde actie uitvoert, kunt u niet achterhalen welke kopie hij heeft gevolgd. Kies één vaste plek voor elke instructie. Een regel die al op precies één plek staat en toch wordt genegeerd, is een ander probleem. Het is de moeite waard om de mechanismen achter een genegeerde instructie te controleren voordat u deze naar een vaardigheid verplaatst in de hoop dat de verplaatsing het probleem oplost. de grens tussen vaardigheden, MCP-servers en regelsbestanden behandelt de complexere gevallen, inclusief situaties waarin de juiste oplossing een MCP-server (model context protocol) is die de agent een nieuw hulpmiddel aanreikt in plaats van een nieuwe instructie.

Deel het zodra het zijn waarde heeft bewezen

Een vaardigheid die een week echt werk overleeft, is het waard om vast te leggen. Projectvaardigheden in .claude/skills/ worden beoordeeld als code en worden meegeleverd met de repository, zodat een teamgenoot die deze kloont, uw correctie ontvangt zonder extra configuratiestappen. Het verplaatsen van een vaardigheid tussen repositories zonder kopiëren en plakken is een uitdaging op zich, die wordt behandeld in hoe u agentskills deelt tussen repositories.

Een opmerking over portabiliteit. Claude Code accepteert een lange lijst met frontmatter-velden, maar de Agent Skills-standaard staat er slechts zes toe: name, description, license, compatibility, metadata en allowed-tools. Uploadt u een vaardigheid naar claude.ai, of verpakt u deze voor de Skills API, met andere gegevens in de frontmatter, dan faalt het proces direct in plaats van het veld te negeren:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Blijf binnen deze zes velden en hetzelfde bestand wordt geladen in Claude Code en in alle andere systemen die de standaard ondersteunen. Waar het bestand wordt geladen bepaalt nog steeds wat het kan doen, aangezien Cowork in een Anthropic-sandbox draait terwijl Claude Code op uw eigen machine of VPS draait. De nginx-vaardigheid hierboven is dus de moeite waard om mee te nemen naar de checkout van een teamgenoot, maar zinloos in een sandbox die de server niet kan bereiken. Het schrijven van de instructies zelf zodat ze de overstap naar een ander model overleven is een aparte taak, en vaardigheden schrijven die werken met elk model behandelt dit onderwerp.

FAQ

Hoe lang moet een SKILL.md-bestand zijn?

Houd het onder de 500 regels en verwacht dat de meeste nuttige skills aanzienlijk korter zijn. De inhoud wordt onderdeel van het gesprek zodra de skill wordt aangeroepen en blijft daar voor de rest van de sessie; elke regel is dus een terugkerende kostenpost in plaats van een eenmalige. Verplaats uitgebreid referentiemateriaal naar afzonderlijke bestanden in de skill-directory en link ernaar vanuit SKILL.md, één niveau dieper, zodat de agent ze alleen leest wanneer dat nodig is. Gebundelde scripts worden uitgevoerd in plaats van gelezen, waardoor ze alleen de kosten van hun output met zich meebrengen.

Waarom wordt mijn skill nooit geactiveerd?

De beschrijving is meestal de oorzaak, omdat dit het enige deel van de skill is dat in de context staat wanneer het model een beslissing neemt. Zorg ervoor dat erin staat wanneer de skill gebruikt moet worden, niet alleen wat deze doet, en dat de beschrijving de woorden bevat die u daadwerkelijk in uw verzoeken typt. Als de beschrijving correct lijkt, controleer dan de frontmatter op disable-model-invocation: true, die de skill volledig verbergt voor het model, en op een paths glob die de skill beperkt tot bestanden waar u niet aan werkt. Een skill in een geneste .claude/skills/-directory onder uw startdirectory is een andere oorzaak: deze wordt pas geladen nadat de agent een bestand in die subdirectory heeft gelezen of bewerkt.

Moet dit een skill zijn of een regel in mijn rules-bestand?

Vraag uzelf af op hoeveel van uw taken het van toepassing is. Een rules-bestand wordt in elke sessie geladen, dus het moet feiten bevatten die voor elke taak gelden, zoals de package manager of de naamgevingsconventie voor branches. Een skill wordt alleen geladen wanneer deze wordt geactiveerd, dus het is de juiste plek voor een procedure die slechts voor een klein deel van de taken relevant is. Schrijf nooit dezelfde instructie op beide plekken; de twee kopieën zullen uiteenlopen, waardoor u niet meer kunt achterhalen welke de agent heeft gevolgd.

Hoe weet ik of een skill daadwerkelijk heeft geholpen?

Vergelijk het met een nulmeting. Verzamel een aantal echte verzoeken, voer elk verzoek uit in een nieuwe sessie met de skill beschikbaar, en voer ze daarna opnieuw uit met de skill uitgeschakeld via het /skills-menu. Vergelijk beide antwoorden naast elkaar. Een nieuwe sessie is essentieel omdat het gesprek waarin u de skill schreef nog steeds uw uitleg bevat, waardoor een onvolledig bestand volledig lijkt. De skill-creator-plugin voert deze vergelijking voor u uit en rapporteert het slagingspercentage naast de tokenkosten.

Kan ik dezelfde SKILL.md gebruiken met een andere agent?

Ja, zolang u binnen de velden blijft die de Agent Skills-standaard definieert: name, description, license, compatibility, metadata en allowed-tools. Claude Code accepteert veel meer velden en ondersteunt ook functies in de body, zoals shell command injection, die andere tools niet uitvoeren. Het uploaden van een skill met een veld buiten de standaard mislukt met een expliciete foutmelding waarin de toegestane eigenschappen worden vermeld. Bepaal daarom vroegtijdig of een skill bedoeld is om in Claude Code te blijven of uitwisselbaar moet zijn.