Een Claude skill schrijven (SKILL.md-structuur + praktijkvoorbeelden)

Een Claude skill schrijven in één zin: maak een map aan, zet er een SKILL.md-bestand in, en schrijf een beschrijving die goed genoeg is dat Claude weet wanneer hij hem moet pakken. Dat is het hele mechanisme. Het onderdeel dat écht bepaalt of je skill werkt, is 1.024 tekens lang: het description-veld dat Anthropic gebruikt om jouw skill te selecteren uit de 100-plus die geladen kunnen zijn. Wij draaien 25 skills in productie op de Techsy community library, en de skills die falen, falen bijna nooit op hun instructies. Ze falen op die ene regel.

Korte samenvatting

Een Claude skill schrijven: (1) maak een map aan met de naam van de skill, (2) voeg een SKILL.md toe met YAML-frontmatter (name en description) plus Markdown-instructies, (3) schrijf de beschrijving in de derde persoon met duidelijke triggerwoorden, (4) houd de body onder de 500 regels en verplaats detail naar referentiebestanden, en (5) test hem met echte taken voordat je hem vertrouwt.

Wat een Claude skill eigenlijk is

Een skill is een map met een SKILL.md-bestand in de root. Meer is niet nodig. Dat bestand bevat twee dingen: metadata die Claude vertelt wanneer hij de skill moet gebruiken, en instructies die vertellen hoe hij de taak moet uitvoeren zodra hij geactiveerd is.

De reden dat dit goedkoop blijft, is een laadmodel dat Anthropic progressive disclosure noemt. Bij het opstarten leest Claude alleen de name en description van elke geïnstalleerde skill, zo'n 100 tokens per stuk. Hij leest het volledige SKILL.md-bestand pas wanneer je beschrijving matcht met de taak die voorligt, en hij leest gebundelde referentiebestanden pas wanneer de instructies ernaar verwijzen. Zo kun je een grote, gedetailleerde skill uitbrengen zonder dat je er bij elke request voor betaalt. Een werkend overzicht hiervan vind je in onze Skills library.

Het SKILL.md-skelet dat je kunt kopiëren

Elke skill begint met dezelfde vorm. Dit is de minimale versie die werkt:

---
name: reviewing-pull-requests
description: Reviews pull request diffs for bugs, security issues, and style. Use when the user asks for a code review, mentions a PR, or shares a diff.
---

# Reviewing Pull Requests

1. Read the diff and summarize what changed.
2. Flag likely bugs and edge cases, most severe first.
3. Check for hardcoded secrets and injection risks.
4. Note style issues only if they hurt readability.
5. End with a short verdict: approve, or request changes.

Twee ----markeringen omsluiten de frontmatter. Daaronder is de body gewoon Markdown. Over onze 25 skills heen is de structuur die de echte praktijk overleefde saai en consistent: een titel van één regel, dan een genummerde of opgesomde procedure, dan eventuele templates of voorbeelden. Zodra we slim probeerden te zijn met proza, scande Claude het alleen. Zodra we stappen schreven, volgde hij ze. Wil je afgeronde skills bestuderen, dan zijn de 25 skills op de Techsy community site allemaal leesbare SKILL.md-bestanden die je kunt openen en kopiëren.

Frontmatter-regels: name en description

De frontmatter heeft precies twee verplichte velden, en beide hebben harde limieten die het waard zijn om te onthouden, omdat Anthropic's tooling ze valideert.

Een nuttige conventie uit Anthropics best-practices-gids: benoem skills in de gerundiumvorm, dus processing-pdfs, writing-documentation, analyzing-spreadsheets. Dat leest prettig in een lijst en beschrijft de activiteit in plaats van een vage naamwoordelijke term als helper of utils. Houd de name gelijk aan de mapnaam zodat de twee nooit uit elkaar gaan lopen. Voor de volledige validatieregels is het Anthropic best-practices-document de bron.

Schrijf een description die daadwerkelijk triggert

Dit is het onderdeel dat de meeste tutorials overslaan, en het is het onderdeel dat bepaalt of je werk ooit gebruikt wordt. De description wordt in de system prompt geïnjecteerd, en Claude leest hem om te beslissen of hij je skill überhaupt laadt. Een perfecte body achter een vage description is een skill die nooit draait.

Drie regels maken het verschil:

Schrijf in de derde persoon. De description beschrijft de skill, niet jou en niet de gebruiker. Eerste- of tweedepersoonsformuleringen verwarren de selectie.

