Why Half of Claude Skills Don't Work — Test Data

If you searched “claude skill not working,” here is the short version: it is probably not you. We install and test every skill we list, on a clean setup, following the author’s own instructions, and then score the result against Claude with no skill at all. The failure patterns are so consistent that we can now rank them by frequency.

The longer version has numbers, and every one of them is computed from our public test data. Our catalogue currently holds 73 skills. 45 have been through the full protocol; 28 are still in the test queue. Of the 45 tested, 35 earned a clean pass. The other 10, or 22%, got a “works with setup” verdict, meaning the skill as shipped did not work and we had to intervene: install a missing dependency, wire up an MCP connection, or fill in configuration the README never mentioned. Across the whole catalogue, that leaves 35 of 73 skills, 48%, with a verdict of “tested, works” today. Slightly less than half. Hence the title.

And that understates the problem, because the 45 tested skills are already survivors. Our crawler sweeps GitHub every 12 hours and has filed 267 repositories into the discovery queue. Skills that are abandoned, duplicated, or obviously broken get cut at triage and never reach a scored test. The failure modes below are what we find in the skills good enough to be worth testing.

The numbers, before the storytelling

Our score is 25 points across four criteria: installs cleanly (5), triggers reliably (5), output vs. baseline (10), docs and honesty (5), normalized to a score out of 10. Here is how 45 tested skills did on each:

Criterion	Perfect score	Docked at least a point	Scored 3/5 or worse
Installs cleanly (/5)	34 of 45	11 (24%)	8 (18%)
Triggers reliably (/5)	14 of 45	31 (69%)	0
Output vs. baseline (/10)	2 of 45 at 10	—	5 sat at the 7/10 floor
Docs & honesty (/5)	5 of 45	40 (89%)	12 (27%)

Not one skill of the 45 scored a perfect 25. Overall scores run from 6.8 to 9.6 out of 10, with a median of 8.4, and 9 of the 45 land below 8.0. The four failure modes map onto the table’s four rows.

Failure mode 1: the trigger description that never fires

This is the most widespread defect in our data. Only 14 of 45 tested skills, 31%, scored a perfect 5/5 on “triggers reliably.” The other 31 fire inconsistently: they miss phrasings they should catch, or they activate on unrelated work. Notice the zero in that table’s last column, though. No tested skill scored below 4/5 on triggering, and that is survivorship, not quality. A skill whose trigger is completely dead gets caught at triage and never earns a score. The ones that reach testing merely misfire.

The mechanism is unglamorous. When you send a prompt, Claude decides whether to load a skill based on one thing: the description field in the SKILL.md frontmatter. Not the README, not the code, not the 400 lines of careful instructions below the frontmatter. If the description does not connect your words to the skill’s job, the skill sits in your directory doing nothing, and you conclude that Claude skills don’t work.

Authors keep writing that field as if it were a landing page. Two anonymized pairs from our testing, lightly paraphrased:

A description that never fires:

“Supercharge your content workflow with AI-powered writing intelligence. Write better, faster, smarter.”

The same job, written by a skill that scored 5/5 on triggering:

“Use when the user wants to create, read, or edit Word documents (.docx). Trigger on any mention of ‘Word doc’, ‘.docx’, or a request for a report, memo, or letter as a Word file. Do not use for PDFs or spreadsheets.”

One more, from the data category:

“Your ultimate SQL assistant for everything data.”

Versus:

“Use when the user asks to write, debug, or optimize a SQL query, names a table or schema, or pastes a query error. Do not trigger on general data questions with no query involved.”

The difference is not writing talent. The good descriptions name the exact phrases a user would type, and they say when not to fire. In our protocol we test both directions: the prompts the skill claims to handle, adjacent phrasings, and deliberately unrelated requests. Most of the 4/5 scores come from skills that pass the first check and stumble on the second or third.

You can check this before installing anything. SKILL.md is plain markdown, readable on GitHub. If the description could double as a billboard, the skill will underperform. If you are debugging your own, paste it into our free skill validator, which flags marketing-speak descriptions along with structural problems.

Failure mode 2: install rot

All 10 of our “works with setup” verdicts are install failures of one kind or another. The pattern shows up cleanly in the scores: skills that passed outright average 4.97 out of 5 on installation. The setup-verdict skills average 3.2.

What actually broke, from our test notes:

