Waarom de helft van Claude-skills niet werkt

Als je hebt gezocht op "claude skill werkt niet," hier het korte antwoord: het ligt waarschijnlijk niet aan jou. We installeren en testen elke skill die we vermelden, op een schone setup, volgens de eigen instructies van de auteur, en scoren het resultaat vervolgens tegen Claude zonder enige skill. De faalpatronen zijn zo consistent dat we ze inmiddels op frequentie kunnen rangschikken.

De langere versie heeft cijfers, en elk cijfer is berekend uit onze publieke testdata. Onze catalogus telt momenteel 73 skills. 45 hebben het volledige protocol doorlopen; 28 staan nog in de testwachtrij. Van de 45 geteste skills kregen er 35 een schone goedkeuring. De overige 10, oftewel 22%, kregen het oordeel "werkt met setup," wat betekent dat de skill zoals geleverd niet werkte en wij moesten ingrijpen: een ontbrekende dependency installeren, een MCP-verbinding opzetten, of configuratie invullen die de README nooit noemde. Over de hele catalogus blijft er dan 35 van de 73 skills over, 48%, met vandaag het oordeel "getest, werkt." Iets minder dan de helft. Vandaar de titel.

En dat onderschat het probleem nog, want de 45 geteste skills zijn al overlevenden. Onze crawler doorzoekt GitHub elke 12 uur en heeft 267 repositories in de discovery-wachtrij gezet. Skills die verlaten, gedupliceerd of overduidelijk kapot zijn, vallen af bij de triage en halen nooit een gescoorde test. De faalpatronen hieronder zijn wat we vinden in de skills die goed genoeg zijn om te testen.

De cijfers, voor het verhaal begint

Onze score is 25 punten over vier criteria: installeert schoon (5), triggert betrouwbaar (5), output versus baseline (10), documentatie en eerlijkheid (5), genormaliseerd naar een score op 10. Zo scoorden 45 geteste skills op elk criterium:

Criterium	Perfecte score	Minstens één punt verloren	Scoorde 3/5 of slechter
Installeert schoon (/5)	34 van 45	11 (24%)	8 (18%)
Triggert betrouwbaar (/5)	14 van 45	31 (69%)	0
Output vs. baseline (/10)	2 van 45 op 10	—	5 op de vloer van 7/10
Documentatie & eerlijkheid (/5)	5 van 45	40 (89%)	12 (27%)

Geen enkele van de 45 skills scoorde een perfecte 25. De totaalscores lopen van 6,8 tot 9,6 op 10, met een mediaan van 8,4, en 9 van de 45 zitten onder de 8,0. De vier faalpatronen komen overeen met de vier rijen van de tabel.

Faalpatroon 1: de triggerbeschrijving die nooit afgaat

Dit is het meest voorkomende defect in onze data. Slechts 14 van de 45 geteste skills, 31%, scoorden een perfecte 5/5 op "triggert betrouwbaar." De andere 31 vuren inconsistent: ze missen formuleringen die ze zouden moeten oppikken, of ze activeren bij ongerelateerd werk. Let wel op die nul in de laatste kolom van de tabel. Geen enkele geteste skill scoorde lager dan 4/5 op triggering, en dat is overlevingsbias, geen kwaliteit. Een skill met een volledig dode trigger wordt bij de triage eruit gehaald en haalt nooit een score. De skills die de test bereiken, missen alleen af en toe.

Het mechanisme is onspectaculair. Wanneer je een prompt stuurt, beslist Claude of hij een skill laadt op basis van precies één ding: het description-veld in de SKILL.md-frontmatter. Niet de README, niet de code, niet de 400 regels zorgvuldige instructies eronder. Als de beschrijving jouw woorden niet koppelt aan de taak van de skill, ligt de skill werkloos in je map en concludeer je dat Claude skills niet werken.

Auteurs blijven dat veld schrijven alsof het een landingspagina is. Twee geanonimiseerde paren uit onze tests, licht geparafraseerd:

Een beschrijving die nooit afgaat:

"Geef je contentworkflow een boost met AI-aangedreven schrijfintelligentie. Schrijf beter, sneller, slimmer."

Dezelfde taak, geschreven door een skill die 5/5 scoorde op triggering:

"Gebruik wanneer de gebruiker een Word-document (.docx) wil aanmaken, lezen of bewerken. Trigger bij elke vermelding van 'Word-document', '.docx', of een verzoek om een rapport, memo of brief als Word-bestand. Niet gebruiken voor PDF's of spreadsheets."

Nog een, uit de datacategorie:

"Jouw ultieme SQL-assistent voor alles met data."

Tegenover:

"Gebruik wanneer de gebruiker vraagt om een SQL-query te schrijven, te debuggen of te optimaliseren, een tabel of schema noemt, of een queryfout plakt. Niet triggeren bij algemene datavragen zonder query."

