When routing becomes a problem

Here's the curve I keep seeing. You install your first skill — say agentic-workflow — and life is great. It fires on the right tasks, the model behaves. You install three more. Still fine. Around skill seven or eight, things get weird. Claude starts ignoring a skill that obviously applies. Or worse, it picks the wrong one and confidently runs the wrong playbook for ten minutes before you notice.

The first time this happened to me, I had a code-review skill and a security-review skill installed together. I asked Claude to "look at this PR." It picked the security skill. The PR was a CSS change. I got 600 words on XSS hardening for a stylesheet.

That's a routing problem, and it's where most builders of personal AI stacks discover they need a strategy. The fix is mostly mechanical: once you understand how routing decisions get made, you can write skills that route themselves.

How a skill router actually decides

There's no central traffic-cop process inside Claude making routing calls. What actually happens is simpler and stranger: every installed skill exposes a short description (usually the first paragraph of SKILL.md plus the front-matter description field). At the start of a turn, those descriptions get fed into the model along with the user's request, and the model picks which skill — if any — applies. Same decision process as picking a tool to call.

This means three things, and once you internalise them everything else clicks:

1. Routing is description-driven. The model never reads the body of your skill until it's been picked. A vague description means your skill won't get picked even if it's perfect for the job.
2. Routing is request-shape-driven. The model is matching the shape of the user's ask against the descriptions. "Review this PR" matches a description containing "code review for pull requests." It does not match "perform comprehensive software quality assurance evaluation."
3. Routing is competitive. Two skills with overlapping descriptions will fight, and the winner is whichever description sounds more confident, more specific, or just appears earlier in the list. Yes, ordering matters more than it should.

For a longer take on the underlying execution model, the prompts-to-skills migration guide covers the foundations. Smart routing sits on top of that.

What routing conflicts look like in the wild

Three patterns, in order of how often I run into them:

Pattern 1: Both skills fire

You ask Claude something ambiguous. Two skills both think they own it. The model either picks one and ignores the other (sometimes the wrong one) or, worse, partially applies both and produces a Frankenstein response. The CSS-as-XSS story above is this pattern. It's the most common conflict and the easiest to spot — the response feels off in a specific way, like Claude's answering a question you didn't quite ask.

Pattern 2: Neither skill fires

You ask something that should obviously trigger a skill. Nothing fires. Claude responds in plain-vanilla mode, which is usually worse than whatever the skill would have produced. This happens when descriptions are too narrow — the skill technically applies but the request doesn't use the magic words. "Add a test for this function" might miss a skill described as "generates pytest unit tests for Python repositories" if your file is .py but you didn't say "pytest."

Pattern 3: The wrong skill fires confidently

The most expensive failure mode. Two adjacent skills, one wins for the wrong reason — usually because its description is more general — and runs an entire playbook before you notice. I once had a generic "writing-assistant" skill steamroll a "release-notes-from-commits" skill on a "draft this week's release notes" request. The writing-assistant produced a fine paragraph of marketing copy. The actual release-notes skill would have read the git log and produced something useful.

If you're working incidents in a team setting, where multiple operators invoke skills against shared infrastructure, this gets dangerous fast. The war-room post on AI skills during live incidents covers the team failure modes — the routing principles are the same as solo, just with higher stakes.

Writing skill descriptions that route correctly

This is the part that pays off forever. A good description is roughly two sentences and answers three questions: what kind of request triggers this skill, what kinds of requests should be sent elsewhere, and what's the output shape. Skip any of those and routing gets sloppy.

Bad description (real, anonymised)

description: |
  A comprehensive skill for software engineering tasks including
  code analysis, debugging, refactoring, optimization, and quality
  improvements. Useful for any code-related work.

Why it routes badly: it claims everything. "Any code-related work" overlaps with five other skills. The model has no signal for when not to pick this one. Result: it wins routing battles it shouldn't and loses ones it should win, depending on which adjacent skill happens to be more aggressive that turn. Generic descriptions feel safe to write. They're poison for routing.

Better description for the same skill

description: |
  Refactors a single function or class for readability — extracts
  helpers, renames vague variables, simplifies branching. Use when
  the user says "clean up", "refactor", or "make this readable".
  NOT for performance work, NOT for cross-file changes — those have
  their own skills. Output: unified diff plus a one-line summary.

What changed: the trigger surface is concrete ("clean up", "refactor", "make this readable"), the boundaries are explicit (NOT performance, NOT cross-file), and the output shape is named. The model now has the information it needs to pick correctly and to not pick when something's outside scope. Notice the explicit "NOT" clauses — they look defensive but they save you from Pattern 1 conflicts above. Worth their weight.

Another good example, different domain

description: |
  Summarises a project's recent commits into release notes for
  end users (not engineers). Triggers on "draft release notes",
  "what's new", or "changelog for v*". Reads git log + linked
  PRs. Skips internal refactors. Output: Markdown grouped by
  Features / Fixes / Breaking changes.

