Claude Skills Tutorial: Bouw je eerste SKILL.md in 10 minuten (2026)

Claude Skills Tutorial: Bouw je eerste SKILL.md in 10 minuten (2026)

Skills zijn waarschijnlijk de belangrijkste Claude Code-feature die je nog niet gebruikt. Een Claude skill is een map met een SKILL.md-bestand dat Claude automatisch laadt zodra je prompt overeenkomt met de beschrijving — geen prompts kopiëren en plakken, geen opgeblazen CLAUDE.md, geen gedoe met welke template je ook alweer moest pakken. We hebben 4 skills gebouwd in de .claude/skills/agent/-map van deze repo, en met Skills 2.0 plus de Anthropic Marketplace die begin 2026 gelanceerd is, vindt het formaat eindelijk zijn ritme. Dit is het patroon dat werkt, na alle valkuilen.

Kernpunten

• Een Claude skill is een map met een SKILL.md-bestand met YAML-frontmatter dat Claude automatisch laadt wanneer het relevant is.
• Skills leven in ~/.claude/skills/ (persoonlijk) of .claude/skills/ (project) — Claude scant beide bij het opstarten.
• Gebruik Skills voor herhaalbare workflows; gebruik MCP voor live externe data; gebruik subagents voor meerstappenplanning; gebruik hooks voor deterministische events.
• De snelste weg naar je eerste skill: vraag Claude om zijn eigen skill-creator-skill aan te roepen — die schrijft de SKILL.md voor je.

Wat zijn Claude Skills?

Een Claude skill is een map met een SKILL.md-bestand met YAML-frontmatter (name, description, optioneel allowed-tools) dat Claude Code automatisch in de context laadt wanneer je prompt overeenkomt met de beschrijving. Skills verpakken herbruikbare workflows — zoals /commit of /explain-code — zonder je systeemprompt op te blazen.

Volgens Anthropic's officiële documentatie heeft elke skillmap drie dingen: een verplichte SKILL.md, optionele meegeleverde scripts (van een Python-helper tot een JSON-config), en optionele referentiedocumenten die samen met de body laden. Dat is het. Geen buildstap, geen installatie, geen manifest.

Het slimme zit hem in progressieve onthulling. Bij het opstarten scant Claude alleen het description-veld van elke skill. De body — instructies, voorbeelden, tool-call-patronen — blijft op schijf totdat je prompt daadwerkelijk matcht. Je kunt dus 50 skills geïnstalleerd hebben en nul token-kosten betalen totdat er één afgaat.

Denk aan skills als kookboekrecept die Claude opslaat wanneer hij de ingrediënten in je prompt ziet. Een skill is een map die Claude op aanvraag leest — niet een prompt die je onthoudt om te plakken. Dat is de hele belofte.

Een minimale SKILL.md ziet er zo uit:

---
name: Summarize file
description: Use when the user asks for a 3-sentence summary of a file or function.
---

Read the file at $ARGUMENTS. Summarize purpose, key dependencies, and the
single most surprising thing about it. Three sentences max.

Tien regels. Echte skill. Klaar om af te gaan.

Snel aan de slag: bouw je eerste skill in 10 minuten

Om je eerste Claude skill in 10 minuten te bouwen: (1) maak ~/.claude/skills/explain-code/ aan, (2) voeg een SKILL.md-bestand toe met name, description en de workflow-body, (3) herstart Claude Code zodat het de nieuwe map oppikt, (4) activeer het met een prompt die overeenkomt met de beschrijving.

Hier is de volledige flow.

Stap 1: Maak de map aan

mkdir -p ~/.claude/skills/explain-code

Persoonlijke skills (alleen voor jou) gaan in ~/.claude/skills/. Projectskills (gedeeld via git met je team) gaan in .claude/skills/ in de root van je repo. Kies persoonlijk voor dagelijkse workflows; kies project als je wilt dat elke contributor op de repo het erft.

Stap 2: Schrijf SKILL.md

Zet dit bestand op ~/.claude/skills/explain-code/SKILL.md:

---
name: Explain code
description: Use when the user asks for a plain-English walkthrough of a code snippet, function, or file. Use $ARGUMENTS for the path or snippet.
---