Het verschil zit niet in schrijftalent. De goede beschrijvingen noemen de exacte zinnen die een gebruiker zou typen, en ze zeggen wanneer níet te triggeren. In ons protocol testen we beide richtingen: de prompts die de skill claimt te verwerken, aanpalende formuleringen, en bewust ongerelateerde verzoeken. De meeste 4/5-scores komen van skills die de eerste check doorstaan en struikelen bij de tweede of derde.

Dit kun je checken voordat je iets installeert. SKILL.md is platte markdown, leesbaar op GitHub. Als de beschrijving ook als billboard zou kunnen dienen, gaat de skill onderpresteren. Als je je eigen skill debugt, plak hem in onze gratis skill-validator, die marketingtaal in beschrijvingen samen met structurele problemen signaleert.

Faalpatroon 2: installatierot

Alle 10 van onze "werkt met setup"-oordelen zijn installatiefouten van een of andere soort. Het patroon is duidelijk zichtbaar in de scores: skills die zonder meer slaagden, scoren gemiddeld 4,97 van de 5 op installatie. De setup-oordeel-skills scoren gemiddeld 3,2.

Wat er daadwerkelijk misging, uit onze testnotities:

• Onvermelde skill-dependencies. Een factuurextractie-skill die stilzwijgend vereist dat de PDF-skill eerst geïnstalleerd is voor gescande documenten, plus een eenregelige locale-aanpassing voor Europese datumnotaties die de README niet vermeldt. De output was echt goed (8/10) zodra we dat hadden uitgevogeld. Het uitvogelen kostte de avond.
• Onvermelde servicedependencies. Een planningsskill die alleen adviserend is totdat je een agenda-MCP verbindt. Een inbox-triage-skill die Gmail of Outlook nodig heeft. Een metrics-skill die uitgaat van een bestaande analytics-export. Geen van deze vereisten is onredelijk. Ze horen allemaal op de eerste regel van de README te staan, niet in een supportticket.
• Verkeerde mapdiepte. De klassieker. Instructies die de skill op skills/naam/naam/SKILL.md laten belanden, één niveau te diep, waar Claude hem nooit vindt. De skill "installeert" zonder foutmelding en triggert dan nooit, waardoor je achter faalpatroon 1 aan gaat terwijl het eigenlijke probleem een pad is.
• Instructies geschreven voor een oudere Claude Code. Git-workflow is een mild geval: commits en branchbeheer werken meteen, maar de begeleiding bij interactieve rebases gaat uit van mogelijkheden die Claude Code bewust blokkeert, dus die stappen moet je zelf handmatig doen.

Eén eerlijke uitzondering die het noemen waard is: brand-guidelines krijgt een setup-oordeel omdat hij nutteloos is totdat je je eigen merkpalet en tone-of-voice invult, en dat staat er ook gewoon. Setup by design is prima. Setup by omission is het faalpatroon.

Het teken, vóór installatie: een README waarvan de installatiesectie één vage regel is. Vergelijk dat met het installatieblok van een skill die 5/5 scoorde, zoals DOCX. Specifieke commando's, specifieke paden, vereisten expliciet genoemd. Het is twee regels lang omdat twee regels alles is wat een werkende installatie nodig heeft.

Faalpatroon 3: de skill triggert en niets wordt beter

Het subtielste faalpatroon, en de reden dat onze scoring output vs. baseline weegt met 10 van de 25 punten, dubbel zoveel als elk ander criterium. De test is bot: we laten dezelfde echte taak twee keer draaien, één keer met de skill geïnstalleerd en één keer zonder, en vergelijken. Een skill moet naakte Claude verslaan of hij heeft geen reden om context in te nemen.

De vloer in onze geteste set is 7/10, en vijf skills zitten daar precies op. Dat betekent dat zelfs onder skills die slagen, ruwweg één op de negen een verbetering levert die je pas met een side-by-side vergelijking zou opmerken. Onder de 7 overleven skills de lijst niet, en de discovery-wachtrij zit vol kandidaten in dat bereik: "schrijfverbetering"-skills in categorieën waar het basismodel al sterk is, en skills die neerkomen op één system prompt die zegt: wees uitstekend.

Slechts twee skills verdienden een 10/10 op output, en ze laten zien hoe een verdiende delta eruitziet. Frontend-design kreeg dezelfde landingspagina-briefing met en zonder skill; de versie mét skill had een echte type-schaal en een doelbewust palet, en niets van de neon-verloop-tells die standaard output kenmerken. Humanizer haalde het overmatige gebruik van gedachtestreepjes en "delve"-achtig vocabulaire zo grondig uit AI-concepten dat twee redacteuren het resultaat niet betrouwbaar als AI-geassisteerd konden aanmerken. Negentien van de 45 skills scoorden 9 of hoger op output. Het skill-concept werkt. Het werkt alleen niet automatisch.