Same recipe: triggers, boundary ("not engineers" separates this from a dev-changelog skill), and output shape. If you liked the picks in the best Claude Code skills for solo devs piece, this is the description style most of those skills already use. They route well because they're written this way.

The three-question test

Before publishing a skill, read its description and answer three questions:

• What's the shortest possible request that should trigger this? (If you can't think of one, the description is too abstract.)
• What's a request that looks similar but should NOT trigger this? (If your description doesn't rule that one out, you'll get Pattern 1 conflicts.)
• What's the output? (If the description doesn't say, you're trusting the model to guess. It will guess differently each time.)

Two minutes per skill. Saves hours of wrong-skill debugging downstream.

The three skills that make smart routing work

Once you've cleaned up your descriptions, smart routing is mostly automatic. But there are three skills that turn it from "automatic" into "compounding," and you want all three installed before your library hits double digits.

1. skill-router — the meta-skill that closes the loop

What it does: sits above your other skills and explicitly chooses which one applies to a given request, with a one-line justification. Effectively a router-as-a-skill.

Why builders need it: good descriptions get you 80% of the way. The router gets you the last 20%, especially in the messy middle where two skills look equally relevant. It also gives you observability — every routing decision comes with a reason, so when the wrong skill fires you can see why and fix the description.

The first time I installed it, three of my own skill descriptions immediately looked broken. Not because the skills were bad — because the router was now showing me, in plain English, why it kept picking the wrong one. That feedback loop is the point.

Install skill-router →

2. agentic-workflow — what runs after routing

What it does: once a specialist skill has been picked, agentic-workflow handles the loop — plan, checkpoint, execute, summarise. It's the skeleton most other skills slot into.

Why builders need it: routing without execution discipline gets you to the right starting line and then runs in random directions. agentic-workflow makes the post-routing behaviour predictable.

Install agentic-workflow →

3. persistent-kb — context the router can lean on

What it does: project-scoped knowledge base Claude reads at session start. Architectural decisions, conventions, the reason you pin certain dependency versions.

Why builders need it: a lot of routing failures aren't really routing failures — they're context failures. The router picks a skill that would be right for a fresh project but is wrong for yours, because it doesn't know your project rejected that pattern three months ago. persistent-kb fills that gap. Pair it with skill-router and your routing decisions get noticeably sharper because the router is choosing in context.

Install persistent-kb →

Honest limitations

Smart routing is great. It's not magic. Three things to be clear-eyed about:

• Routing can't save bad skills. If the skill you'd ideally route to is poorly written, picking it correctly just gets you a bad answer faster. Routing quality is downstream of skill quality.
• Cold-start routing is worse than warm-start. Early in a session, before persistent-kb has loaded any project context, the router has less to go on. Expect the first one or two requests of a session to route slightly worse. Reload context if it matters.
• Big libraries hit a ceiling. Past roughly 30 installed skills, even a router struggles — descriptions start drowning each other. At that point you want skill folders (project-scoped subsets) rather than one giant pile. The router supports this, but you have to opt in.

None of those are reasons to skip smart routing. They're reasons to set it up early, while your library is still small enough to refactor cheaply.

FAQ

Do I need an AI skill router if I only have three or four skills?

Probably not yet. Smart routing earns its keep around skill #8–10. Below that, manual invocation is fine and the router adds overhead you don't need. Install it the moment you forget which skill to invoke for which task — that's the signal.

Does the router slow Claude down?

A little. Adds maybe 200–500 tokens to the first turn of a session, plus a small latency hit for the routing decision itself. In practice you don't notice — the time saved by Claude picking the right specialist on turn one dwarfs the routing overhead.

Can I override the router and force a specific skill?

Yes. Most router implementations honour an explicit "use skill X" instruction in the prompt and skip the routing decision. Useful when you know better than the router does — for example when you've just written a new skill and want to test it on requests that wouldn't normally trigger it.

What if two of my skills genuinely overlap?

Then merge them or split them. Two overlapping skills is a code smell — usually they should be one skill with branching, or one skill that's a strict subset of the other and gets removed. The three-question test in this post is what surfaces overlaps fastest.

Is there a way to debug routing decisions?

The skill-router skill emits a reason for each decision. Read those reasons for a week and patterns emerge — usually one or two descriptions doing most of the wrong-routing damage. Fix those and your hit rate goes up sharply.

Can I share routing setups across teams?

Yes. The router config is a few extra lines in each skill's front-matter. Check those into your repo alongside the skills and your team gets identical routing behaviour. This matters more in incident response than greenfield work — see the war-rooms post linked above.

The bottom line

Smart routing is what turns a pile of skills into a system. Without it, every additional skill you install raises the cognitive cost of remembering when to use what. With it, every additional skill is pure upside. Install skill-router first, then spend twenty minutes rewriting the descriptions of the three skills you use most. Run a real task through the new setup. The improvement is the kind you feel immediately, not the kind you measure in dashboards.

→ Browse all skills · Request a skill