How to Add Agent Skills Without Breaking Old Ones

Adding a new skill to your agent can quietly break the ones you already have. Routing starts sending queries to the wrong skill, even when nothing about the old skills or the router changed. A paper called Skill++ has a fix that is smaller than you would expect: rewrite two lines of metadata and leave everything else alone.

Across 731 skills and ten sessions, the router picked every required skill for 76.3% of queries, up from 36.4% with the original metadata. Substitution errors nearly disappeared and crowding errors fell by half.

What You Need

• An agent with at least one skill already in its library, so the new skill has a closest neighbor to compare against.

Tutorial

1. Rewrite only the name and description of each skill you add. Skill++ leaves everything else alone, with no router training and no labeled data.
2. State in the new description what the skill supports and what it excludes. Routers pick skills by name and description, so those fields are where the difference has to show.
3. Say how it differs from the closest skill you already have. When a new skill's metadata looks like an older one's, it can replace or crowd that skill out.

Wrapping Up

That is the whole method: same skill, same router, a description that says what it covers, what it drops, and which neighbor it sits beside. The gains held across three benchmarks and five routers, and they carried over to the Codex CLI harness.

Next time you add a skill, write that description before you go hunting for a bug in your agent.