You are explaining code to a developer who is new to this codebase.

1. Read the file or snippet at $ARGUMENTS.
2. State the file's purpose in one sentence.
3. Walk through the control flow line by line in plain English.
4. Flag any non-obvious dependencies or side effects.
5. End with one question the reader should ask before changing this code.

Dat is de hele skill. De frontmatter is het contract; de body is het draaiboek.

Stap 3: Herstart Claude Code

Live detectie is een Skills 2.0-feature — oudere versies van Claude Code hebben een verse start nodig om de nieuwe map op te pikken. Als je niet zeker weet welke versie je hebt, kost één herstart niets.

Stap 4: Activeer het

Open een project en prompt:

walk me through what auth/middleware.ts does

Claude matcht je prompt tegen het description-veld, vindt explain-code, en laadt de SKILL.md-body stil in de context. Je ziet "Using skill: explain-code" in het tool-log. Klaar.

Pro tip: Geen zin om het bestand zelf te schrijven? Open Claude Code en zeg Use the skill-creator skill to scaffold an explain-code skill for me. Anthropic's meegeleverde skill-creator is een meta-skill die je interviewt, verstandige allowed-tools kiest en de SKILL.md naar de juiste map schrijft. De snelste weg naar je eerste skill, punt.

Dat is de 10-minutenbelofte — vijf minuten typen, één herstart, één testprompt.

In SKILL.md: de frontmatter-referentie

SKILL.md-frontmatter is YAML omgeven door ----delimiters. Twee velden zijn verplicht: name (≤64 tekens, gebruikt als slash-command-naam) en description (de triggertekst die Claude matcht met je prompt). Optionele velden regelen toegang tot tools, modelaanroeping, bestandsglobs en uitvoeringscontext.

Hier is de volledige referentie, afkomstig van Anthropic's skills-documentatie:

De rij context: fork verdient speciale aandacht. Het is een Skills 2.0-primitief dat de skill in een geïsoleerd contextvenster draait — handig voor langlopende onderzoeksskills of alles wat veel tussentijdse tokens produceert die je niet in je hoofdthread wilt hebben. Als dit concept nieuw voor je is, behandelt onze context engineering-gids de afwegingen.

Een maximale SKILL.md-frontmatter, elk veld ingevuld:

---
name: Deploy preview
description: Use when the user wants to deploy a preview build of the current branch to staging.
allowed-tools: ["Bash(git status:*)", "Bash(npm run build:*)", "Bash(vercel:*)"]
disable-model-invocation: true
user-invocable: true
argument-hint: <branch-name or 'current'>
model: claude-opus-4-7
context: fork
globs: ["package.json", "vercel.json"]
references: ["./deploy-runbook.md"]
bundled-files: ["./scripts/preflight.sh"]
tags: ["deploy", "vercel", "preview"]
---

Pro tip: De grootste fout in description: het schrijven voor mensen. Schrijf het voor Claude — concrete triggerzinnen, geen marketingpraat. Slecht: "Een krachtige Git-automatiseringsskill." Goed: "Use when the user wants to commit changes, write a commit message, or open a PR."

Twee echte skills, van begin tot eind

Twee skillpatronen dekken 80% van de praktijk: (1) een door de gebruiker aanroepbare /commit-skill met disable-model-invocation: true en allowed-tools: Bash(git *) voor deterministische acties; (2) een automatisch geïnvoceerde /explain-code-skill met standaard frontmatter die Claude triggert wanneer prompts overeenkomen met de beschrijving.

De meeste tutorials tonen fragmenten. Hier zijn twee complete bestanden die je vandaag kunt kopiëren naar ~/.claude/skills/.

De /commit-skill (door gebruiker aanroepbaar)

---
name: Commit
description: Use when the user wants to stage and commit code changes with an AI-written conventional-commit message.
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - "Bash(git status:*)"
  - "Bash(git diff:*)"
  - "Bash(git add:*)"
  - "Bash(git commit:*)"
---

1. Run `git status` and `git diff` to see what's staged and unstaged.
2. Group changes into one logical commit. If there are multiple unrelated
   changes, ask the user which to include.
3. Draft a Conventional Commits message: `type(scope): subject` (≤72 chars),
   blank line, body explaining *why*, not *what*.
