I audited 25,693 public Claude Skills. 37% never say when to use them.

How I collected the corpus

I did not want a hand-picked list, because hand-picked lists are how you end up describing the ten skills someone already liked. I wanted the population.

Using the GitHub API I searched five ways — the topics claude-skills, claude-skill and agent-skills, plus repository name and description matches, plus repositories whose README mentions SKILL.md — and collected 4,313 repositories. For each one I fetched the full file tree and recorded every path ending in SKILL.md. That produced 203,973 skill files across 3,703 repositories.

Downloading all of them would have been both slow and dishonest. The distribution is brutally skewed: the median repository holds 2 skill files, while the largest single repository holds 23,793. Four mega-dumps alone would have supplied a third of the corpus and the whole study would really have been a study of those four repositories.

So I capped the sample at 20 files per repository, chosen at random inside each repo with a fixed seed, which yields 25,693 files from all 3,703 repositories — 12.6% of the population, with every repository represented and none able to dominate. Twelve files failed to download. That is the corpus behind every number below.

37.5% of descriptions never say when to use the skill

The specification is explicit about what a description is for. It "should describe both what the skill does and when to use it" and "should include specific keywords that help agents identify relevant tasks". Anthropic's own engineering write-up puts it plainly: pay special attention to the name and description, because "Claude will use these when deciding whether to trigger the skill".

I tested every description for any language that states a condition — use when, when the user, whenever, invoke when, apply when, trigger, and a dozen more patterns. Generous by design: a single match counts as a pass.

9,647 of 25,693 descriptions — 37.5% — contain no such cue at all. They describe a capability and stop. Here are real ones, quoted verbatim from the corpus, from repositories with tens of thousands of stars:

• "Control Eight Sleep pods (status, temperature, alarms, schedules)."
• "Drive and script tldraw offline canvases with an agent."
• "Debug Python with pdb, breakpoint(), post-mortem inspection, and debugpy remote attach."
• "Launch the interactive web dashboard to visualize a codebase's knowledge graph"
• "Replace with description of the skill and when Claude should use it."

The last one is not a joke. It is the untouched placeholder from a template, sitting in a repository with 169,662 stars, published as a skill. Nobody filled it in, and nothing in the tooling complains — because none of this is enforced.

The others are worse in a subtler way, because they look fine. "Debug Python with pdb" is accurate, specific, and useless at selection time: it names a tool, not a moment. Compare it with a description from the same corpus that does the job — "Use when about to claim work is complete, fixed, or passing, before committing or creating PRs". That one tells the model exactly which instant in a conversation it belongs to.

There is a measurable tell. Descriptions with a trigger cue run to a median of 343 characters; those without run to 161. The failure is not subtlety. It is that people stopped writing after the first clause — they wrote a label, not an instruction. And the limit is nowhere near binding: the spec allows 1,024 characters, Claude Code truncates the listing at 1,536, and the median description in the wild is 265. There is roughly four times more room than anyone is using.

Stars tell you nothing about whether a skill is valid

This is the finding I did not expect, and it is the one with the most practical consequence, because stars are how everyone picks.

I split the corpus into four popularity bands and measured two things in each: the share failing a hard requirement of the spec, and the share whose description gives the model nothing to trigger on.

The bands are flat, and the most popular band is the worst on spec compliance. Across the whole corpus the correlation between a repository's star count and its skill being valid is r = −0.0226; between stars and having a trigger cue, r = −0.0358. Both are indistinguishable from no relationship at all.

This is not mysterious once you see the mechanism. Stars measure whether people liked the idea of a repository — usually a curated list, a demo, or a name that spread. Nobody stars a repository after checking that its frontmatter validates. Large repositories also tend to be collections, assembled fast and in bulk, which is exactly the condition under which template placeholders survive.

The practical version: a skill from a 40,000-star repository is, if anything, slightly more likely to be broken than one from a repository with nine stars. Popularity is a signal about the packaging. It carries no information about the file you are about to install.

17.8% fail the specification outright

The Agent Skills spec is short and testable. name is required: 1–64 characters, lowercase letters, digits and hyphens only, no leading or trailing hyphen, no consecutive hyphens, and it must match the parent directory name. description is required: 1–1,024 characters, non-empty. Everything else is optional. A reference validator, skills-ref validate, checks exactly this.

Run those rules across the corpus:

The directory-name rule accounts for most of it, and it is the one people find pedantic until it bites: rename a folder, forget the frontmatter, and the skill quietly stops resolving the way you expect. Set that rule aside entirely and 9.0% still fail — 2,306 files that are missing a required field, have no readable frontmatter, or carry a malformed name.

Then there is the frontmatter itself. The spec defines exactly six fields: name, description, license, compatibility, metadata, allowed-tools. 31.4% of files use at least one field outside that set. Claude Code accepts a number of its own extensions, so many of those are harmless there — but 15.6% use a field that Claude Code rejects too, producing the error "Unexpected key(s) in SKILL.md frontmatter" on the distribution paths that validate strictly, such as claude.ai uploads and the Skills API.