Faalpatroon 4: de README schrijft cheques die de skill niet kan verzilveren

Documentatie en eerlijkheid is het zwakste criterium in de hele dataset. Vijf van de 45 skills scoorden 5/5. Veertig verloren punten, en 12 scoorden 3/5. Nogmaals: de gemiddelde geteste skill heeft betere output dan documentatie.

Wat hier punten kost, op volgorde van hoe vaak we het zien:

• Beloftes die de test tegenspreekt. Een README die claimt "werkt met elk factuurformaat" terwijl de skill een locale-instelling nodig heeft voor niet-Amerikaanse datums. Een pitch van "volledige git-automatisering" op een skill die in Claude Code helemaal geen interactieve rebases kan uitvoeren. We beschouwen dit meestal niet als liegen. We zien het als auteurs die de skill documenteren die ze van plan waren te schrijven, in plaats van de skill die ze daadwerkelijk schreven.
• Ontbrekende vereisten. Elke onvermelde dependency uit faalpatroon 2 is ook een documentatiefout, en dat is waarom setup-oordeel-skills gemiddeld 3,4/5 scoren op documentatie terwijl schone passes gemiddeld 3,97 halen.
• Stilte over gedrag dat je zou willen weten. Of de skill naar huis belt, wat hij met de inhoud van je bestanden doet, tegen welke modelversies hij is geschreven. Zeldzame maar ernstige gevallen, verborgen netwerkcalls of instructies met de vorm van prompt-injectie diep in het bestand, zijn de reden dat dit criterium bestaat. Wij lezen elke SKILL.md die we vermelden, van begin tot eind. Doe hetzelfde voor alles wat buiten een geteste directory vandaan komt.

We hebben de regressie niet formeel getoetst, maar de informele observatie houdt stand over 45 tests: het aantal badges in een README en de kwaliteit van de installatiesectie bewegen tegengesteld.

Wat de top doet, anders dan de rest

Zes skills, 13% van alles wat we hebben getest, delen de topscore van 9,6/10: DOCX, skill-creator en frontend-design uit Anthropics officiële repo, test-driven-development en systematic-debugging uit Jesse Vincents superpowers-collectie, en humanizer uit de community. Nog eens zes, waaronder xlsx, pdf en sql-queries, zitten op 9,2. Wat de topgroep gemeen heeft, is controleerbaar:

Perfecte installaties en perfecte triggers, zonder uitzondering. Alle zes scoorden 5/5 op beide. Wat er ook aan creatieve energie in deze skills is gestoken, geen ervan is besteed aan de beschrijving; die lezen als specificaties, met expliciete triggerzinnen en expliciete uitsluitingen.

Toegespitst op waar het basismodel slecht in is. Claude heeft geen skill nodig om proza te schrijven. Wel om een echte .docx met stijlen en bijgehouden wijzigingen te produceren, of om te stoppen met een race condition "oplossen" door te gokken. Systematic-debugging verdiende zijn score op een bug die Claude al drie keer had "gefixt" zonder hem ooit echt te fixen; de hypothese-test-verifieer-lus van de skill maakte een einde aan het gokken. Elke topscorer richt zich op een gat dat je in één zin kunt benoemen.

Documentatie die zichzelf onderverkoopt. De laagste documentatiescore onder de zes is een 4. Hun READMEs vermelden vereisten en erkennen beperkingen; bijvoeglijke naamwoorden zijn schaars. Het blijkt dat de auteurs die hun eigen installatie-instructies testen, ook beschrijvingen schrijven die triggeren. Vakmanschap correleert met zichzelf.

Ook het vermelden waard: pedigree helpt, maar beslist niet. Tien van de elf door Anthropic geschreven skills die we testten, slaagden zonder meer, en de uitzondering is setup by design. Maar een derde van de topgroep is één community-auteur die zich erin verdiepte, en genoeg community-skills scoren hoger dan officiële in hun categorie. De meest gesterde repository in onze discovery-wachtrij heeft ruim 85.000 sterren en nog steeds geen oordeel, want sterren zijn geen test.

Als je skills aan het kiezen bent

Gebruik geteste skills. Dat is een zelfbedienende zin op een site waarvan het hele product het testen van skills is, dus hier is de redenering om zelf te checken: de vier faalpatronen hierboven zijn onzichtbaar in een GitHub-listing. Sterren meten marketingbereik. Een README meet het optimisme van de auteur. De enige manier om te weten of een skill de baseline verslaat, is de baseline daadwerkelijk draaien, wat ons ongeveer een avond per skill kost, keer 45 tot nu toe.

Begin met de beste skills van 2026 voor de tier-list over alle categorieën heen, of ga direct naar jouw categorie, bijvoorbeeld de beste coding-skills. Elke vermelding linkt naar de testnotities, inclusief de workarounds voor skills die ze nodig hebben.