4. Show the message to the user. Ask "Commit this?" Wait for explicit yes.
5. On confirmation, run `git add` for the included files and `git commit -m`.
6. Print the resulting commit hash.

Testprompt: /commit

Wat er gebeurt: Claude inspecteert de git-status, stelt een bericht op, vraagt je te bevestigen, en voert pas dan git commit uit. Het disable-model-invocation: true betekent dat het nooit automatisch afgaat bij een vage "sla mijn wijzigingen op"-prompt — het draait alleen wanneer je /commit typt. De allowed-tools-whitelist vergrendelt het op git-subcommando's; het kan fysiek geen rm -rf uitvoeren of naar remote pushen. Dit is er één die we live gebruiken in onze eigen pipeline.

Voor deterministische acties na een commit (lint draaien, types regenereren, een Slack-webhook pingen) kun je beter Claude Code hooks gebruiken — skills zijn probabilistisch, hooks gaan altijd af.

De /explain-code-skill (door model aanroepbaar)

---
name: Explain code
description: Use when the user asks for a plain-English walkthrough of a code snippet, function, or file. Use $ARGUMENTS for the path or snippet.
argument-hint: <file path or pasted snippet>
model: claude-opus-4-7
---

1. Read the file or snippet at $ARGUMENTS. If $ARGUMENTS is empty, ask
   the user which file to explain.
2. State the file's purpose in one sentence.
3. Walk through the control flow line by line in plain English.
4. Flag any non-obvious dependencies, side effects, or hidden assumptions.
5. End with one question the reader should ask before modifying this code.

Testprompt: walk me through what auth/middleware.ts does

Wat er gebeurt: merk op dat de gebruiker /explain-code niet heeft getypt. Claude matcht "walk me through" tegen het description-veld, vindt de skill en roept het automatisch aan. Dat is de magie — de description verzorgt de routing. Het veld model: claude-opus-4-7 koppelt deze skill aan Opus, ongeacht welk model je als standaard hebt ingesteld, zodat diepgaande code-walkthroughs altijd het slimmere model krijgen. (Meer over het gebruik van Claude Code met verschillende modellen.)

Waarom twee patronen? Skill #1 is door gebruiker aanroepbaar + vergrendeld op specifieke tools — voorspelbaar, veilig, perfect voor git of deploys. Skill #2 is automatisch aanroepbaar + open-ended — de magie van skills, maar vertrouw op je description-veld. Door de gebruiker aanroepbare skills geven voorspelbaarheid; door het model aanroepbare skills geven magie. Kies per skill, niet per repo.

Voor meer echte voorbeeldskills, bekijk de officiële anthropics/skills-repo en de door de community onderhouden awesome-claude-skills-lijst.

Skills vs MCP vs Subagents vs Hooks: wanneer gebruik je wat?

