{"slug": "36-of-public-ai-agent-skills-are-broken-heres-how-to-build-one-that-isnt", "title": "36% of Public AI Agent Skills Are Broken. Here’s How to Build One That Isn’t.", "summary": "A new analysis finds that 36% of public AI agent skills are broken, according to a report from agentskills.io. The report outlines five best practices for building reliable skills, emphasizing that descriptions must clearly state both what a skill does and when to use it, and that content should come from specific, hands-on experience rather than generic LLM-generated text.", "body_md": "Agent skills are the simplest way to make an AI agent better at a specific job. And because they’re so simple, they’re also really easy to get wrong. The mistakes rarely look like mistakes, either — a skill that never triggers, one that quietly runs code it shouldn’t, or one that works perfectly and still hands you the wrong answer. The simplicity is the trap: it hides just how many small decisions actually matter. So let’s cover five best practices for building them.\n\nA skill is procedural knowledge handed to an AI agent. The model already knows plenty of facts, but what it doesn’t know is your particular way of doing a particular job — and a skill teaches it exactly that.\n\nThe format is almost comically simple. It’s basically just a SKILL.md file — markdown in a folder. But here's the part worth worrying about: an agent skill hands a probabilistic model a folder of text and trusts it to run a fragile, multi-step job. A skill can also contain and run code, so sourcing one off the internet means running a random person's software on your machine. And while there is an open agent skills standard defined at agentskills.io, here are some considerations when creating them.\n\nWith that context in place, let’s get started with the first best practice.\n\nThe description is one of the strongest signals that determines whether an agent considers a skill relevant. Every SKILL.md file opens with a bit of YAML, and in there we define a name and a description. Both are on the short side: according to agentskills.io, a name can be a maximum of 64 characters, and a description — which describes what the skill actually does — is limited to 1,024 characters.\n\n```\n---name: monthly-compliance-reportdescription: Generates the monthly compliance report from internal data. Use when someone asks for the compliance report or the monthly filing.---\n```\n\nThis tiny header is the entire contract the agent sees at startup, which is exactly why the wording of the description carries so much weight.\n\nSay you have 100 of these skills installed. The agent can’t read all of them at once without filling up its context window, so at startup it just loads the name and the description of each skill. Here’s where the best practice comes in: the name and the description need to contain enough information by themselves for the agent to know when to use it. A compliance skill that “generates reports” might be just a little too vague. The fix is to say both what the skill does and when the agent should make use of it.\n\nA good version reads: *“Generates the monthly compliance report from internal data, used when someone asks for the compliance report or the monthly filing.”* It says what the skill does, and it says when the skill should do it.\n\nThe description should also lean a bit on the pushy side. Models tend to under-trigger — they might skip a skill they should have used — so it’s safer to oversell the description a touch rather than undersell it. Think LinkedIn posts. So that’s getting a skill to trigger. What goes inside it once it does?\n\nOnce a skill triggers, the body is entirely yours to fill — and this is where a lot of skills go sideways, because the temptation is to just have the LLM write the skill for you.\n\nThe first skills many people create are all like this. You say, “Hey, AI agent, write me a skill that does X,” and it generates stuff you only glance at before calling the skill a complete success. What you get out of that is very generic mush: *handle errors appropriately, validate inputs* — stuff the model already knew.\n\nThe whole point of a skill is your specific way of doing a specific job, so the content has to come from somewhere the model can’t get to on its own. There are two ways to do that. One, you walk through the task by hand once and write down what actually worked, including the corrections you made along the way. Or two, you synthesize it from artifacts you already have — things like old reports, runbooks, review comments, and PR feedback.\n\nSimon Willison has a line about this. He says: keep the domain expertise and let the agent do the routine part. He’s absolutely right. You bring the expertise; the model brings the typing.\n\nSo what does this mean for the SKILL.md body? The highest-value section you can put in it is gotchas — environment-specific facts that defy reasonable assumptions. Every time you correct the agent by hand, that correction is a gotcha. Write it down; otherwise, you'll be making the same correction next week, and the week after.\n\nEven when you do all this right, it doesn’t always work the first time around. Consider a skill built for a monthly compliance report from an actual, real report — real expertise, exactly what we’re talking about. But on the first run, the row totals didn’t add up to the column totals. The math was wrong on a compliance report. That’s the good kind of wrong, though, because it’s the kind you can catch. We’ll come back to this one.\n\nThe point is, a good skill body gets thorough. And thorough means it can get really, really long. As it turns out, long gets expensive.\n\nThat expense is the reason the third best practice exists. At startup, the agent only sees the name and the description, but when it selects a skill, that’s when it actually reads the rest. Now we bring the body of the SKILL.md file into context — and that context is shared with everything else already in the context window. Every line in the skill body is now competing for the model's attention, which means the goal is to write less.\n\nThis feels a little bit in opposition to the last best practice, because you’d think the more detailed and thorough a skill body is, the better. But the model is already smart. It knows what a PDF is. It knows what a database migration does. So only write down what the agent wouldn’t know on its own — stuff that’s not already part of the model’s training data.\n\nWe can put this into numbers. It’s recommended to keep the body of SKILL.md under about 500 lines of text, or roughly 5,000 tokens, and just keep it at that. And when it's bigger than that, split it out. The skill folder can hold a sub-folder called references, and the agent will only open the files in there when it actually needs them.\n\n```\nmonthly-compliance-report/├── SKILL.md├── references/│   └── reporting-standards.md└── scripts/    └── reconcile_totals.py\n```\n\nBy pushing the heavy detail into references/, the agent pulls it in only on demand — which is the whole point of a pattern called progressive disclosure: disclose additional information like this only when it is needed.\n\nStaying lean is one thing, but some steps you really don’t want the agent guessing at at all.\n\nGuessing is precisely the risk the fourth best practice addresses. Every time the model runs your skill, it reads the instructions and improvises through them. For loose steps, that’s fine — a lot of paths get you to the right answer. But for a step that has to be exactly right every single time, you don’t want the model regenerating the logic on the fly.\n\nThe best practice is to make use of deterministic scripts, matching how prescriptive you are to how fragile the step is. Loose step: write instructions. Fragile step: write code.\n\nThe skills folder holds a scripts directory — same idea as references. You drop a script in there, and the skill body just tells the agent to run it. The script doesn't get loaded into context, so you save tokens as well, and it's more reliable than having the model improvise from scratch every time. You do have to be explicit about intent, though, so the model doesn't just read the script as reference material. Say \"run this script\" or \"read this as reference\" — don't leave that to a guess. This works in Claude Code, but it isn't just an Anthropic thing; OpenAI's Codex works roughly the same way.\n\nBack to that compliance report, the one where the row totals didn’t reconcile. The math step is now a deterministic math script. The model doesn’t add the numbers anymore — it calls a script that adds the numbers, and that whole class of bug just goes away, because the script doesn’t guess.\n\n``` python\ndef reconcile_totals(df, tolerance=0.01):    row_total = df[\"Total\"].sum()    column_total = df[[\"Jan\", \"Feb\", \"Mar\"]].sum().sum()    if abs(row_total - column_total) > tolerance:        raise ValueError(            f\"Reconciliation failed: rows={row_total:.2f}, \"            f\"columns={column_total:.2f}\"        )    return row_total\n```\n\nBecause the totals are computed and compared explicitly in code rather than inferred by the model, this step is deterministic: it either passes the reconciliation check or raises an error. That’s exactly what we want for fragile operations — guess out of the loop.\n\nAnd note that the answer isn’t to write more tests. You can’t test your way to trust; a test only catches what you already thought to check. The answer is that, for the parts that have to be right, you guess out of the loop. This is moving away from the probabilistic behavior an agent exhibits and toward a more deterministic model instead. If something can be hard-coded as deterministic logic, do it — because if the agent has to make probabilistic decisions, those decisions won’t always be consistent across multiple runs.\n\nA skill you built yourself, that you’ve read, and whose fragile steps you’ve hardened is a skill you can trust. But not all skills you’ll run are ones you build yourself. What about the ones that came from a stranger?\n\nThat stranger’s code problem is what the final best practice is all about. As noted, a skill can run code — a stranger’s software on your machine. A skill folder can contain executable scripts, and those scripts can access things like the local file system on your computer, or, in fact, any API keys you happen to have lying around. That’s exactly what makes skills so powerful.\n\nBut[Snyk’s ToxicSkills audit], published in February 2026, scanned 3,984 public skills: 36.8% (1,467) had a security flaw of some kind, and 13.4% (534) had something critical going on — like a prompt injection or straight-up malware.\n\nWhich means we have to treat an agent skill like any other dependency, the same way we’d check a random package before pulling it into a project: read what it does and check what it reaches out to. Just because agent skills are an open standard doesn’t say anything about whether a given skill is safe.\n\nSo those are the five best practices. A good skill is one the agent will actually trigger, built with real hands-on expertise, kept lean so it doesn’t fill up the context window, backed by a deterministic script whenever a guess would be dangerous or just inconsistent, and vetted before it ever runs.\n\nAnd this is all moving fast. It’s an open standard, more agentic platforms are adopting it, and this list is going to grow — which is really us asking what we missed. If you’ve built agent skills and you’ve got a great best practice, drop it in the comments. Preferably one that isn’t malware.\n\nSnyk — “Snyk Finds Prompt Injection in 36%, 1,467 Malicious Payloads in a ToxicSkills Study of Agent Skills Supply Chain Compromise” (published February 5, 2026) 🔗 [snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/)\n\n[36% of Public AI Agent Skills Are Broken. Here’s How to Build One That Isn’t.](https://pub.towardsai.net/36-of-public-ai-agent-skills-are-broken-heres-how-to-build-one-that-isn-t-398cf48f7b99) was originally published in [Towards AI](https://pub.towardsai.net) on Medium, where people are continuing the conversation by highlighting and responding to this story.", "url": "https://wpnews.pro/news/36-of-public-ai-agent-skills-are-broken-heres-how-to-build-one-that-isnt", "canonical_source": "https://pub.towardsai.net/36-of-public-ai-agent-skills-are-broken-heres-how-to-build-one-that-isn-t-398cf48f7b99?source=rss----98111c9905da---4", "published_at": "2026-08-21 20:01:01+00:00", "updated_at": "2026-08-21 20:13:54.353843+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-research"], "entities": ["agentskills.io"], "alternates": {"html": "https://wpnews.pro/news/36-of-public-ai-agent-skills-are-broken-heres-how-to-build-one-that-isnt", "markdown": "https://wpnews.pro/news/36-of-public-ai-agent-skills-are-broken-heres-how-to-build-one-that-isnt.md", "text": "https://wpnews.pro/news/36-of-public-ai-agent-skills-are-broken-heres-how-to-build-one-that-isnt.txt", "jsonld": "https://wpnews.pro/news/36-of-public-ai-agent-skills-are-broken-heres-how-to-build-one-that-isnt.jsonld"}}