Skip to content
Back to search

intelligent-model-router-skills

Select models for tasks and subtasks using a supplied model inventory and evidence. Offline alpha with deterministic ranking.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/whale-devx--intelligent-model-router-skills/badge.svg)](/listings/whale-devx--intelligent-model-router-skills)

HTML

<a href="/listings/whale-devx--intelligent-model-router-skills"><img src="/api/listings/whale-devx--intelligent-model-router-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install the skill

Run this in your project, then choose your agent in the installer:

npx skills add whale-devx/intelligent-model-router-skills --skill intelligent-model-router

[Installation for Codex, Claude Code, Cursor, Gemini CLI, Kiro CLI and API clients](docs/PORTABILITY.md)

Use a Node.js version supported by the [Skills CLI](https://github.com/vercel-labs/skills#install-a-skill). Python is **not** required for the instruction-only workflow.

<details> <summary>Install across projects, choose an agent, or install manually</summary>

Add `-g` for a user-level installation:

npx skills add whale-devx/intelligent-model-router-skills --skill intelligent-model-router -g

Use `-a` to select an installer target, for example:

npx skills add whale-devx/intelligent-model-router-skills --skill intelligent-model-router -a claude-code

This names an installer target, **not** a certification of this skill's live-host behavior. See the [host test checklist](docs/HOST-TESTS.md).

For a manual installation, copy the entire `skills/intelligent-model-router/` folder to your host's documented skill location. Keep its references, assets, scripts, and license together. Review before replacing an existing installation.

[Installation details, privacy, and troubleshooting](docs/GETTING-STARTED.md)

</details>

2. Ask your agent to use it

Use intelligent-model-router before creating subagents.
Inspect the models this host exposes to me; do not assume access.
Choose a model for each actual task using relevant evidence.
Keep my existing permissions, privacy rules, and budget.
If evidence is missing, explain what is needed.
If delegation is unavailable, recommend only.

3. Review the plan

Expect the selected model, reasons, evidence dates, exclusions, and execution status. When a verified endpoint stays a recommendation, check `reasons` for the missing host or endpoint capability, policy authorization or delegation limit. The helper **does not call a model**: it returns a recommendation or a proposed host operation. A host must revalidate permissions and confirm any actual handoff.

**No new inference account. No gateway. No server required.** The skill and bundled helpers send no telemetry. The external installer has its own [telemetry settings](docs/GETTING-STARTED.md#installer-privacy).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 225 lines
  1. <picture>
  2. <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
  3. <source media="(prefers-color-scheme: light)" srcset="docs/assets/banner-light.svg">
  4. <img src="docs/assets/banner-light.svg" alt="Your models, one clear decision: available models flow through a routing decision to a recommendation or an authorized host handoff." width="1200">
  5. </picture>
  6. # Intelligent Model Router Skills
  7. **Use the models you already have. Choose with evidence.**
  8. A provider-neutral [Agent Skill](https://agentskills.io/specification) that helps your
  9. agent choose a model **before a task handoff or subagent creation**. Start with the
  10. models you can access, check the constraints, and get an explainable routing plan.
  11. **Your host stays in control of execution.**
  12. [![Offline checks on main](https://github.com/whale-devx/intelligent-model-router-skills/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/whale-devx/intelligent-model-router-skills/actions/workflows/ci.yml)
  13. [![Stage: alpha](https://img.shields.io/badge/stage-alpha-9a6700)](#current-status)
  14. [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0969da)](LICENSE)
  15. [**Quick start**](#quick-start) · [**How it works**](#how-it-works) · [**Documentation**](docs/README.md) · [**Roadmap**](docs/ROADMAP.md) · [**ภาษาไทย**](docs/README.th.md)
  16. > [!IMPORTANT]
  17. > **0.1.0-alpha.1 is an offline reference implementation.** Host/user-supplied
  18. > inventory and evidence work today. Automatic account discovery, live leaderboard
  19. > imports, and native execution adapters are not implemented. Installing the skill
  20. > does not override a host's built-in Auto mode. [See current status](#current-status).
  21. ## Quick start
  22. ### 1. Install the skill
  23. Run this in your project, then choose your agent in the installer:
  24. ```sh
  25. npx skills add whale-devx/intelligent-model-router-skills --skill intelligent-model-router
  26. ```
  27. [Installation for Codex, Claude Code, Cursor, Gemini CLI, Kiro CLI and API clients](docs/PORTABILITY.md)
  28. Use a Node.js version supported by the [Skills CLI](https://github.com/vercel-labs/skills#install-a-skill).
  29. Python is **not** required for the instruction-only workflow.
  30. <details>
  31. <summary>Install across projects, choose an agent, or install manually</summary>
  32. Add `-g` for a user-level installation:
  33. ```sh
  34. npx skills add whale-devx/intelligent-model-router-skills --skill intelligent-model-router -g
  35. ```
  36. Use `-a` to select an installer target, for example:
  37. ```sh
  38. npx skills add whale-devx/intelligent-model-router-skills --skill intelligent-model-router -a claude-code
  39. ```
  40. This names an installer target, **not** a certification of this skill's live-host
  41. behavior. See the [host test checklist](docs/HOST-TESTS.md).
  42. For a manual installation, copy the entire `skills/intelligent-model-router/`
  43. folder to your host's documented skill location. Keep its references, assets,
  44. scripts, and license together. Review before replacing an existing installation.
  45. [Installation details, privacy, and troubleshooting](docs/GETTING-STARTED.md)
  46. </details>
  47. ### 2. Ask your agent to use it
  48. ```text
  49. Use intelligent-model-router before creating subagents.
  50. Inspect the models this host exposes to me; do not assume access.
  51. Choose a model for each actual task using relevant evidence.
  52. Keep my existing permissions, privacy rules, and budget.
  53. If evidence is missing, explain what is needed.
  54. If delegation is unavailable, recommend only.
  55. ```
  56. ### 3. Review the plan
  57. Expect the selected model, reasons, evidence dates, exclusions, and execution status.
  58. When a verified endpoint stays a recommendation, check `reasons` for the
  59. missing host or endpoint capability, policy authorization or delegation limit.
  60. The helper **does not call a model**: it returns a recommendation or a proposed
  61. host operation. A host must revalidate permissions and confirm any actual handoff.
  62. **No new inference account. No gateway. No server required.** The skill and bundled
  63. helpers send no telemetry. The external installer has its own
  64. [telemetry settings](docs/GETTING-STARTED.md#installer-privacy).
  65. ## When to use it
  66. | Your goal | The skill's role |
  67. | --- | --- |
  68. | **Choose a model for the next task** | Compare eligible models using task-relevant evidence and constraints. |
  69. | **Create specialized subagents** | Recommend a model for each subagent's actual task, without expanding permissions. |
  70. | **Reconsider a model or plan a fallback** | Make a new constrained decision at a safe boundary; never silently relax policy. |
  71. The skill selects **among your available models**, not every model on a leaderboard.
  72. It is not a provider subscription, inference proxy, or agent runtime.
  73. ## How it works
  74. ```mermaid
  75. flowchart TD
  76. A[Host or user supplies model inventory] --> B[Profile task and constraints]
  77. B --> C[Filter eligible models]
  78. C --> D[Compare permitted task-relevant evidence]
  79. D --> E{Enough comparable evidence?}
  80. E -->|No| F[Abstain and explain what is missing]
  81. E -->|Yes| G[Return an explainable routing plan]
  82. G --> H[Recommend only]
  83. G -.-> I[Host revalidates and performs an authorized handoff]
  84. ```
  85. **In words:** inventory → constraints → comparable evidence → plan, or an honest
  86. abstention. The dotted handoff belongs to the **external host**, not the offline
  87. helper. A public catalog is not proof of access; a plan is not an execution receipt.
  88. Read the [routing contract](skills/intelligent-model-router/references/contract.md)
  89. for exact input fields, ranking rules, defaults, and limitations.
  90. ## Current status
  91. | Available in this alpha | Not implemented or not yet verified |
  92. | --- | --- |
  93. | Portable `SKILL.md` and instruction-only workflow | Live-host conformance runs are not yet recorded |
  94. | Host/user discovery protocol and explicit-file inventory import | Automatic host-native account/model discovery |
  95. | Offline eligibility checks and deterministic ranking | Live leaderboard fetching and native execution adapters |
  96. | Provenance, exact model identities, source deduplication | Calibrated success probabilities and learned routing |
  97. | Proposed actions with permission and safe-boundary checks | A universal model switch or automatic Sub-agent API |
  98. The CI badge reports **offline checks on `main`**, not live-host compatibility,
  99. security certification, or an improvement in model quality.
  100. **Evidence rules:** unknown is not zero; popularity is not capability; preference
  101. is not correctness; leaderboard scores are not task-success probabilities.
  102. <details>
  103. <summary>What happens when information is missing?</summary>
  104. | Result | Meaning |
  105. | --- | --- |
  106. | `needs_inventory` | Supply an authorized model inventory. |
  107. | `no_eligible_models` | No candidate meets the current constraints. |
  108. | `insufficient_evidence` | Comparable, sufficiently current evidence is missing. |
  109. | `selected` | A model was selected; execution is still a separate host action. |
  110. Invalid input is rejected. Unknown efficiency values are not treated as free or
  111. instant. Missing evidence is not silently filled in. The complete rules are in the
  112. [contract](skills/intelligent-model-router/references/contract.md).
  113. </details>
  114. ## See the offline example
  115. This example uses **fictional models and synthetic scores**, not a live benchmark.
  116. From a repository checkout with Python 3.10+:
  117. ```sh
  118. python skills/intelligent-model-router/scripts/route.py --input skills/intelligent-model-router/assets/example-request.json --as-of 2026-11-20
  119. ```
  120. Abbreviated result:
  121. ```json
  122. {
  123. "status": "selected",
  124. "selected": {"id": "example-b"},
  125. "action": "recommend",
  126. "execution_status": "not_executed",
  127. "estimated_success_probability": null
  128. }
  129. ```
  130. Synthetic evidence cannot plan execution. The fixed date makes the demonstration
  131. repeatable; real requests must use current observations, not a replay date.
  132. <details>
  133. <summary>For contributors: run the offline test suite</summary>
  134. ```sh
  135. python -m unittest discover -s tests -v
  136. ```
  137. The helpers use Python's standard library. Tests cover validation, policy gates,
  138. source deduplication, stale/missing evidence, subagent depth, CLI behavior, and
  139. copying the skill outside the repository. See [contribution guidance](CONTRIBUTING.md).
  140. </details>
  141. ## Find your next step
  142. | I want to… | Start here |
  143. | --- | --- |
  144. | Install and try the skill | [Getting started](docs/GETTING-STARTED.md) |
  145. | Browse all documentation | [Documentation hub](docs/README.md) |
  146. | Integrate a host or supply model inventory | [Host protocol](skills/intelligent-model-router/references/host-protocol.md) |
  147. | Understand decisions or supply evidence | [Contract](skills/intelligent-model-router/references/contract.md) · [Source guide](skills/intelligent-model-router/references/sources.md) |
  148. | Test compatibility or report a problem | [Host checklist](docs/HOST-TESTS.md) · [Open an issue](https://github.com/whale-devx/intelligent-model-router-skills/issues/new/choose) |
  149. | Help build the next version | [Roadmap](docs/ROADMAP.md) · [Contributing](CONTRIBUTING.md) |
  150. Small contributions count: clarify a confusing step, improve a translation, or
  151. record a reproducible host test. Report failures and unknowns as well as successes.
  152. Never include credentials, personal inventories, or private prompts in public issues.
  153. For vulnerabilities, follow [SECURITY.md](SECURITY.md).
  154. ## License and attribution
  155. Project code and authored instructions use [Apache-2.0](LICENSE). Third-party data,
  156. benchmarks, and trademarks retain their own terms. A source guide is not a data
  157. redistribution license. No benchmark provider or host endorses this project.
  158. [Changelog](CHANGELOG.md) · [Security](SECURITY.md) · [Documentation style](docs/WRITING-GUIDE.md) · [Back to top](#intelligent-model-router-skills)
  159. [Import a pinned Arena English text snapshot](skills/intelligent-model-router/references/arena.md)
  160. Pass `--request request.json` to check Arena mappings against the endpoints in
  161. your routing request. A discovery key beginning with `unmapped:` cannot supply a quality score.
  162. If the router returns `insufficient_evidence`, check `evidence_coverage` for
  163. model keys missing observations and the number of independent origins that
  164. compare every eligible identity. [Reading the result](skills/intelligent-model-router/references/contract.md#diagnosing-insufficient-evidence)
  165. When sharing adapted scores, copy `source_notice` for the source and license
  166. credit. The full import report contains your local endpoint mappings.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.