• Undeclared skill dependencies. An invoice-extraction skill that quietly requires the PDF skill to be installed first for scanned documents, plus a one-line locale edit for European date formats that the README does not mention. Output was genuinely good (8/10) once we figured that out. The figuring-out took the evening.
• Undeclared service dependencies. A scheduling skill that is advisory-only until you connect a calendar MCP. An inbox-triage skill that needs Gmail or Outlook wired up. A metrics skill that assumes an analytics export exists. None of these are unreasonable requirements. All of them belong in the first line of the README, not in a support issue.
• Wrong directory depth. The classic. Instructions that leave the skill at skills/name/name/SKILL.md, one level too deep, where Claude never finds it. The skill “installs” without an error message and then never triggers, which sends you chasing failure mode 1 when the actual problem is a path.
• Instructions written for an older Claude Code. Git-workflow is a mild case: commits and branch management work immediately, but the interactive rebase guidance assumes capabilities Claude Code deliberately blocks, so those steps are yours to run manually.

One honest exception worth naming: brand-guidelines carries a setup verdict because it is useless until you fill in your own brand palette and voice, and it says so plainly. Setup by design is fine. Setup by omission is the failure mode.

The tell, before you install: a README whose install section is one vague line. Compare it against the install block on any skill that scored 5/5, like DOCX. Specific commands, specific paths, prerequisites stated. It is two lines long because two lines is all a working install needs.

Failure mode 3: the skill fires and nothing improves

The subtlest failure, and the reason our scoring weights output vs. baseline at 10 of 25 points, double any other criterion. The test is blunt: we run the same real task twice, once with the skill installed and once without, and compare. A skill has to beat naked Claude or it has no reason to occupy context.

The floor in our tested set is 7/10, and five skills sit exactly on it. That means even among skills that pass, roughly one in nine delivers an improvement you would need a side-by-side to notice. Below 7, skills do not survive to a listing, and the discovery queue is full of candidates in that range: “writing improvement” skills in categories where the base model is already strong, and skills that are one system prompt saying, in effect, be excellent.

Only two skills earned 10/10 on output, and they show what an earned delta looks like. Frontend-design got the same landing-page brief with and without the skill; the with-skill version had a real type scale and an intentional palette, and none of the neon-gradient tells that mark default output. Humanizer stripped the em-dash overuse and “delve”-class vocabulary from AI drafts thoroughly enough that two editors could not reliably flag the result as AI-assisted. Nineteen of 45 skills scored 9 or better on output. The skill concept works. It just does not work automatically.

Failure mode 4: the README writes checks the skill can’t cash

Docs and honesty is the weakest criterion in the entire dataset. Five of 45 skills scored 5/5. Forty lost points, and 12 scored 3/5. To repeat: the median tested skill has better output than documentation.

What costs points here, in order of how often we see it:

• Promises the test contradicts. A README that claims “works with any invoice format” while the skill needs a locale setting for non-US dates. A “full git automation” pitch on a skill that cannot perform interactive rebases in Claude Code at all. We do not treat this as lying, usually. We treat it as authors documenting the skill they intended to write rather than the one they wrote.
• Missing prerequisites. Every undeclared dependency from failure mode 2 is also a documentation failure, which is why setup-verdict skills average 3.4/5 on docs while clean passes average 3.97.
• Silence about behavior you would want to know. Whether the skill phones home, what it does with your file contents, which model versions it was written against. Rare but serious cases, hidden network calls or prompt-injection-shaped instructions buried mid-file, are why this criterion exists at all. We read every SKILL.md we list, top to bottom. You should do the same for anything from outside a tested directory.

We have not run the regression, but the informal observation holds across 45 tests: README badge count and install-section quality move in opposite directions.

What the top tier does differently

Six skills, 13% of everything we have tested, share the top score of 9.6/10: DOCX, skill-creator, and frontend-design from Anthropic’s official repo, test-driven-development and systematic-debugging from Jesse Vincent’s superpowers collection, and humanizer from the community. Another six, including xlsx, pdf, and sql-queries, sit at 9.2. What the top tier has in common is checkable:

Perfect installs and perfect triggers, without exception. All six scored 5/5 on both. Whatever creative energy went into these skills, none of it was spent on the description; those read like specifications, with explicit trigger phrases and explicit exclusions.

Scoped to what the base model is bad at. Claude does not need a skill to write prose. It does need one to produce a real .docx with styles and tracked changes, or to stop “fixing” a race condition by guessing. Systematic-debugging earned its score on a bug Claude had previously fixed three times without fixing it once; the skill’s hypothesis-test-verify loop ended the guessing. Every top scorer targets a gap you can name in one sentence.

