Common Pitfalls of Skills Development (And How to Fix Them)

I recently gave a version of this talk at AI Engineer Europe in London. What follows is the fuller story — what we found when we looked at thousands of skills, what goes wrong, and how to fix it. You know that scene in The Matrix? Neo gets a spike in the back of his head, they upload kung fu directly into his brain, and he just... knows it. That's what a skill is for an AI coding agent. You write a markdown file — a SKILL.md — and the agent loads it when the task matches. Suddenly it knows your team's deployment process, or how your API handles pagination, or that you never use semicolons. It's not code. It's context. Procedural knowledge, injected at the right moment. The thing is — Neo's upload worked perfectly. Ours? Not always. Skills are everywhere now We spent some time analysing essentially all of public GitHub. In November last year, 12 repos had SKILL.md files. By March — five thousand four hundred and sixty. That's 450x growth in fourteen weeks. Skills went from zero to 27% of all agent config activity in three months. Faster adoption than CLAUDE.md , AGENTS.md , or any of the dotfile formats before them. And 1 in 12 merged PRs on GitHub now touches an agent config file — 8.4%, up from basically zero eighteen months ago. This is not a niche thing anymore. This is how people are working. Watch on YouTube But are they electrifying? Ninety percent of agent config files are never updated after creation. Write once, forget forever. Your codebase evolves every day. Your dependencies change. Your API contracts shift. But the instructions you gave your agent? Frozen in time. For Gemini files it's even worse — 97% are write-once. And the purpose-built "skill-as-product" repos? Over half are under 50 kilobytes. Wrapper repos. Many are AI-generated. High churn, low staying power. We have this explosion of skills, and most of them are going stale the moment they're committed. What we did about it The DevRel team at Tessl spent a couple of months doing something pretty