Your AI agents should not all carry the same skills

Our team runs several AI agents, each with a different job. One is a coordinator that handles documents and handoffs, one is a product manager, one is a designer, another reads markets through numbers. Whenever we find a good skill pack we want the team to have, the first question is basic: which agents should get it?

The instinctive answer is "install everything for everyone and be done with it." We almost did. The next six hours of assigning skills agent by agent taught us three lessons instead, each backed by real logs, and each pointing at the same principle.

Part 1Installing everything makes no agent better

We started with the team's product manager agent. Its job spans discovery through go-to-market, so we enabled the whole product-management skill family for it, seven plugins in one go. Then we probed it: which skills can you see?

The list came back with 168 skills.

That sounds like being well equipped. What we had actually created was a permanent tax. Every time an agent wakes up to work, the names and descriptions of every skill it can see are loaded into its context first. See 168 skills, pay for that context on every single run, even though an OKR-planning task never once needs an image-generation skill. And more options do not make selection sharper. They raise the odds of grabbing something close-but-wrong.

That was the point where we stopped and reset the principle. An agent's capability is not measured by how many skills it can see. It is measured by how often it picks the right one at the right moment. A small accurate kit beats a big noisy one.

Part 2Curate by role: read the content, not the name

A skill name is a headline, not a contract

Once we switched to curating suites by role, we hit the second miss immediately. While assembling the design suite for our designer agent, we found a skill called demo-builder. The name fit perfectly, designers build demos. In it went.

Hours later we finally opened the skill file and read it. The content is about seed data and mock logins for setting up dev environments. Nothing to do with design at all. Another one in the pile, brand-guidelines, sounds like a generic brand-system tool. Its content is one specific company's brand, unusable for our work. Both got pulled from the suite.

A skill name works like a headline. It is written to be memorable and clickable. The content is the actual contract for what it does. We wrote about the same failure shape from another angle, agents reporting their own work (Why AI agents lie), and the rule turns out to be identical for skills: the label is not the substance. Open and read before you install.

Three layers must hold before a skill actually reaches an agent

Another thing the afternoon taught us: "installed" does not mean "usable." For a skill to actually reach an agent, three layers have to line up, and when any one of them is missing the system just goes quiet. No error anywhere.

The painful property of these layers is that they fail silently. None of them alerts you. We hit this ourselves with a skill that showed up in the probe list but stayed dead when called from the chat room. It took a while to trace it to the third layer. Since then, every skill handout ends with checking all three layers before telling anyone it's done.

No matching skill? Leave the slot empty

While finishing suites for the whole team, three agents had no genuinely matching skill anywhere across our marketplaces. The urge to give "everyone something" nearly made us force near-matches in. We left them empty instead. An empty suite beats a self-deceiving one, because a nearly-right skill gets picked for the wrong job and produces nearly-right output, which is worse than nothing and harder to catch.

Part 3Guessed names and shifting versions: why you need a lint

The third miss: a hand-written list always drifts from reality

The last miss hurt the most because it happened twice in a row. Assigning the finance suite to our analyst agent, we typed skill names into its list from memory plus an old folder on a laptop. The guessed names did not exist on the server. The real ones were spelled differently. We fixed that, and still weren't done: when we pinned the skill pack to a specific version for supply-chain safety, the set of names inside changed again. The probe from the afternoon said a name existed. By evening, the files on disk said it didn't.

So a hand-written list and installed reality drift apart through two independent doors: humans guessing names, and versions moving underneath you. Both are silent. Nothing visibly breaks. You just have an agent that can't invoke a skill at the moment it matters.

Let a machine do the comparing, not human memory

The fix is not trying harder. It is removing "trying" from the loop. We wrote one short lint with a single job: walk every declared skill name for every agent, compare it against the skill files actually installed on disk, and complain immediately with the agent's name when a declared skill has no real file behind it.

Before trusting the checker, we did one more step we'd recommend to everyone. Plant one fake name and watch it get caught. A checker that has never caught a known-bad in front of you has a meaningless "pass". Once it flagged the fake correctly, we removed the plant and started believing its results.

The unplanned bonus: setting up the lint forced us to look around it, and we discovered that our skill-sync script had never once completed on Linux, because it used a Mac-only command inside. It had been dying quietly, halfway, for weeks. Human attention does not find that class of bug. Tools that force a comparison against reality do.

The list a human wrote is not the truth. What sits on disk is. The job is to make a machine compare the two for you, every time, not some of the time.

Part 4Start with your own team

If you run more than one agent, on Claude Code or anywhere else, walk through this. It takes under an hour for a small team.

1. Write each agent's role first. One line per agent: what it does, what it does not. If you can't write the line, you're not ready to assign it skills.
2. Inventory your skills and read every one. Reading just the skill's description file takes minutes per skill. The name is a headline; the content is the contract.
3. Curate small: 3-5 skills per agent, matched to its most frequent real work. Any agent with no genuine match keeps an empty slot. No force-fitting.
4. Write a list-versus-disk checker, positive-control it with a fake name before trusting it, and run it after every list edit or version update.
5. If a suite grows past 10 skills, add a short playbook inside the agent's main skill saying which tool fits which stage, so the agent doesn't guess.

A light bag you always pick correctly from carries a team further than a bag with everything in it and nothing findable. Go pack your team's bags.