An agent skill is a folder with a markdown file in it, telling a coding agent how to do some recurring job. Teams now write them the way they used to write runbooks. Researchers collected 138,000 of these files from public repositories and checked each one against the format's own published rules.

Nine in ten had something wrong. The authors are careful to say that number lumps a repeated heading in with a leaked API key, so it shouldn't be read as nine in ten skills being broken. The shape of the problems matters more than the count. Almost all of them are ordinary packaging faults. The single most common defect, in more than half the files, was a skill that never says when it should be used. It describes what it does and stops there.

That's the one thing the file can't afford to leave out, because the description is the main basis on which an agent decides whether to load the skill at all. A skill that skips it sits in the repository looking perfectly sensible and simply doesn't get picked.

"The most direct reuse failure is that an otherwise useful skill is never selected."

This is a failure with no symptom. A broken skill that runs produces bad output someone notices. A skill that never gets selected produces nothing: no error, no log line, no complaint. The library keeps growing and nobody can say which half of it is doing any work. Any team with an internal skill library should be able to answer one question: which skills actually got loaded last week? Most can't, because nothing anywhere is recording it.

The second finding cuts against the instinct to fix this by writing more. Problems pile up steeply with length, and the shortest skills were the cleanest by a wide margin. Among the complaints filed against real agent platforms was one installed set that added over four minutes to every cold start before the agent had done anything. And when the researchers examined the small group of clean, widely used skills to see what they had in common, the one trait that wasn't circular was that each encoded something local: this repository's conventions, this service's deployment steps. A skill explaining how to write a good unit test is one your agent will dutifully load and learn nothing from.

"A reusable skill is not merely a saved prompt; it is a routed, progressively disclosed, executable capability."

Their explanation for all this, offered as a hunch rather than a result, is that most public skills are chat transcripts saved to disk. Someone solved a problem interactively, thought that was useful, and committed it. The same caution applies to the associations they report: files stamped as AI-generated carried roughly twice the rate of safety problems, but authors who bother to stamp a file that way aren't a random sample of anyone.

Where this lands for a working team is how to spend review attention. Their automated repair pass fixed more than half the ordinary structural problems and none of the security ones. Not a poor rate: zero. That's a decent argument for letting a linter own formatting and keeping human eyes for anything touching credentials or destructive commands.

"Defect-free status is not the goal."

Sources

1. Zhang, C., Liu, Y., Chen, X. et al., "What Keeps Agent Skills from Being Reusable? Evidence from 138K SKILL.md Files" — https://arxiv.org/abs/2608.08453