Gebruik Skills voor herbruikbare workflows die Claude automatisch moet triggeren of die je als slash-commands aanroept. Gebruik MCP-servers als je live externe data nodig hebt (databases, API's, bestandssystemen buiten de werkmap). Gebruik subagents voor meerstappenplannen die Claude aan een frisse context moet delegeren. Gebruik hooks voor deterministische events (pre-commit, post-tool-use) die altijd moeten afgaan — nooit probabilistisch.

Kort samengevat: skills zijn workflows, Model Context Protocol is data, subagents zijn plannen, hooks zijn events. Elk leeft op een andere laag van Claude Code, en de verkeerde laag is het verkeerde gereedschap. Volgens Anthropic's eigen Skills explained-bericht is dit het kader dat ze je willen meegeven.

Ze combineren. Een skill kan een MCP-tool aanroepen via allowed-tools. Een hook kan afgaan nadat een skill voltooid is. Een subagent kan skills gebruiken waartoe het toegang heeft gekregen. Het schoonste mentale model: kies eerst de juiste laag, laat ze dan stapelen. Skills zijn de context engineering-primitief die je pakt als je een workflow wilt die Claude kan kiezen; je automatiseert met hooks als je iets wilt dat Claude niet kan overslaan.

De slechtste manier om elk te misbruiken: Skills voor live data (gebruik MCP); MCP voor eenmalige promptsjablonen (gebruik Skills); subagents voor deterministische bestandsbewerkingen (gebruik hooks); hooks voor vertakkende logica (gebruik Skills). Skills zijn workflows, MCP is data, subagents zijn plannen, hooks zijn events. Kies op basis van de laag, niet het buzzword.

Waar skills leven: persoonlijk, project, plugin, enterprise

Claude skills installeren in vier scopes: persoonlijk (~/.claude/skills/, alleen jij), project (.claude/skills/ in de repo-root, je team via git), plugin (gedistribueerd via de Anthropic Marketplace of een plugin-URL), en enterprise (door IT uitgerold via MDM/beheerdersbeleid). Claude scant alle vier bij het opstarten.

De meegeleverde doc-skills worden makkelijk vergeten — Claude Code levert al pdf, docx, pptx en xlsx-skills mee, plus een kleine bibliotheek van /debug, /simplify en vergelijkbare ingebouwde functies. (Het zusterprogramma Claude Design levert zijn eigen meegeleverde workflow-skills voor het genereren van ontwerpen; hetzelfde model, ander domein.)

Wanneer kies je voor plugin in plaats van project? Plugins winnen als dezelfde workflow meerdere repo's ten goede komt — een /release-skill die je gebruikt over vijf clientcodebases hoort in een plugin, niet gekopieerd en geplakt in de .claude/skills/ van elke repo. Projectskills winnen voor codebase-specifieke conventies (je teams PR-sjabloon, je aangepaste testrunner). De Anthropic Marketplace, plus /plugin install vanaf elke URL, maakt plugins het juiste antwoord voor hergebruik over repo's. Volgens de plugin-documentatie worden detectie en updates automatisch afgehandeld.

Geavanceerde patronen: $ARGUMENTS, dynamische shell-injectie, context: fork

Drie geavanceerde skillpatronen zijn het meest relevant: $ARGUMENTS laat gebruikers parameters meegeven aan door de gebruiker aanroepbare skills (/translate $ARGUMENTS); dynamische shell-injectie (met allowed-tools: Bash(...)) laat een skill scripts draaien en output in de context pipen; en context: fork (Skills 2.0) draait de skill in een geïsoleerd contextvenster. Anthropic's Complete Guide whitepaper is de canonieke referentie voor context: fork vanaf mei 2026.

$ARGUMENTS voor geparametriseerde skills

---
name: Translate
description: Translate the most recent message into the target language.
user-invocable: true
argument-hint: <target-language, e.g. spanish, japanese, brazilian portuguese>
---

Translate the user's previous message into $ARGUMENTS. Preserve tone,
preserve markdown formatting, return only the translation.

Testprompt: /translate spanish. Claude vervangt spanish door $ARGUMENTS tijdens runtime. De schoonste manier om een skill veelzijdig te maken zonder varianten te schrijven.

Dynamische shell-injectie via allowed-tools

---
name: Review last commit
description: Use when the user wants a code review of the last git commit.
allowed-tools: ["Bash(git diff HEAD~1:*)", "Bash(git log -1:*)"]
---

Run `git diff HEAD~1` and `git log -1`. Review the diff for bugs, security
issues, and style violations. Output a 5-bullet review.

De skill roept de shell aan, pipt de diff in de context en beoordeelt die. Vergrendel allowed-tools op specifieke commando's (Bash(git diff HEAD~1:*)), nooit kaal Bash — kale Bash-toestemming is de security-valkuil van dit patroon.

context: fork (Skills 2.0)

---
name: Deep research
description: Use when the user wants a multi-source research summary on a topic.
context: fork
---

Research the topic in $ARGUMENTS using available web tools. Produce a
2-page summary with citations. Do not pollute the main thread.

Forken geeft de skill zijn eigen contextvenster, zodat de 50K tokens aan tussentijdse onderzoeksnotities niet in je hoofdsessie terechtkomen. Handig voor lang onderzoek, grote refactor-planningen, of alles wat veel wegwerpbare tokens produceert. Alleen Skills 2.0 — oudere versies van Claude Code negeren het veld.

Probleemoplossing: waarom je skill niet triggert

Skills triggeren meestal niet om één van vier redenen: (1) de description is te generiek voor Claude om te matchen met je prompt, (2) de map staat op het verkeerde pad (.claude/skills/ niet claude/skills/), (3) Claude Code is niet herstart nadat de skill is toegevoegd (alleen pre-Skills-2.0), of (4) de skill-naam conflicteert met een meegeleverde of hogerprioritaire skill. Volgens de meest gegoogelde foutmodi in de Claude Code GitHub issues tracker dekken deze vier ~95% van de "waarom werkt dit niet"-meldingen.

Foutmodus 1: "Mijn skill verschijnt helemaal niet"

De nummer-één oorzaak is een verkeerd pad — .claude/skills/ (met de punt) vs claude/skills/ (zonder punt) is een typefout die we allemaal wel eens 's nachts maken. Voer ls -la ~/.claude/skills/ uit om te bevestigen dat de map bestaat met de punt. Als die er is en Claude hem nog steeds niet ziet, herstart Claude Code één keer. Pre-Skills-2.0-versies scannen alleen bij het opstarten.

Foutmodus 2: "Claude roept mijn skill niet automatisch aan"

Het description-veld is te vaag of geschreven voor mensen, niet voor Claude. Herschrijf het met concrete triggerzinnen die weerspiegelen hoe gebruikers hun verzoeken daadwerkelijk formuleren. Na het bouwen van 4 skills voor deze repo was de valkuil die ik tegenkwam het achterlaten van beschrijvingen zoals "A helpful skill for SEO." Nutteloos. Herschrijf naar: "Use when the user wants to add JSON-LD schema, meta tags, or SEO frontmatter to a Markdown post." De triggernauwkeurigheid ging van ~30% naar ~95%. Triggernauwkeurigheid staat of valt met het description-veld. Schrijf het voor Claude, niet voor je cv.

Foutmodus 3: "De beschrijving is afgekapt in het slash-command-palet"

Je description heeft meer dan 1024 tekens of je name heeft meer dan 64 tekens. Beide hebben harde limieten. Oplossing: splits de skill in twee smallere skills, of verplaats de lange details naar de SKILL.md-body. De frontmatter is voor routing, niet voor documentatie.

Foutmodus 4: "Live wijzigingsdetectie werkt niet"

Pre-Skills-2.0 Claude Code vereist een volledige herstart na elke SKILL.md-bewerking. Als je aan een skill itereert en je wijzigingen worden niet opgepikt, zit je waarschijnlijk op een oudere build. Upgrade naar een Claude Code-versie met Skills 2.0 (live detectie) of went jezelf aan om na elke opslag te herstarten. Vervelend, maar goedkoop.

Skills buiten Claude: de Open Agent Skills Standard

Ja — skills zijn een open standaard. De Agent Skills-standaard op agentskills.io definieert het SKILL.md-formaat onafhankelijk van elke vendor. OpenAI's Codex CLI en ChatGPT Desktop adopteerden de standaard in december 2025; dezelfde SKILL.md die je voor Claude Code schrijft, draait in Codex met kleine frontmatter-aanpassingen.

Hier is de cross-tool ondersteuningsmatrix van mei 2026: Claude Code heeft volledige Agent Skills-ondersteuning (de referentie-implementatie). OpenAI's Codex CLI heeft volledige ondersteuning. ChatGPT Desktop heeft gedeeltelijke ondersteuning — name, description en body werken, maar allowed-tools-pariteit is er nog niet. Gemini CLI kondigde ondersteuning aan in begin 2026 maar had die op het moment van schrijven nog niet uitgebracht. Cursor is de vreemde eend — het gebruikt zijn eigen Cursor rules-formaat en leest SKILL.md niet natively, hoewel community-shims bestaan.

Wat je vandaag moet schrijven zodat je skills het jaar overleven: houd name en description schoon en vendor-agnostisch. Isoleer vendor-specifieke frontmatter achter een naamruimte (claude: of codex:) als je cross-tool gaat. Het draagbare oppervlak — name, description, body, $ARGUMENTS — werkt overal; geavanceerde velden zoals context: fork zijn Claude-specifiek totdat andere vendors equivalenten uitbrengen. Anthropic duwt ook op diepere marketplace-integratie volgens het gelekte Claude Code-stappenplan, dus draagbaarheid wordt alleen maar makkelijker.

De drie plekken om voorbeeldskills te zoeken: anthropics/skills (officieel), awesome-claude-skills (community) en agentskills.io (de specificatiepagina van de standaard). Skills zijn geen Claude-feature meer. Het is een open standaard die Claude als eerste heeft uitgebracht.

Veelgestelde vragen

Wat is het verschil tussen een Claude skill en een MCP-server?

Een Claude skill is een SKILL.md-bestand met workflow-instructies die Claude laadt wanneer je prompt overeenkomt met de beschrijving. Een MCP-server is een apart proces dat Claude aanroept om live data op te halen (databases, API's, bestandssystemen buiten de werkmap). Gebruik Skills voor workflows; gebruik MCP voor data. Ze combineren — skills kunnen MCP-tools aanroepen.

Zijn Claude skills gratis?

Ja — Skills is een ingebouwde Claude Code-feature, geen extra kosten. Je betaalt alleen voor de modeltokens die worden verbruikt wanneer een skill draait. Skills die je installeert vanuit de Anthropic Marketplace kunnen betaald zijn (vandaag zeldzaam), maar de officiële anthropics/skills-repo en community awesome-lists zijn allemaal gratis te kopiëren en gebruiken.

Waar worden Claude skills geïnstalleerd?

Persoonlijke skills gaan in ~/.claude/skills/{skill-name}/, projectskills in .claude/skills/{skill-name}/ in je repo-root. Plugin-skills installeren via /plugin install <url> en leven in je plugin-map. Enterprise-skills worden door de IT van je organisatie uitgerold via beheerde instellingen. Claude Code scant alle vier scopes bij het opstarten.

Hoe maak ik een Claude skill van nul?

Maak een map aan in ~/.claude/skills/, voeg een SKILL.md-bestand toe met YAML-frontmatter (name, description) gevolgd door de workflow-instructies, en herstart Claude Code. De snelste weg: open Claude Code en vraag het de meegeleverde skill-creator-skill aan te roepen — die scaffoldt de SKILL.md voor je in minder dan een minuut.

Waarom triggert mijn Claude skill niet?

Vier meest voorkomende oorzaken: (1) de description is te vaag voor Claude om te matchen met je prompt — herschrijf met concrete triggerzinnen; (2) de skill staat op het verkeerde pad (.claude/skills/ niet claude/skills/); (3) Claude Code heeft een herstart nodig op pre-Skills-2.0-versies; (4) de skill-naam conflicteert met een meegeleverde skill. Controleer met ls -la ~/.claude/skills/.

Kunnen ChatGPT of Cursor Claude skills gebruiken?

ChatGPT Desktop en Codex CLI ondersteunen dezelfde Agent Skills-standaard als Claude — dezelfde SKILL.md draait in beide met kleine frontmatter-wijzigingen. Cursor gebruikt zijn eigen Cursor rules-formaat en leest SKILL.md niet natively. Gemini CLI kondigde ondersteuning aan begin 2026, maar had die vanaf mei 2026 nog niet uitgebracht.

Wat is de skill-creator-skill?

skill-creator is een meta-skill meegeleverd in de anthropics/skills-repo die Claude helpt nieuwe SKILL.md-bestanden voor je te schrijven. Vertel Claude wat je wilt dat de skill doet; skill-creator interviewt je voor de beschrijving, kiest verstandige allowed-tools en schrijft de SKILL.md naar de juiste map. Snelst mogelijke scaffold.

Wat doet disable-model-invocation?

Het instellen van disable-model-invocation: true in de frontmatter van je skill voorkomt dat Claude de skill automatisch triggert op basis van prompt-matching. De skill wordt alleen door de gebruiker aanroepbaar — het verschijnt in het slash-command-palet als /skill-name en draait alleen wanneer het expliciet wordt aangeroepen. Gebruik het voor destructieve of deterministische acties zoals /commit of /deploy.

Bouw een paar skills, ship ze in een project, kijk wat blijft hangen. Als je team tegen de typische "skill triggert niet"-valkuilen aanloopt over meerdere repo's en je een tweede paar ogen wilt op je .claude/skills/-setup, neem dan contact op — we lopen er graag doorheen.