npm install -g agentic-skill-router agentic-skill-router init
Install the CLI, then write the routing skill entry that agents can discover and invoke.
agentic-skill-router
A no-embedding, agent-facing routing skill that moves rarely used Agent Skills out of always-on context, then retrieves the right skill instructions on demand.
Agent support
Runs as a project or global routing skill for Codex and Claude Code agents.
1,152 units
Batch evidence combines 150 anonymized skills, 24 expert queries, 16 variants, and 48 aggregate rows.
Bash + Tool
Strategy experiments compare bash-based agentic retrieval, tool-wrapped retrieval, and catalog baselines.
Quick Start
Install the CLI, then initialize agentic-skill-router as an agent-facing routing skill. The README and CLI help remain the source of truth for the full option set.
agentic-skill-router init codex project $agentic-skill-router list
After restarting Codex, invoke the installed routing skill with Codex's $skill syntax.
agentic-skill-router init claude-code project /agentic-skill-router suggest
After restarting Claude Code, invoke the installed routing skill through its slash command.
agentic-skill-router skills web # http://127.0.0.1:8787
Browse, filter, disable, and restore local skills; the server binds to loopback by default.
agentic-skill-router skills route \ --query "draft a Lark mail reply" \ --json
Select a matching skill from the disabled corpus and emit structured output for agent workflows.
agentic-skill-router skills status agentic-skill-router skills enable user:codex:lark-mail
Restore SKILL.md from state records while keeping built-in and system skills protected.
Core Features
The project is a routing skill for reducing always-on skill metadata while keeping disable, restore, and on-demand retrieval controlled.
Installs a skill entry that agents can call when a task needs instructions from a disabled skill.
Reads local transcripts, extracts skill usage signals, and suggests stale or unused entries by last-used time.
Disables skills by renaming SKILL.md, keeps state records, and protects built-in system skills.
Searches local skill files directly with agentic retrieval instead of introducing embeddings or a vector database.
A localhost Web UI can browse, filter, disable, and restore skills; public binding requires an explicit danger flag.
Ships an npm CLI, Codex slash prompt, Claude Code plugin assets, and one unified routing skill workflow.
How It Works
agentic-skill-router adds an auditable skill-routing layer between local skill directories and the agent's normal trigger path.
01
Install skill
init writes a project or global routing skill entry that the agent can invoke.
02
Scan skills
Collect metadata, source, conflict, and disabled-state information into one actionable inventory.
03
Slim context
suggest combines transcript usage with policy rules, then leaves disable decisions explicit.
04
Route on demand
When a disabled skill is needed, the routing skill selects a target and reads its instructions.
05
Restore
enable restores SKILL.md through state records and supports repair paths for missing state.
Batch Experiment Results
Latest aggregate data comes from experiments/dci-compare/runs/rerun-150-full-2026-05-26:
48 aggregate rows and 1,152 experiment units across Claude, Codex, 16 routing variants,
and 24 expert queries.
Bash-based agentic retriever
The agent searches disabled skills directly with general shell commands such as
find, rg, and sed.
Pros: no embeddings, full-body evidence, and explainable traces. Tradeoff:
output and turns need bounds.
Tool-wrapped agentic retrieval
Search, open, and read actions are wrapped behind controlled tool interfaces while the agent still plans the retrieval path. Pros: steadier behavior and clearer boundaries. Tradeoff: tool design shapes recall and debugging.
Metadata / catalog retrieval
The workflow reads skill descriptions or a prebuilt catalog first, then expands candidates only when needed. Pros: cheaper, faster, and easier to bound. Risk: weak metadata can be pulled toward near-miss distractors.
48
aggregate rows
1,152
experiment units
16
routing variants
24
expert queries
0 / 0
timeouts / API errors
4
Codex configs hit 24/24
| Agent | Variant | Mode | Hits | Cost | Trigger | Avg work |
|---|---|---|---|---|---|---|
| Codex | I-meta |
with md | 24/24 | $3.02 | 100% | 3.0 turns / 2.0 tools |
| Codex | E-digest |
with md | 24/24 | $3.05 | 100% | 3.0 turns / 2.0 tools |
| Codex | K-lite-replicate |
with md | 24/24 | $3.27 | 100% | 3.5 turns / 2.4 tools |
| Codex | C-lite |
with md | 24/24 | $4.36 | 100% | 4.9 turns / 5.7 tools |
| Codex | G-native |
with md | 23/24 | $1.84 | 0% | 1.0 turns / 0.0 tools |
| Codex | K-lite |
with md | 23/24 | $2.77 | 100% | 3.3 turns / 2.2 tools |
| Codex | K-bounded |
with md | 23/24 | $2.83 | 100% | 3.8 turns / 2.8 tools |
| Codex | H-bounded |
with md | 23/24 | $4.94 | 100% | 5.8 turns / 5.7 tools |
| Claude | B-cc |
no md | 23/24 | $5.61 | 95.8% | 7.1 turns / 5.2 tools |
| Claude | K-lite |
with md | 22/24 | $4.06 | 95.8% | 4.0 turns / 2.1 tools |
Resources
Code, docs, and experiment artifacts stay in the repository for reproduction and implementation review.
Full experiment HTML report
Rendered all-experiments report, browsable directly on this site.
README
Install steps, CLI commands, skill paths, and runtime details.
Chinese README
Project overview and usage notes for Chinese readers.
Routing Skill
Agent-facing workflow and reference documents.
Report PDFs
Downloadable report, available as Chinese and English PDF editions.