Wrangle Many Skills.
One CLI ships with one gateway skill that routes to a local model holding the full skill library. Solves the auto-discovery ceiling without bloating context. The agent stays lean, the catalog stays huge, and the router does the dispatch for you.
- A gateway skill the single skill your CLI ships with. Claude sees one front-matter description, not forty. Context stays cheap.
- A router agent and its catalog a small model holding every per-method skill description, returning the right one on query. Local by default, but anywhere it can hold the catalog also works.
- A ceiling you stop hitting install a fortieth skill in the same family and the agent still picks it accurately. The router scales with you instead of degrading.
Wire the router with Claude.
Hand the canonical pattern off to Claude in one paste. It reads the source, scopes your skill library, builds the gateway plus the router catalog, then tests dispatch end to end.
How this fits in the OS.
At least one CLI installed with a skill family that has grown past the agent's auto-discovery ceiling. If you haven't built a CLI yet, start with Build Your First CLI and come back when your skill count gets big.
A small local language model (Qwen or Gemma class via Ollama works), one new gateway skill in your CLI, and a structured catalog file the router reads. Optional: a remote host if local model RAM is tight.
One mediated entry point for an entire skill family. The agent sees one description instead of forty. Your context budget stops fighting your skill library, and the next thirty skills you install just work.
What you'll build.
By the end of this build you have a gateway skill installed in your CLI plus a router agent holding the full skill library. The gateway is what Claude sees: one front-matter block, one job description. The router is what the gateway calls: a small model that holds every per-method skill description internally and returns the matched skill on query. Claude then invokes the matched skill locally and the CLI does the work.
The pattern is the same shape as the Librarian Agent on the read side: a single mediator that holds a catalog so the main agent doesn't have to.
Why a thirty-skill CLI breaks auto-discovery.
Every Claude skill ships with a front-matter description. That description is how the agent decides when to use the skill. To make that decision, Claude has to hold every description in scope at decision time. There's an upper limit on how many it can hold and compare against, and you hit it sooner than you expect once you start shipping CLIs with full skill catalogs.
The team hit this with a single CLI shipping 30 to 40 per-method skills. New skills got installed correctly, but the agent stopped picking them reliably. Not a load problem. A selection problem. You can have the skill installed and still have Claude fail to invoke it.
The naive fix is to bump the auto-discovery budget in your Claude Code settings. That buys you headroom but not a ceiling fix. Past a certain count, you stop trusting the agent's selection accuracy whether the description fits in the window or not. That's where this card picks up.
What changes for you.
The install is mechanical. The shift in how you think about your skill library is the real thing. Three shifts you'll feel:
- Your context stays lean even with forty skills installed. You stop budgeting context against skill count. Adding a thirty-first per-method skill costs zero front-matter. The gateway description is the only one Claude scans.
- You stop hand-prompting "you have a skill for this, go find it." That's the workaround you reach for once auto-discovery starts missing. With the router, the dispatch is the agent's default path, not a thing you have to remember to prompt for.
- You start designing CLIs as a gateway plus a catalog. Every new CLI you build ships with one gateway skill instead of N per-method skills. The per-method skills still exist as the things the router routes to. They just stop being individually exposed to the main agent.
Before you start.
- You already built or installed a CLI and wrote per-method skills on top of it. If you haven't, run Build Your First CLI first. If you borrowed one, see Borrow a Working CLI.
- Your skill library is past about fifteen skills in a single family and you're feeling the selection accuracy slip. If you're still at five or six, this is premature. The abstraction costs more than it saves until the ceiling actually bites.
- You can run a small local model (Qwen or Gemma class via Ollama is the default). If your computer can't spare the RAM, the router can run on a remote host instead. Pick this up at Step 04.
- Claude Code installed on your computer with the workshop repo (
agent-native-os) cloned locally.
The build.
Inventory the skill family you're routing
~15 minPick one CLI's skill family. Not all of your skills, just the family that's past the ceiling. The Slack CLI's 30+ skills, the n8n CLI's 40 skills, whichever one you've actually grown past.
List every skill installed under ~/.claude/skills/ that belongs to one CLI family (I'll tell you which). For each skill, pull the name, the one-line description from the front matter, and the trigger phrases. Output as a table so I can confirm we're routing the right family. Stop when you have the list. Don't write anything yet.
The agent does this for you. You don't hand-list the skills. Claude reads the skill directory, parses the front matter, and gives you a clean inventory. You confirm the family size is past the ceiling threshold before you build the router.
Draft the gateway skill
~30 minThe gateway is one skill with one job: take a natural language intent ("post a message in #ops"), ask the router which per-method skill matches, and invoke the result. The front-matter description has to be broad enough to catch every intent the family handles, specific enough that Claude knows to route through it.
Example description shape: "Use this skill for any Slack operation, including posting messages, searching, file uploads, reactions, channel management, and user lookups. This routes through the Slack CLI router to the right per-method skill."
Draft the gateway skill for the family we inventoried in Step 01. Write the YAML front matter (name, description, trigger conditions) plus the body that explains how to call the router. Don't write the file yet. Show me the draft so I can refine the description first. The description is the surface Claude sees, so wording matters.
The agent does this for you. Claude proposes the front matter and the body. You read it, adjust the description to match how you actually phrase intents, then approve.
Build the router catalog
~30 minThe catalog is a structured file the router reads on every dispatch. One entry per per-method skill, with the fields the router needs to match against an intent.
| Field | What goes in it |
|---|---|
| skill_name | The slash command or skill ID Claude will invoke after the router returns. slack-cli-post-message, for example. |
| description | The same one-line description you pulled from the front matter in Step 01. |
| trigger_phrases | Natural language phrases that should route to this skill. The router matches user intent against these. |
| required_args | Parameters the skill needs. The router can populate these from the intent or return them as gaps for the gateway to fill. |
Generate the router catalog file by reading every skill we inventoried in Step 01. For each skill, write one entry with the four fields above. Use the existing skill descriptions verbatim where they're already good. Save to ~/.claude/skills/<family>-router/catalog.json. Show me the first three entries before writing the whole file.
The agent does this for you. Forty skill files, forty catalog entries, generated in one pass. You spot-check the first few, approve, and let it finish.
Pick where the router runs
~45 minThe router is a small model holding the catalog and answering queries. The default is local because it's cheap and fast: Ollama with a Qwen or Gemma class model, running on your computer. Local is the optimization, not the requirement. If your computer can't spare the RAM, the router can run on a remote host (a small VPS, an n8n workflow with an LLM node, anywhere it can hold the catalog and answer a webhook).
| Placement | When to pick it | Latency |
|---|---|---|
| Local model (Ollama) | You have spare RAM (4 to 8 GB). You want offline capability. You want zero per-dispatch cost. | Fastest, in-memory. |
| Remote host (VPS, n8n) | Your computer is RAM-constrained. You already run infrastructure. You want centralized observability. | One network hop plus a cheap LLM call. |
Look at my computer's RAM and current usage. Recommend local or remote for the router based on what I can actually spare. If local, walk me through installing Ollama and pulling a small instruction-following model (Qwen or Gemma class, 7B or smaller). If remote, walk me through configuring the gateway skill to call a webhook instead, and we'll set up the remote endpoint together. Pause between major decisions and wait for me to confirm.
The agent does this for you. You don't pick a model from a vendor matrix. Claude reads your machine's specs, picks a reasonable default, and installs it. You watch the first dispatch work before scaling up.
Test dispatch end to end
~30 minThe test is three real intents from your actual workflow. Not contrived examples. You want to see the gateway catch the intent, route through the router, return the matched skill name, and the CLI command fire.
Give me three real intents for the family we're routing. For each, run it through the gateway skill and report: which skill the router matched, what arguments it filled in, and what command the CLI ended up running. If any dispatch routes wrong, tell me which trigger phrase in the catalog needs to change to fix it. Don't change anything yet, just diagnose.
Watch the dispatch chain on each test:
- Claude sees the intent, picks the gateway skill (one front-matter description, the only one in this family).
- The gateway skill calls the router with the intent text.
- The router reads the catalog, returns the matched
skill_nameand anyrequired_args. - The gateway invokes the per-method skill locally with those args.
- The CLI command runs.
When it works.
You'll know the build is real when:
- Adding a new per-method skill is a one-line change in the catalog. No new front matter for Claude to scan. You install the skill, append the catalog entry, dispatch starts working. That's the leverage.
- Dispatch latency is consistent. Local model: a few hundred ms per dispatch after warm-up. Remote: one network round-trip plus a cheap LLM call. Either way, predictable.
- Claude stops hand-prompting itself. You don't have to say "you have a skill for this, go find it" anymore. The gateway description is broad enough to catch the intent and the router does the rest.
- You install a fortieth skill in the family and selection accuracy doesn't change. The auto-discovery ceiling stops being the variable that limits how many per-method skills you can ship.
If you get stuck.
Common failure modes, ranked by how often they bite people:
- Built the router before you needed it. Most common. A six-skill family does not justify a router. The abstraction costs more than it saves. Stay on direct per-method skills until the family is past about fifteen and selection accuracy actually slips.
- Gateway description too narrow. Claude doesn't pick the gateway because the description sounds like only one operation. Broaden it. List the operations the family covers ("posting, searching, file uploads, reactions, channels, users") so Claude knows the gateway is the entry point for all of them.
- Catalog trigger phrases too generic. The router matches the wrong skill because trigger phrases overlap. Tighten them. One skill per intent, not one intent per multiple skills.
- Local model RAM blew up your computer. The small models still want a few GB. If your daily-driver machine is already running hot, switch to a remote host (Step 04). The pattern doesn't depend on local.
- Pasted a real credential into the chat. Rotate the key immediately. Redo the credential step with the Infisical or 1Password placeholder pattern. If Claude offers to enter the real value for you, say no. Real credentials only get typed directly into your password manager.
Still stuck? Post the family you're routing, the gateway description you wrote, and the dispatch trace you saw, in the workshop Slack. Someone in the cohort is solving the same thing.
Where to go next.
You shipped the router. The natural next moves on the shelf: