Troubleshooting skills

Wat je leert

Geschatte tijd: 15 minuten

Aan het einde van deze les kun je:

De skills validator gebruiken om structurele problemen op te vangen voordat je gaat debuggen
Veelvoorkomende problemen met skill triggering en laden diagnosticeren en oplossen
Skill priority conflicten tussen enterprise, personal, project en plugin skills oplossen
Runtime errors debuggen, inclusief ontbrekende dependencies, permissions en path problemen

(4 minuten)

Wanneer skills niet werken zoals verwacht, valt het probleem meestal in een paar voorspelbare categorieën. Deze video behandelt elk ervan — van skills die niet triggeren tot priority conflicten tot runtime failures — en geeft je een systematische aanpak voor troubleshooting. Je leert ook over de skills validator tool en hoe je claude --debug kunt gebruiken om loading issues te diagnosticeren.

Belangrijkste punten

Begin met de skills validator tool — deze vangt structurele problemen op voordat je tijd besteedt aan het debuggen van andere dingen
Als een skill niet triggert , is de oorzaak bijna altijd de description — voeg trigger phrases toe die aansluiten bij hoe je werkelijk requests formuleert
Als een skill niet laadt , controleer dat SKILL. md zich in een benoemde directory bevindt (niet in de skills root) en de bestandsnaam exact SKILL. md is
Als de verkeerde skill wordt gebruikt , zijn je descriptions te vergelijkbaar — maak ze duidelijker van elkaar onderscheiden
Voor runtime errors , controleer dependencies, file permissions (chmod +x) en path separators (gebruik overal forward slashes)

Wanneer skills niet werken, valt het probleem meestal in een van enkele categorieën: de skill triggert niet, laadt niet, heeft conflicten of faalt tijdens runtime. Het goede nieuws is dat de meeste fixes vrij eenvoudig zijn.

De Skills Validator gebruiken

Het eerste wat je kunt proberen is de agent skills verifier command. Installatiestappen verschillen per besturingssysteem, maar uv gebruiken is de gemakkelijkste manier om het snel in te stellen.

Eenmaal geïnstalleerd, navigeer je naar je skill directory of voer je de command overal uit. De validator vangt structurele problemen op voordat je tijd besteedt aan debuggen.

Skill triggert niet

Je skill bestaat en slaagt validatie, maar Claude gebruikt het niet wanneer je dat verwacht. De oorzaak is bijna altijd de description.

Claude gebruikt semantic matching, dus je request moet overlappen met de betekenis van de description. Als er niet genoeg overlap is, geen match. Dit kun je doen:

Controleer je description tegen hoe je werkelijk requests formuleert
Voeg trigger phrases toe die gebruikers werkelijk zouden zeggen
Test met variaties zoals "help me profile this," "why is this slow? ", "make this faster"
Als een variatie niet triggert, voeg die keywords toe aan je description

Skill laadt niet

Als je skill niet verschijnt wanneer je Claude vraagt "what skills are available," controleer dan deze structurele vereisten:

Het SKILL. md bestand moet zich in een benoemde directory bevinden, niet in de skills root
De bestandsnaam moet exact SKILL. md zijn — "SKILL" in hoofdletters, "md" in kleine letters

Voer claude --debug uit om loading errors te zien. Zoek naar berichten die je skill naam noemen. Soms wijst dit je direct naar het probleem.

Verkeerde skill wordt gebruikt

Als Claude de verkeerde skill gebruikt of lijkt verward tussen skills, zijn je descriptions waarschijnlijk te vergelijkbaar. Maak ze duidelijker. Zo specifiek mogelijk zijn helpt Claude niet alleen om te beslissen wanneer je skill moet worden gebruikt — het voorkomt ook conflicten met andere vergelijkbare skills.

Skill Priority Conflicten

Als je personal skill wordt genegeerd, kan een enterprise of skill met hogere prioriteit dezelfde naam hebben.

Als er bijvoorbeeld een enterprise "code-review" skill is en je hebt ook een personal "code-review" skill, wint de enterprise skill elke keer. Je opties zijn:

Hernoem je skill naar iets duidelijkers (dit is meestal het gemakkelijkere pad)
Praat met je admin over de enterprise skill

Plugin Skills verschijnen niet

Een plugin geïnstalleerd maar kun je de skills niet zien? Wis de cache, herstart Claude Code en herinstalleer.

Als skills nog steeds niet verschijnen na dat, kan de plugin structuur verkeerd zijn. Dit is wanneer de validator tool echt zijn waarde bewijst.

Runtime Errors

De skill laadt maar faalt tijdens uitvoering. Een paar veelvoorkomende oorzaken:

Ontbrekende dependencies: Als je skill externe packages gebruikt, moeten deze geïnstalleerd zijn. Voeg dependency info toe aan je skill description zodat Claude weet wat nodig is.
Permission issues: Scripts hebben execute permission nodig. Voer chmod +x uit op alle scripts waarnaar je skill verwijst.
Path separators: Gebruik overal forward slashes, zelfs op Windows.

Snelle Troubleshooting Checklist

**Triggert niet? ** Verbeter je description en voeg trigger phrases toe.
**Laadt niet? ** Controleer je path, bestandsnaam en YAML syntax.
**Verkeerde skill gebruikt? ** Maak descriptions duidelijker van elkaar onderscheiden.
**Wordt overschaduwd? ** Controleer de priority hierarchy en hernoem indien nodig.
**Plugin skills ontbreken? ** Wis cache en herinstalleer.
**Runtime failure? ** Controleer dependencies, permissions en paths.

Lesreflectie

Ben je in je eigen werk tegen een van deze troubleshooting scenario's aangelopen? Welke fix zou je het meeste tijd hebben bespaard?
Hoe zou je een proces opzetten om skills te valideren voordat je ze met je team deelt?

Cursus afsluiting

Gefeliciteerd met het voltooien van Introduction to Agent Skills! Je hebt geleerd hoe je skills in Claude Code kunt maken, configureren, delen en troubleshooten. Wanneer je skills voor je eigen workflows gaat bouwen, onthoud dat de beste skills voortkomen uit echte pijnpunten — begin met de instructies die je jezelf het meest herhaald ziet geven.

Feedback

We horen graag hoe je skills in je werk gebruikt, plus eventuele feedback over deze cursus. Deel je feedback hier.