The most common inventions are revealing: version (2,917 files), argument-hint (1,736), tags (1,012), author (988), category (623), triggers (531). People are reaching for a package manifest. The format is not one. A triggers: field in particular is wishful thinking — nothing reads it, and the 531 authors who wrote one had the right instinct and put it in a place where no model will ever look. That instinct belongs in the description.

A quarter of the ecosystem is the same skills, over and over

Names repeat heavily. 27.2% of files carry a name that at least one other file in the corpus also uses. The leaders read like a census of what people believe an agent should do first:

skill-creator 81 · pdf 53 · code-review 46 · frontend-design 42 · docx 36 · xlsx 35 · pptx 32 · handoff 30 · setup 27 · mcp-builder 27

Look closely at that list. pdf, docx, xlsx, pptx, skill-creator, mcp-builder, canvas-design, frontend-design, brand-guidelines, webapp-testing — these are Anthropic's own first-party skills, the ones that ship in the box. 377 files in the corpus, 1.5%, are re-publications of a skill the user already has.

Bodies duplicate less than names: 95.2% of skill bodies are unique after whitespace normalisation, and 8.3% are byte-identical copies of another file, with the most-copied body appearing 21 times. Descriptions duplicate more — 13.1% are word-for-word identical to another skill's description, which is how you end up with two skills competing for the same trigger and neither winning cleanly.

So the ecosystem is not mostly plagiarism. It is mostly parallel invention: thousands of people writing their own code-review skill, independently, at the same time. Which is fine, except that it means the marketplace signal you are shopping in is dominated by the most obvious ideas, not the most useful ones.

Size: most skills are small, and the big ones are the problem

Both the spec and the Claude Code documentation give the same guidance: keep SKILL.md under 500 lines, keep the body under roughly 5,000 tokens, and move detail into referenced files that load only when needed.

The median skill is comfortable: 151 lines, 6,542 characters, 13 headings. The distribution:

under 50 lines 14.2% · 50–149 35.3% · 150–499 43.3% · 500 or more 7.2%

1,825 files exceed the 500-line guidance and 2,208 carry a body over roughly 5,000 tokens; the largest is 12,191 lines and 391,575 characters. Those are not skills, they are manuals that happen to load in one shot — and every token of them enters the context the moment the skill triggers, whether the task needed it or not.

At the other end, 3.4% have a body under 200 characters: a frontmatter block and a stub. And 963 files have no frontmatter fields at all. The median file carries just 3 frontmatter fields.

The healthy shape is unglamorous: a real description, 150 to 300 lines of instruction, and the reference material pushed into references/ where it costs nothing until it is needed. Most of the corpus is already there. The tail in both directions is where the damage sits.

The market is ten months old, and it is still accelerating

Repository creation dates put a hard edge on when this started. Before September 2025 the counts are noise — a handful of repositories a month, most of them unrelated projects that later added a skill. Then:

Oct 2025 106 · Nov 98 · Dec 119 · Jan 2026 339 · Feb 386 · Mar 561 · Apr 529 · May 433 · Jun 403 · Jul 308

October 2025 is when Anthropic shipped Agent Skills. Within five months the ecosystem was creating more than 500 new repositories a month, and it has stayed in the hundreds since.

It is also alive rather than abandoned, which surprised me given how much of it is broken. 55.8% of the files in the corpus were last pushed in August 2026 — the month I collected them — and 71.9% within the last two months. This is not a graveyard of weekend experiments. It is an active ecosystem that has simply never been checked against its own specification.

Write a description that actually triggers

Everything above reduces to one repair, and it takes about ninety seconds per skill.

A description has two jobs, and most people do only the first. Job one: what this does. Job two: the moment it applies — stated in the words a user would actually type, not in the words you would use to categorise your own work.

Four rules that follow directly from the data:

1. Put a "use when" clause in every description. 37.5% of the corpus does not, and that alone separates a skill that runs from one that sits there.
2. Write the trigger in the user's words, not yours. The model matches against what someone typed. "Debug Python with pdb" describes the tool; "use when a test fails and the traceback is not enough" describes the moment.
3. Use the room you have. The median description is 265 characters against a 1,024 limit. Three or four concrete trigger phrases cost you nothing and are the whole game.
4. Then validate. Run skills-ref validate, or paste the file into the checker below. Nine percent of public skills fail a rule that takes one second to test.

How to judge someone else's skill in sixty seconds

If you are installing rather than writing, the corpus suggests a short checklist. It is deliberately not "check the stars", because stars carry no signal here.

None of this measures whether the instructions inside are any good. That still takes reading. But it removes the files that were never going to run, and on this evidence that is somewhere between a fifth and a third of what is on offer.