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 destilleren uit een reële fout. Zoek een taak die uw coding agent twee keer fout heeft uitgevoerd, noteer de correctie die u beide keren hebt getypt 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 belangrijk. Een skill die vanuit verbeelding is geschreven, documenteert een probleem dat u nooit hebt gehad, en het kost nog steeds context in elke sessie. Een skill die is gedestilleerd uit een fout die u hebt 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 op echte servers herhaaldelijk voorkomt. 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 zaken terwijl de fout nog voor u ligt: het verzoek dat u typte en de correctie die u gaf, in de bewoordingen die u gebruikte. Die twee regels vormen samen 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 deze faalt en schrijf vervolgens de minimale instructies die deze fouten verhelpen. De fouten vormen de specificatie; een vaardigheid die u niet kunt herleiden naar een fout is daarom meestal een vaardigheid die niemand nodig had.

Voor een uitgewerkt voorbeeld van dezelfde destillatie 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. Hier is 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 is een complete skill. De onderdelen:

• name: maximaal 64 tekens, alleen kleine letters, cijfers en koppeltekens, en 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 moet gebruiken, 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 diepte, omdat een bestand waarnaar wordt verwezen vanuit een ander bestand waarnaar wordt verwezen, vaak slechts gedeeltelijk wordt gelezen.
• scripts/: bestanden die de agent uitvoert in plaats van leest. Alleen hun output kost context, dus een script van 300 regels is goedkoop.

Waar u de map plaatst, bepaalt wie de skill krijgt.

• .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 waar die plugin ook 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 startte, vereist een herstart, omdat er niets was om te monitoren toen de sessie begon.

Het beschrijvingsveld is de meest effectieve regel 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 wordt gelezen als het model dat 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 trigger-zinnen en voorbeeldverzoeken; dit wordt onder diezelfde limiet aan de beschrijving toegevoegd.

Gebruik vervolgens de woorden die u daadwerkelijk zult typen. description: Helps with nginx matcht niets, 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 klein, 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 bij latere beurten. Elke regel die u schrijft, is een kost die u betaalt voor de gehele sessie, niet voor één antwoord.

Anthropic raadt aan 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 alleen 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 duwen elkaar volledig uit de context.

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

Als de skill de agent opdraagt om een gebundeld script uit te voeren, benoem het pad dan met ${CLAUDE_SKILL_DIR} zodat het wordt opgelost waar de skill ook is geïnstalleerd, en keur hetzelfde commando vooraf goed zodat de uitvoering niet stopt bij een toestemmingsvraag.

---
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 toewijzing geldt voor de beurt die de skill aanriep en vervalt wanneer u uw volgende bericht verstuurt, zodat het niet stilletjes een permanente toestemming wordt.

Hoe u aantoont dat de skill wordt geactiveerd

Het observeren van het laden van een skill bevestigt dat de agent deze heeft gevonden. Het vertelt u echter niet 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 tijdens het schrijven. Die achtergebleven context maskeert hiaten 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, corrigeer dan de beschrijving. De body 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 run met een schone context begint. Vervolgens wordt een vergelijking geschreven 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.

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 gebruikt moet worden, 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/ map onder uw startmap. Deze worden pas geladen nadat de agent een bestand in die submap 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 wordt geactiveerd bij irrelevante werkzaamheden. "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. Voor acties met bijwerkingen, zoals een deploy of een commit, stelt u disable-model-invocation: true in en roept u deze zelf aan met /name, zodat de agent nooit zelfstandig beslist dat het een goed moment is om te deployen.

Foutmodus: de vaardigheid hoort in uw rules-bestand

Een rules-bestand 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 (skill) wordt alleen geladen wanneer de vaardigheid wordt geactiveerd. Frequentie is hierbij de doorslaggevende factor. Een feit dat voor elke taak in de repository geldt, zoals de pakketbeheerder die u gebruikt, hoort in het rules-bestand thuis. Een procedure die slechts op een klein deel van de taken van toepassing is, zoals de bovenstaande nginx-regel, hoort in een vaardigheid thuis; daar kost het geen resources op dagen dat niemand nginx bewerkt.

De werkelijke fout is het op beide plaatsen opnemen van de instructie. 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. de grens tussen vaardigheden, MCP-servers en rules-bestanden behandelt de complexere gevallen, inclusief situaties waarin het juiste antwoord een MCP-server (model context protocol) is die de agent een nieuwe tool aanreikt in plaats van een nieuwe instructie.

Deel het zodra het zijn waarde heeft bewezen

Een vaardigheid die een week aan echt werk overleeft, is het waard om vast te leggen. Projectvaardigheden in .claude/skills/ worden beoordeeld als code en komen mee met de repository, waardoor 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 agent-vaardigheden deelt tussen repositories.

Een opmerking over overdraagbaarheid. 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. Als u een vaardigheid uploadt naar claude.ai, of deze verpakt voor de Skills API, met andere gegevens in de frontmatter, dan mislukt dit direct in plaats van dat het veld wordt genegeerd:

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. Het schrijven van de instructies zelf, zodat deze ook werken bij een overstap naar een ander model, is een aparte taak, die wordt behandeld in vaardigheden schrijven die werken met elk model.

FAQ

Hoe lang moet een SKILL.md bestand zijn?

Houd het onder de 500 regels en ga ervan uit dat de meeste nuttige skills veel 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 diep, zodat de agent ze alleen leest wanneer dat nodig is. Gebundelde scripts worden uitgevoerd in plaats van gelezen, dus die kosten alleen de output.

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 het 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 dit 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; het is dus de juiste plek voor een procedure die slechts bij een klein deel van de taken relevant is. Schrijf nooit dezelfde instructie op beide plekken, omdat de twee kopieën uit elkaar gaan lopen en 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 paar echte verzoeken, voer elk verzoek uit in een nieuwe sessie met de skill beschikbaar, voer ze daarna opnieuw uit met de skill uitgeschakeld via het /skills menu, en lees beide antwoorden naast elkaar. Een nieuwe sessie is belangrijk 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 die de toegestane eigenschappen opsomt, dus bepaal vroegtijdig of een skill bedoeld is om in Claude Code te blijven of om uitwisselbaar te zijn.