Als je er een aan het schrijven bent

De faalpatronen dienen ook als checklist, en drie van de vier zijn goedkoop te vermijden.

Schrijf de beschrijving als triggerspecificatie: de zinnen die een gebruiker zou typen, plus wat de skill moet negeren. Test daarna de installatie-instructies op een machine die niet van jou is, of op zijn minst in een schone map, en vermeld elke dependency, inclusief andere skills en MCP-verbindingen. Draai onze skill-validator voordat je publiceert; die vangt de structurele problemen en het billboard-beschrijvingsprobleem binnen enkele seconden. Voor de volledige walkthrough, van frontmatter tot publicatie, zie hoe je je eigen Claude-skill schrijft.

Het vierde faalpatroon, de baseline verslaan, is het patroon dat echt nadenken vereist. Voordat je iets schrijft: laat je doeltaak door Claude lopen zonder skill. Als de output al goed is, heb je geen skill, maar een README voor een functie die Claude standaard al levert. De 9,6-tier bestaat omdat die auteurs echte gaten vonden. Ironisch genoeg is het beste gereedschap voor de klus zelf ook een skill: skill-creator bouwde in één sessie een werkende interne skill voor ons, en de beschrijvingsoptimalisatiestap verbeterde meetbaar de triggering in onze test.

Het ongemakkelijke deel

Niets in deze data zegt dat het ecosysteem slecht is. Het zegt dat het ecosysteem ongereviewd is, wat een ander probleem is met een bekende vorm. Browserextensies rond 2010, npm rond 2016: een lage drempel om te publiceren plus geen verificatielaag levert een catalogus op waar het mediane item middelmatig is, de beste items echt uitstekend zijn, en geen enkel oppervlaktesignaal ze uit elkaar houdt. Skills die onze installatiecheck niet doorstaan, hebben honderden sterren. Twee van onze zes topscorers komen uit repo's waar de meeste mensen nog nooit van hebben gehoord.

De gebruikelijke correctie komt uiteindelijk, een mix van reviewlagen en reputatie. Tot het zover is, ligt de last bij wie installeert, en de cijfers hierboven zijn hoe die last eruitziet: 22% van de geteste skills kapot zoals geleverd, 69% met onvolmaakte triggers, 89% met documentatie die punten verloor. Wij blijven de data hoe dan ook publiceren. Het volledige protocol en de scoringsrubriek staan op de methodologiepagina, en elk cijfer in dit artikel is reproduceerbaar vanuit de testnotities per skill.

Veelgestelde vragen

Waarom triggert mijn Claude-skill niet?

Check drie dingen in volgorde. Ten eerste het pad: SKILL.md moet staan op ~/.claude/skills/<naam>/SKILL.md, niet één map dieper; een verkeerd genest skill faalt stilzwijgend. Ten tweede de description in de frontmatter: als die als een slogan leest, heeft Claude niets om jouw prompt tegen te matchen. Herschrijf hem zodat hij de exacte zinnen noemt die je daadwerkelijk typt, of draai hem door de skill-validator. Ten derde: prompt met woorden letterlijk uit de beschrijving; als dat wel triggert, is de dekking van de beschrijving je probleem.

Hoe bepalen jullie of een skill "werkt"?

Schone installatie op een verse setup volgens de eigen instructies van de auteur, triggerchecks in beide richtingen (gaat af bij geclaimde prompts, blijft stil bij ongerelateerde), en een echte taak gescoord tegen een baseline zonder skill, goed voor 10 van de 25 punten. Oordelen: pass, works-with-setup, of nog-in-wachtrij. De methodologiepagina heeft de rubriek; elke skillpagina heeft de notities.

Zijn officiële Anthropic-skills betrouwbaarder dan community-skills?

Gemiddeld betrouwbaarder: 10 van de 11 die we testten, slaagden zonder meer, en de uitzondering (brand-guidelines) vereist expres configuratie. Maar het gemiddelde is niet het interessante getal. Twee van onze zes hoogst scorende skills komen uit de repo van één community-auteur, en humanizer, een community-skill, is een van slechts twee skills die 10/10 scoorden op output. Testresultaten verslaan herkomst.

Betekenen deze resultaten dat ik Claude-skills moet vermijden?

Het tegenovergestelde. De geteste laag is stilletjes uitstekend: 19 van de 45 skills scoorden 9 of hoger op output vs. baseline, en de top zes zijn het verschil tussen Claude als chatvenster en Claude als tool die afgewerkt werk levert. De bevinding is smaller dan "skills werken niet." Het is dat de helft van wat gepubliceerd wordt een defect heeft dat je niet ziet in de listing, dus installeer op basis van testdata, niet van sterren.