Docs that undersell. The lowest docs score among the six is a 4. Their READMEs state prerequisites and admit limitations; adjectives are scarce. It turns out the authors who test their own install instructions also write descriptions that trigger. Craftsmanship correlates with itself.

Also worth noting: pedigree helps but does not decide. Ten of the eleven Anthropic-authored skills we tested passed cleanly, and the exception is setup-by-design. But a third of the top tier is one community author who cared, and plenty of community skills outscore official ones in their category. The most-starred repository in our discovery queue has over 85,000 stars and still no verdict, because stars are not a test.

If you’re picking skills

Use tested ones. That is a self-serving sentence on a site whose entire product is testing skills, so here is the reasoning to check for yourself: the four failure modes above are invisible in a GitHub listing. Star counts measure marketing reach. A README measures the author’s optimism. The only way to know whether a skill beats baseline is to run the baseline, which takes us about an evening per skill, times 45 so far.

Start with the best skills of 2026 for the cross-category tier list, or go straight to your category, for instance the best coding skills. Every entry links its test notes, including the workarounds for skills that need them.

If you’re writing one

The failure modes double as a checklist, and three of the four are cheap to avoid.

Write the description as a trigger specification: the phrases a user would type, plus what the skill should ignore. Then test the install instructions on a machine that is not yours, or at least in a fresh directory, and declare every dependency, including other skills and MCP connections. Run our skill validator before you publish; it catches the structural problems and the billboard-description problem in seconds. For the full walkthrough, frontmatter to publishing, see how to write your own Claude skill.

The fourth failure mode, beating baseline, is the one that requires actual thought. Before writing anything, run your target task through Claude with no skill. If the output is already fine, you do not have a skill, you have a readme for a feature Claude ships with. The 9.6 tier exists because those authors found real gaps. Ironically, the best tool for the job is itself a skill: skill-creator scaffolded a working internal skill for us in one session, and its description-optimization step measurably improved triggering in our test.

The uncomfortable part

Nothing in this data says the ecosystem is bad. It says the ecosystem is unreviewed, which is a different problem with a familiar shape. Browser extensions around 2010, npm around 2016: a low barrier to publishing plus no verification layer produces a catalogue where the median item is mediocre, the best items are genuinely excellent, and no surface signal separates them. Skills that fail our install check have hundreds of stars. Two of our six top scorers come from repos most people have never heard of.

The usual correction eventually arrives, some mix of review layers and reputation. Until it does, the burden sits on whoever installs, and the numbers above are what the burden looks like: 22% of tested skills broken as shipped, 69% with imperfect triggers, 89% with documentation that lost points. We will keep publishing the data either way. The full protocol and scoring rubric are on the methodology page, and every figure in this article is reproducible from the per-skill test notes.

FAQ

Why is my Claude skill not triggering?

Check three things in order. First, the path: SKILL.md must sit at ~/.claude/skills/<name>/SKILL.md, not one directory deeper; a mis-nested skill fails silently. Second, the frontmatter description: if it reads like a slogan, Claude has nothing to match your prompt against. Rewrite it to name the exact phrases you actually type, or run it through the skill validator. Third, prompt with words from the description verbatim; if that fires, the description’s coverage is your problem.

How do you decide a skill “works”?

Clean install on a fresh setup following the author’s own instructions, trigger checks in both directions (fires on claimed prompts, stays quiet on unrelated ones), and a real task scored against a no-skill baseline, worth 10 of 25 points. Verdicts: pass, works-with-setup, or still-in-queue. The methodology page has the rubric; each skill page has the notes.

Are official Anthropic skills more reliable than community ones?

More reliable on average: 10 of the 11 we tested passed cleanly, and the exception (brand-guidelines) requires configuration on purpose. But average is not the interesting number. Two of our six top-scored skills come from one community author’s repo, and humanizer, a community skill, is one of only two skills to score 10/10 on output. Test results beat provenance.

Do these results mean I should avoid Claude skills?

The opposite. The tested tier is quietly excellent: 19 of 45 skills scored 9 or better on output vs. baseline, and the top six are the difference between Claude as a chat window and Claude as a tool that produces finished work. The finding is narrower than “skills don’t work.” It is that half of what is published has a defect you cannot see from the listing, so install from test data, not from stars.