# Good
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDFs or when the user mentions forms or document extraction.

# Avoid
description: I can help you work with your PDF files whenever you need.

Vermeld zowel wat als wanneer. "Verwerkt data" vertelt Claude niets over welke taak erbij past. Noem de concrete capability en de concrete triggers.

Neem de woorden op die een gebruiker daadwerkelijk zou typen. Als mensen "PR", "diff" en "code review" zeggen, zet die termen dan in de description. Claude matcht erop. Dit is de edit met de hoogste impact die je aan een skill kunt maken, en hij kost je één regel.

Progressive disclosure en bestandsstructuur

Zodra een skill groter wordt dan een scherm of twee, gaat structuur ertoe doen. Anthropics richtlijn is concreet: houd de SKILL.md-body onder de 500 regels, en verplaats alles wat langer is naar aparte referentiebestanden waar de body naar linkt. Die bestanden kosten nul tokens totdat Claude ze daadwerkelijk leest.

Een volwassen geworden skill ziet er zo uit:

reviewing-pull-requests/
├── SKILL.md            # overview + the core procedure
├── security.md         # detailed security checklist (read when needed)
├── style-guide.md      # house style rules (read when needed)
└── scripts/
    └── diff_stats.py    # executed, never loaded into context

Twee regels houden dit werkend. Ten eerste: houd referenties één niveau diep — link elk bestand rechtstreeks vanuit SKILL.md, nooit bestand-naar-bestand-naar-bestand, omdat Claude diep geneste bestanden mogelijk alleen met een partial read bekijkt en zo inhoud mist. Ten tweede: geef elk referentiebestand langer dan 100 regels een inhoudsopgave bovenaan, zodat een partial read alsnog de volledige scope toont. Anthropics engineering-artikel over Agent Skills legt de architectuur hierachter uit als je het diepere model wilt. Zodra je skill tools gaat orkestreren, is onze MCP-catalogus een handige metgezel om servers aan te sluiten.

Vrijheidsgraden (en wanneer je scripts toevoegt)

Niet elke instructie hoeft even strikt te zijn. Match hoe strak je een stap scriptet aan hoe fragiel die stap is.

Als een stap deterministisch is, breng dan een script uit in plaats van Claude elke keer code te laten genereren. Een gebundeld script is betrouwbaarder, bespaart tokens en blijft consistent tussen runs. Twee gewoontes houden scripts eerlijk: handel fouten af in het script zelf in plaats van dat aan Claude over te laten, en verantwoord elke constante zodat je geen onverklaarde magic numbers hebt. Dit is ook waar skills verschillen van subagents, die hun eigen tool-allowlist en system prompt meedragen; onze automations library verzamelt subagent-voorbeelden, en je kunt de twee aanpakken vergelijken op de Techsy AI automations-pagina.

Testen: eval-driven skill development

De beste skill-auteurs schrijven tests voordat ze documentatie schrijven. Anthropic raadt aan eerst evaluaties te bouwen: laat Claude los op drie representatieve taken zonder de skill, noteer precies waar hij faalt, en schrijf dan alleen genoeg instructie om die fouten te verhelpen. Zo blijf je echte problemen oplossen in plaats van ingebeelde problemen documenteren.

Een praktische loop:

1. Kies drie echte taken die de skill moet afhandelen.
2. Voer ze uit zonder skill geladen en noteer wat er misgaat.
3. Schrijf de minimale SKILL.md die die problemen oplost.
4. Test opnieuw met de skill geladen, idealiter op Claude Haiku, Sonnet en Opus, want een skill die Opus goed stuurt, kan voor Haiku onvoldoende gespecificeerd zijn.
5. Kijk hoe Claude door de bestanden navigeert. Negeert hij een referentie, dan is je link niet prominent genoeg. Leest hij hetzelfde bestand steeds opnieuw, dan hoort die inhoud in SKILL.md thuis.

Voor een hands-on walkthrough die een skill end-to-end bouwt, heeft onze zustersite een volledige Claude Skills-tutorial; die combineert goed met de schrijfregels hier. Je kunt je build ook aftoetsen tegen onze enterprise build checklists.

Veelgemaakte fouten die een skill om zeep helpen

De meeste kapotte skills falen om een van een kort lijstje redenen:

