Claude skill triggert niet? Fix het in 6 checks

Je installeerde een skill, je vroeg Claude om precies het ding te doen waar de skill voor is, en Claude ging verder alsof de skill niet bestaat. Geen foutmelding, geen waarschuwing, niets om op te greppen. Alleen stilte.

We zien dit constant. SkillProof installeert en test elke skill in onze catalogus op een schone machine, en niet triggeren is het meest voorkomende defect dat we vinden. Het is ook het best te repareren: vrijwel elke "skill werkt niet"-melding in onze testlogs is terug te voeren op een van zes oorzaken, en vijf daarvan sluit je in minder dan een minuut uit.

Loop eerst de checklist na. De rest van het artikel werkt elke check uit met symptoom, oorzaak en fix.

De 30-secondenchecklist

1. Juiste map? Het bestand moet op ~/.claude/skills/<skill-name>/SKILL.md staan, één map per skill, bestandsnaam exact SKILL.md.
2. Herstart? Claude scant skills bij de sessiestart. Wijzigingen halverwege een sessie blijven onzichtbaar tot je herstart.
3. Naamconflict? Twee skills met dezelfde name overschaduwen elkaar. Er overleeft er maar één.
4. Beschrijving te vaag? Noemt de beschrijving niet wat gebruikers letterlijk vragen, dan matcht Claude hem nooit. Dit is oorzaak nummer één.
5. Frontmatter geldig? Eén kapot YAML-teken maakt de hele skill onzichtbaar, geluidloos.
6. Conflicterende skill? Een andere geïnstalleerde skill met een overlappende beschrijving kan de match winnen.

Slagen alle zes checks en activeert de skill wel maar verandert de output niet, dan is dat een ander soort falen. Ga door naar als hij triggert maar niets doet.

Check 1: de skill staat in de verkeerde map

Symptoom. De skill verschijnt nooit wanneer je Claude vraagt "welke skills heb je geïnstalleerd?" Alsof je hem nooit hebt gekopieerd.

Oorzaak. Claude kijkt alleen op specifieke plekken: ~/.claude/skills/ voor persoonlijke skills en .claude/skills/ binnen een project voor projectskills. Daarbinnen is de indeling strikt: één map per skill, met daarin een bestand dat exact SKILL.md heet. De fouten die we het vaakst zien wanneer we community-skills installeren om te testen: de hele gecloonde repo kopiëren (waardoor het pad skills/some-repo/skills/pdf-helper/SKILL.md wordt, één niveau te diep), SKILL.md direct in ~/.claude/skills/ droppen zonder eigen map, en skill.md in kleine letters, wat sommige bestandssystemen vergeven en andere niet.

Fix. Verifieer vanuit de terminal:

