Agent Token Saver Skill Router

Agent Token Saver Skill Router

Overview

Run the helper outside model context when the host supports prompt hooks. Load this router skill itself only on hosts without that mechanism or when changing router behavior.

Goal: keep the system prompt tiny, preserve prefix-cache stability, and load only the skills that actually change the next action.

For native hooks, shell-output compression, deterministic projections and the full measured stack, see https://github.com/Supersynergy/agent-token-saver. This router is a separate optional skill/CLI; the full-stack installer never downloads or updates it implicitly.

When to Use

Use when:

• The agent has a large SKILL.md library.
• Startup/system prompts include long skill catalogs.
• The user asks to save tokens, reduce context bloat, route skills, or make skills work across agents.
• You are in Hermes, Claude Code, Codex CLI, OpenCode, Cursor, Windsurf, or a repo-local .agents/skills setup.

Do not use for:

• A one-line factual answer where no skill is needed.
• Security/approval gates. Keep those explicit and separate.
• Hiding required safety/compliance instructions.

Operating Rule

Keep the router out of context when possible. Load everything lazily.

Default load budget:

Stop loading once the next concrete action is clear.

Automatic fuzzy routing stops at five. 10 is the hard ceiling for an explicit named stack, not a fuzzy-routing default. Keep one primary skill active in a worker; the controller may reserve support paths for a distinct phase or blocker. Legacy in-context routing controllers are explicit-only so automatic routing cannot recurse into another skill loader.

context-mode is also explicit-only: it is a heavy session layer, not a default for ordinary test, log or file tasks. Use $context-mode or start a dedicated heavy session only after deterministic projection is insufficient. Plain test verification also stays zero-skill; a debugger is selected only when the request itself asks to debug a failure.

Universal Discovery Order

Check the cheapest available source first:

1. Explicit $SkillName from the user.
2. Canonical cache (~/.cache/agent-token-saver/skills-index.json).
3. Grep-friendly skills.idx or bounded SKILL.md frontmatter.
4. Full SKILL.md bodies only for the selected primary/support set.
5. External search only if local discovery misses.

Common roots:

./.agents/skills
./.claude/skills
./.codex/skills
~/.agents/skills
~/.hermes/skills
~/.claude/skills
~/.claude/cts/skills
~/.codex/skills
~/.codex/plugins/cache
~/.gg/skills
~/.opencode/skills
~/.cursor/skills
~/.windsurf/skills

Adaptive Routing Loop

1. Classify the request: objective, domain, risk, output.
2. Resolve explicit names first: $SkillName must exact-match before fuzzy scoring, including plugin-cache skills.
3. Search candidate skill names/descriptions with 2-5 specific keywords.
4. Score candidates:
   • 3 = directly required
   • 2 = materially improves quality/safety
   • 1 = maybe useful later
   • 0 = skip
   • User favorites win close calls; generic tokens (matching many skills) are down-weighted.
   • Frontmatter tags participate in scoring; for debugging/testing work, skills under software-development outrank unrelated domain tutorials.
5. Select zero or one primary workflow skill, then add a support only when an independently confident task clause contributes new concrete evidence.
6. Load at most five automatic selections. Preserve mention order for a pure named stack. In a mixed request, infer the task primary first and append naturally named skills as supports.
7. Execute with tools.
8. Benchmark token savings when changing router behavior.

Self-Learning Without an Echo Chamber

Every CLI/hook route records a compact event under ~/.local/state/agent-skill-router/. The event contains a one-way intent hash, selected skill names, decision, score, margin and timestamp—never the raw prompt. si stats merges those route counts with actual load/use telemetry from Claude/Codex ~/.gg/skill-usage*.jsonl and Hermes ~/.hermes/skills/.usage.json.

Automatic learning uses actual application only as a tiny familiarity signal (maximum +2). Explicit si feedback <skill> success|failure is stronger, but the total adaptive adjustment stays between -6 and +8 and applies only after a skill already has a positive deterministic content match. Route frequency itself never improves rank, preventing self-reinforcing popularity loops. Alias history is aggregated into its canonical skill before ranking, and every report labels the current evidence window low, medium, or high confidence.

Operational telemetry stays in sidecars. The router never rewrites, archives, or deletes SKILL.md files automatically. Use si doctor, si drift, and the complete si stats --all report to select review-gated metadata/content improvements.

Tools use a separate registry and ranking surface. ghmax (alias ghgrep), tilth, canonical superweb (including the old superscrape, smart-fetch, hyperfetch, superfetch, supersearch, feeds-pull, batch-md-rs, and bulkfetch commands), synxp (alias synx), rtk, grepgod, rg, just, git, and other high-leverage local CLIs are never counted as skill loads. Exact tool names win deterministically; strong pure-tool requests return zero skills. Codex/Claude PostToolUse and Hermes post_tool_call observers store only canonical tool name, outcome, bounded latency and timestamp—never the command, arguments, output, or raw prompt. Tool learning is bounded and cannot create semantic relevance.

Skill suites are not alias maps. The Superweb component skills superscrape, stealth-research, stealth-scraper, and scrape-deep keep their own exact-name telemetry and feedback while generic multi-step web work selects superweb. Only equivalent executable modes share the canonical tool ranking.

Stacks, Subagents, and Processes