• Een description geschreven voor mensen. Marketingtekst leest lekker weg en triggert niets. Schrijf voor het model: capabilities en triggers.
• Te veel opties. "Gebruik pypdf, of pdfplumber, of PyMuPDF, of..." maakt Claude aarzelend. Geef één default met één escape hatch.
• Diep geneste referenties. Bestanden die linken naar bestanden die linken naar bestanden worden maar deels gelezen. Houd alles op één hop afstand van SKILL.md.
• Tijdgevoelige instructies. "Doe X voor augustus" veroudert. Zet verouderde richtlijnen liever in een ingeklapte "oude patronen"-notitie.
• Windows-stijl paden. Gebruik altijd forward slashes; backslashes breken op Unix-runners.
• Inconsistente terminologie. Kies één woord voor een ding ("field", niet "field/box/element/control") en gebruik het overal.

Het patroon achter alle zes: een skill is een instructieset voor een zeer capabele lezer die geen geduld heeft met ambiguïteit. Zeg het specifieke ding, één keer.

Over de auteur

Mert Batur Gurbuz is Co-Founder van Techsy, University of Birmingham. Hij en het Techsy-team bouwen AI agents, automation-systemen en voice/SDR-pipelines voor B2B-klanten, en onderhouden de 25-skill library waar in deze gids voortdurend naar wordt verwezen. Connect op LinkedIn. Meer builder-gidsen vind je op de TECHSY.community blog.

Veelgestelde vragen

Waar staan de bestanden van een Claude skill?

Een skill is een map die een SKILL.md-bestand bevat. In Claude Code staan persoonlijke skills in ~/.claude/skills/{skill-name}/ en projectskills in .claude/skills/{skill-name}/. Bij de API en claude.ai upload je de skillmap. De mapnaam moet overeenkomen met het name-veld in de frontmatter.

Moet de skillnaam overeenkomen met de mapnaam?

Ja, houd ze identiek. Het name-veld mag maximaal 64 tekens lang zijn, gebruikt alleen kleine letters, cijfers en koppeltekens, en vermijdt de gereserveerde woorden "anthropic" en "claude". Overeenkomst met de mapnaam voorkomt dat ze uit elkaar gaan lopen en maakt de skill makkelijk te refereren in conversatie en documentatie.

Hoe lang mag een SKILL.md zijn?

Houd de body van SKILL.md onder de 500 regels voor betrouwbare prestaties. Er is geen harde tokenlimiet, omdat referentiebestanden en scripts pas kosten wanneer ze gelezen worden, maar een opgeblazen hoofdbestand concurreert met al het andere in het context window. Naarmate je richting 500 regels gaat, splits je detail op in referentiebestanden die rechtstreeks vanuit SKILL.md gelinkt worden.

Waarom triggert mijn skill niet?

Bijna altijd de description. Claude selecteert skills door de taak te matchen met het description-veld, dus als die van jou vaag is of in de eerste persoon geschreven, activeert hij nooit. Herschrijf hem in de derde persoon, vermeld wat de skill doet en wanneer je hem gebruikt, en neem de exacte woorden op die een gebruiker voor die taak zou typen.

Wat is het verschil tussen een skill, een subagent en een MCP server?

Een skill is een verpakte instructieset die Claude laadt wanneer relevant. Een subagent is een aparte agent met zijn eigen tool-allowlist en system prompt die een gedelegeerde taak afhandelt. Een MCP server stelt externe tools en data beschikbaar via het Model Context Protocol. Skills beschrijven hoe je werk doet; MCP servers leveren waarop je acteert.

Kan een Claude skill code uitvoeren?

Ja. Skills kunnen uitvoerbare scripts bundelen die Claude als tools draait in plaats van in de context in te lezen, wat goedkoper en betrouwbaarder is voor deterministisch werk zoals validatie of bestandsconversie. Maak de intentie expliciet in je instructies: zeg "run this script" voor uitvoering, of "see this script" wanneer het referentiemateriaal is.

Werken skills zowel in de API als op claude.ai?

Ja, al verschilt de runtime. Op claude.ai kan de code execution environment packages installeren vanuit npm en PyPI, terwijl de Claude API geen netwerktoegang of runtime package-installatie heeft. Vermeld vereiste packages in je SKILL.md en bevestig dat ze beschikbaar zijn in de doelomgeving voordat je erop vertrouwt.

Hoeveel skills kan Claude tegelijk geladen hebben?

Veel, omdat bij het opstarten alleen de name en description van elke skill in de context staan, zo'n 100 tokens per stuk. Daarom is de description zo belangrijk: Claude kiest mogelijk uit 100-plus skills, en een precieze description is wat hem in staat stelt de jouwe correct te kiezen. De volledige body laadt pas zodra de skill geselecteerd is.