ls ~/.claude/skills/*/SKILL.md

Elke skill die je verwacht moet precies één regel printen. Ontbreekt een skill of heeft zijn pad extra nesting, verplaats de map dan zodat SKILL.md één niveau onder skills/ zit. Onze installatiegids loopt de juiste indeling per platform door.

Check 2: je hebt niet herstart

Symptoom. De mappenstructuur klopt, je hebt hem twee minuten geleden gefixt, en Claude ziet de skill in hetzelfde gesprek nog steeds niet.

Oorzaak. Skilldiscovery gebeurt één keer, bij het opstarten. Claude leest de frontmatter van elke SKILL.md die het kan vinden en houdt die index vast voor de sessie. Een skill die je halverwege een sessie toevoegt, hernoemt of bewerkt bestaat niet wat de lopende sessie betreft.

Fix. In Claude Code: sluit af en start een nieuwe sessie. In de desktopapp: sluit volledig af met Cmd+Q op macOS (het venster sluiten telt niet) en open opnieuw. Deze is zo goedkoop om uit te sluiten dat we hem vóór al het diepere debuggen doen, zoals je een router herstart voordat je je provider belt.

Check 3: een naamconflict overschaduwt je skill

Symptoom. Je installeerde de skill, de map klopt, je hebt herstart, en de skilllijst toont óf niets nieuws óf een andere skill die op dezelfde naam reageert.

Oorzaak. Skillnamen moeten uniek zijn. Delen een persoonlijke skill en een projectskill een name, of leveren twee geïnstalleerde packs allebei een skill genaamd seo-audit, dan overschaduwt de één de ander zonder waarschuwing. We liepen er in ons eigen cataloguswerk tegenaan: twee marketingpacks naast elkaar geïnstalleerd leverden een stille dubbeling op, en degene die we wilden laadde nooit.

Fix. Zoek naar duplicaten:

grep -h "^name:" ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null | sort | uniq -d

Elke output betekent een conflict. Hernoem de map en het name-veld van de kopie die jij beheert, herstart, en check de lijst opnieuw.

Check 4: de beschrijving zegt nooit wanneer hij moet vuren

Symptoom. De skill staat in de lijst met geïnstalleerde skills. Vraag je erom bij naam, dan werkt hij prima. Vraag je om de taak in je eigen woorden, dan gebeurt er niets.

Oorzaak. Dit is de grote, en hij verdient zijn eigen sectie, dus hier de korte versie: Claude beslist of het een skill laadt door alleen het description-veld te lezen en dat te vergelijken met je verzoek. Zegt de beschrijving wat de skill ís in plaats van wanneer je hem gebruikt, dan komt de match er nooit. De skill is niet kapot. Hij maakt alleen geen reclame voor zichzelf.

Fix. Herschrijf de beschrijving rond de zinnen die gebruikers echt typen. De deep dive hieronder toont drie echte faalpatronen en hun herschrijvingen.

Check 5: de frontmatter is ongeldig

Symptoom. Map correct, herstart gedaan, geen naamconflict, en de skill verschijnt nog steeds helemaal niet in de lijst. Dit lijkt op check 1, maar het pad is in orde.

Oorzaak. Het YAML-blok bovenin SKILL.md kon niet geparsed worden, en een skill met onparseerbare frontmatter wordt simpelweg overgeslagen. De gebruikelijke boosdoeners uit onze testnotities: een ontbrekende afsluitende ---, een niet-gequote dubbele punt in de beschrijving ("Use for: reports" breekt de parser), gekrulde aanhalingstekens geplakt uit een blogpost of Google Doc, tabs als inspringing, en een name die de formatregels schendt (alleen kleine letters, cijfers en koppeltekens, maximaal 64 tekens; beschrijvingen maximaal 1024).

Fix. Open het bestand en bekijk het blok, of sla dat over: plak het in onze skill validator en die markeert parsefouten, formatschendingen en smart-quote-vervuiling direct. Parset de frontmatter en blijft de skill zich toch verstoppen, ga dan terug naar check 1, want op dat punt is het bijna altijd het pad.

Check 6: een andere skill wint de match

Symptoom. Je vraagt om de taak en er activeert wél een skill, alleen niet de jouwe. Of het gedrag verandert op een manier die past bij de instructies van een andere skill.

Oorzaak. Wanneer meerdere beschrijvingen een verzoek plausibel dekken, kiest Claude degene die als beste fit leest, en een bredere, zelfverzekerdere beschrijving verslaat doorgaans een smallere. Installeer een algemene "writing assistant"-skill naast je "release notes formatter" en de generalist kan elk schrijfverzoek opslokken, release notes incluis.

Fix. Slijp beide beschrijvingen aan zodat hun territoria niet overlappen, en voeg expliciete uitsluitingen toe. Een regel als "Do NOT use for release notes or changelogs" in de beschrijving van de generalist is grof en werkt. Beheer je de storende skill niet, schakel hem dan uit terwijl je de jouwe test, en beslis daarna of je ze echt allebei nodig hebt.

Waarom beschrijvingen falen: de deep dive

Wij testen elke skill die we opnemen, en triggerproblemen zijn reden nummer één waarom skills laag scoren in onze reviews. Geen kapotte scripts, geen slechte instructies. Beschrijvingen die nooit gematcht worden.

De mechaniek verklaart waarom. Bij het opstarten laadt Claude van elke skill alleen de name en description, ruwweg honderd tokens. De body, hoe briljant ook, blijft op schijf totdat de beschrijving een match wint tegen je verzoek. De beschrijving is een verkooppraatje aan een model, en de meeste auteurs schrijven hem als een museumbordje.

Hier de drie patronen die we het vaakst afstraffen, met herschrijvingen die ze in onze hertests fixten.

Patroon 1: het bescheiden etiket.

description: Helps with documents.

Niets hier sluit aan op iets wat een gebruiker zou typen. Vergelijk het met Anthropics DOCX-skill, die onze triggertests in één keer doorstond. Zijn beschrijving noemt het bestandsformaat, de acties en de formuleringen die hem moeten activeren. De herschrijving die dezelfde logica volgt:

description: Create, edit, and format Word documents (.docx).
  Use when the user mentions a Word doc, .docx file, memo,
  letter, or asks for a deliverable "as a document."

Patroon 2: de interne naam.

description: Runs the acme-formatter pipeline with corporate config.

Dit beschrijft de implementatie. Geen gebruiker vraagt Claude om "de acme-formatter-pipeline te draaien"; ze vragen om "dit rapport even opschonen voordat ik het naar een klant stuur". De herschrijving vertaalt de skill naar het vocabulaire van de gebruiker:

description: Reformat rough drafts into client-ready reports using
  Acme's corporate style. Use when the user wants to clean up,
  polish, or "make presentable" a document for external sharing.

Patroon 3: de gulzige deken.

description: Use for any writing task.

Het omgekeerde falen. Dit matcht alles, wat betekent dat hij botst met elke andere schrijfgerelateerde skill en vuurt wanneer het niet moet, en gebruikers zetten hem binnen een week uit. De herschrijving versmalt de claim en zet hekken langs de randen:

description: Write and edit marketing copy: landing pages, ads,
  and email campaigns. Do NOT use for technical docs, code
  comments, or internal memos.

De test die wij bij reviews toepassen: lees alleen de beschrijving en vraag je af: "als een gebruiker zijn verzoek natuurlijk typte, zouden deze woorden dan matchen?" Schrijf in de derde persoon, benoem wat de skill doet en wanneer hij van toepassing is, en gebruik de echte woorden die mensen gebruiken. Schrijf je een skill vanaf nul, dan behandelt onze auteursgids dit dieper, en Anthropics Skill Creator stelt standaard beschrijvingen op die deze test doorstaan.

Zo test je het triggeren op de juiste manier

De meeste mensen testen een skill door hem te noemen: "gebruik de invoice-skill hierop." Dat bewijst niets, want een skill bij naam noemen omzeilt de beschrijvingsmatch volledig. Het is een rookmelder testen door op de testknop te drukken en concluderen dat je huis brandveilig is.

Test zoals een gebruiker zou vragen, telkens in een verse sessie. Voor een skill die facturen uitleest drie formuleringen die moeten vuren:

• "Haal de totalen uit deze factuur-pdf's."
• "Ik heb 30 facturen van leveranciers, zet de bedragen en datums in een tabel."
• "Extraheer de regelitems uit deze rekening."

En twee die dat niet moeten:

• "Vat deze pdf voor me samen." (Generiek pdf-werk; het territorium van een andere skill.)
• "Schrijf een factuurmail aan deze klant." (Opstellen, niet extraheren.)

Doet een moet-vuren-formulering niets, vraag Claude dan direct: "Welke van je geïnstalleerde skills zou je voor dit verzoek gebruiken, en waarom?" Het antwoord toont je de matchredenering en wijst meestal rechtstreeks naar de zwakke plek in de beschrijving. Activeren de moet-niet-vuren-formuleringen de skill toch, dan heb je een gulzige deken en heb je uitsluitingen nodig. Dit is exact het protocol dat we in catalogustests draaien, en het is dezelfde discipline die de skill Systematic Debugging leert: eerst reproduceren, één variabele tegelijk, geloof het bewijs.

Als hij triggert maar niets doet

Stel dat de skill wél activeert. Je kunt dat bevestigen door Claude midden in het gesprek te vragen of er een skill laadde voor het verzoek; dat vertelt het je gewoon. Maar de output ziet er hetzelfde uit als voordat je iets installeerde.

Dat is geen triggerprobleem, en niets hierboven gaat het fixen. Het is een bodyprobleem: de instructies binnen de skill zijn te vaag om gedrag te veranderen, of de skill verwijst naar meegeleverde bestanden die niet bestaan op de paden die hij verwacht, of hij roept een script aan waarvan de dependencies nooit gedeclareerd zijn. De beschrijving kreeg de skill door de deur en binnen viel de inhoud om.

In onze tests is dit de andere grote emmer mislukkingen, ruwweg het spiegelbeeld van triggerdefecten, en het is de hoofdreden dat ongeveer de helft van de community-skills onze tests niet doorstaat. De snelle onderscheider: veranderde het gedrag helemaal niet, verdenk dan het triggeren; veranderde het gedrag maar slecht of gedeeltelijk, verdenk dan de body. Debug dienovereenkomstig, want de fixes overlappen niet.

Platformvalkuilen

Het skillformaat is overal identiek, maar discovery niet, en een skill die op de ene plek werkt kan er op een andere dood uitzien.

Claude Code leest mappen op schijf: ~/.claude/skills/ voor persoonlijk, .claude/skills/ per project. Beide laden; naamconflicten tussen de twee scopes lossen op naar één winnaar (check 3). Herstart de sessie na elke wijziging.

Claude Desktop leest je skillmappen niet. Skills upload je als zip via Settings, onder Capabilities, en de zip moet de map van de skill bovenin bevatten, niet de kale SKILL.md en ook geen extra wrapper-map. Een skill die prima triggert in Claude Code is op Desktop simpelweg afwezig totdat je hem daar apart uploadt.

claude.ai volgt dezelfde uploadroute als Desktop, met twee extra manieren om te verliezen: skills vereisen dat de code execution-feature op je abonnement aanstaat, en workspace-admins kunnen skills organisatiebreed uitschakelen, in welk geval niets wat je uploadt ooit zal vuren en geen foutmelding dat vertelt. Vraag het je admin voordat je een avond besteedt aan beschrijvingen herschrijven.

Nog één cross-platform-valkuil: een skillbody geschreven voor Claude Code die git aanroept of lokale projectbestanden leest, triggert correct op claude.ai en faalt vervolgens in de sandbox. Dat is een bodyprobleem in een platformkostuum.

Wanneer je stopt met debuggen

Is het je eigen skill, ga dan door, want elke fix hierboven is permanent en de validator plus de test met vijf formuleringen brengen je er. Is het een skill van een derde en heb je meer dan twintig minuten verbrand aan andermans description-veld, dan is het redelijk hem in te ruilen voor één die deze checklist al heeft doorlopen: elke skill op onze best-of-lijsten doorstond triggertests op een schone machine voordat we hem opnamen.

FAQ

Hoe bevestig ik dat een skill überhaupt geïnstalleerd is?

Vraag Claude "welke skills heb je geïnstalleerd?" in een verse sessie. Staat je skill niet in het antwoord, dan zit het probleem in discovery (checks 1, 3 en 5: map, conflict, frontmatter), niet in het triggeren. Staat hij wel in de lijst maar activeert hij nooit, dan zit het probleem in de beschrijving (checks 4 en 6).

Kan ik de skill niet gewoon forceren door hem te noemen?

Ja. "Gebruik de docx-skill om deze memo te schrijven" laadt de skill direct, en het is een prima workaround terwijl je debugt. Een fix is het niet: een skill die je elke keer bij naam moet oproepen is een skill met een kapotte beschrijving, en je vergeet hem op te roepen precies wanneer het ertoe doet.

Waarom werkt mijn skill in Claude Code maar niet op Desktop of claude.ai?

Verschillende discovery-paden. Claude Code leest mappen op schijf; Desktop en claude.ai zien alleen skills die via Settings zijn geüpload als zip met de skillmap bovenin. Bevestig op claude.ai ook dat code execution aanstaat en dat je workspace-admin skills niet volledig heeft uitgeschakeld.

Breekt te veel skills installeren het triggeren?

Niet direct. Vijftig skills kosten een paar duizend tokens metadata, en dat is goedkoop. Het echte risico is overlap: hoe meer beschrijvingen je installeert, hoe waarschijnlijker dat twee ervan hetzelfde territorium claimen, en dan wint soms de verkeerde (check 6). Installeer op behoefte, en snoei skills die nooit vuren.

Mijn skill triggerde gisteren wel en vandaag niet. Is dat normaal?

Af en toe, ja. Matchen is modelgedreven, geen regex, dus een beschrijving op het randje vuurt op de ene formulering en mist een bijna identieke. Is een skill wispelturig in plaats van dood, behandel hem dan als een zwakke beschrijving: voeg de exacte zinnen die misten toe aan het description-veld, herstart en test opnieuw. Betrouwbare skills triggeren op elke redelijke formulering, en daarom testen wij met vijf, niet met één.