• Default: route "<task>" returns zero, one primary, or a complementary bundle of one primary plus at most four supports.
• Explicit names: $skill-name syntax or natural “use A, B, and C” wording preserves mention order. --max 10 permits a named 10-skill manifest; fuzzy routing remains capped at five.
• Controller: load only the primary skill needed for its next decision. Hand a subagent only its own primary path plus a compact task contract; do not forward the controller's full stack or raw catalog.
• Reserve the remaining paths for phase changes (for example implementation → release → security review). Load a reserve skill only when it changes the next action.
• Explicit references retain their order and can fill all 10 slots. Fuzzy support results must cover a distinct phase; score-near alternatives are exposed under consider and are not loaded.

Agent teams

Use a controller, not a broad prompt broadcast. Before spawning, define one independent closed objective and one machine oracle for each lane. A worker receives a 300–700-token capsule containing evidence paths/hashes, constraints, one routed skill path at most, three tries at most and a <=500-token return.

Start with no worker for a small overlapping check. Otherwise use at most three independent workers. The controller receives claim, evidence reference, command and oracle result—not raw logs or the parent transcript—and totals parent, children, retries, fallbacks and compactions before accepting the result.

CLI Helper

If this repo is installed, use the helper:

si index --refresh
si route "<task>" --strict --json
si find "<keywords>" --limit 8
si resolve <exact-skill-name>
si resolve <legacy-name> --canonical
si aliases --json
si drift --all --json --output /tmp/skill-drift.json
si explain "<task>"
si stats --all --output /tmp/skill-usage.tsv
si feedback <exact-skill-name> success
si tools --all --output /tmp/tool-usage.tsv
si inventory --output /tmp/skill-tool-inventory.json
si tool-feedback ghmax success --latency-ms 850
si install-hooks --target all
si hook-status
si doctor --json
si bench "<task>"

Hermes preserves its consent gate: with hooks_auto_accept: false, approve the new observer once on first use. The installer never weakens that global gate.

si and agent-skill-route are identical entrypoints. No dependencies. Python stdlib only. The cache TTL defaults to 300 seconds; rebuild after skill installs or frontmatter edits.

Historical names remain compatibility shims. si aliases shows their canonical responsibility; explicit aliases resolve directly to the canonical skill when it is installed, and si stats aggregates historical applied usage into that name without double-counting events. Aliases and umbrella routers stay excluded from automatic fuzzy selection. si drift separately reports identical and divergent active same-name copies without modifying them.

Favorites & Noise Filter

• Favorites: pin your go-to skills in ~/.agents/skill-favorites.txt — one name or name=weight per line (default weight 6, # comments). Pinned skills get a boost and win close calls, marked ★ in router output. The boost applies only when the skill already matches the intent, so favorites never surface for unrelated tasks. Override the file path with AGENT_SKILL_FAVORITES_FILE.
• Noise filter: scan skips backup/stale skill copies automatically — dir or flat-file names matching *.bak*, *-backup, *.old, *.disabled, *-deprecated.
• Specific beats generic: intent tokens that match many skills (e.g. cli, app) are down-weighted by document frequency; rare, specific tokens dominate the ranking.

Agent-Specific Notes

Hermes

Best config:

hermes config set skills.prompt_router_only true
hermes config set skills.router_skill agent-token-saver-skill-router

Restart or start a new session so the cached system prompt rebuilds.

Claude Code

Install to:

~/.claude/skills/agent-token-saver-skill-router/SKILL.md

Keep bulky skill families in cold storage when possible. Search indexes first, read full skills only after routing.

Codex CLI

Install to:

~/.codex/skills/agent-token-saver-skill-router/SKILL.md

For repos that prefer portable instructions, also add a short pointer in AGENTS.md:

Use agent-token-saver-skill-router first. Do not load broad skill catalogs; route by local SKILL.md frontmatter and lazy-load only selected skills.

GG Coder

Install globally to:

~/.gg/skills/agent-token-saver-skill-router.md

For project-local GG Coder use, copy the same file to:

.gg/skills/agent-token-saver-skill-router.md

Repo-local agents

Install to:

.agents/skills/agent-token-saver-skill-router/SKILL.md

This makes the router travel with the repository.

Benchmark Protocol

Use chars/4 as the portable estimate unless a tokenizer is installed.

Report:

• full catalog chars/tokens/lines
• router block chars/tokens/lines
• absolute tokens saved
• percent reduction
• command used

Pitfalls

1. Loading umbrella skills for curiosity. Load only when the task needs the procedure.
2. Breaking prompt cache mid-session. Change router config, then start a new session.
3. Deleting skills instead of de-hotting them. Cold skills should remain discoverable and loadable.
4. Routing by names only. Descriptions catch domain-specific skills with generic names.
5. Compressing safety away. Approval, privacy, destructive-command, and outreach gates remain hot when required by policy.

Verification Checklist

• Router runs outside model context when hooks are available.
• Full skills remain loadable on demand.
• bench shows before/after token counts.
• No more than one skill is auto-loaded per normal task or subagent.
• Team workers are independent, capped at three, and have a machine oracle.
• Broad controller stacks use at most 10 paths and lazy-load by phase.
• Production/security/release phase changes still route to the right gate skill.
• New session/restart confirms prompt-size reduction.
• Route logs contain hashes and scores, never raw prompts.
• Learned adjustments cannot create relevance or exceed the bounded range.