model-inventory

Model Inventory

Scan → probe → cache: which AI CLIs live on this machine, which models each can actually use right now, and a role→model routing table other skills consume to spawn each sub-agent on the best model available — strongest for planning, cheapest that suffices for mechanical work.

When to use this skill

• "scan available models" / "which models can I use" / "check my model access"
• "what AI CLIs are installed" / "is fable available"
• "refresh the model inventory" / "/model-inventory"
• A consumer skill (goal-runner, autopilot, task-executor) finds ~/.claude/model-inventory.json missing or stale at kickoff and invokes this skill to rebuild it

Do not auto-trigger mid-task to choose a model — consumers read the cached inventory; rescanning is this skill's explicit job.

Evidence tiers

The rule consumers rely on: a model status not observed from a live probe is unverified, never verified. An expired subscription looks identical to an active one until tier 3 — that's the whole reason tier 3 exists.

• ❌ "claude is installed and has credentials, so fable: verified" — the plan may not include fable; that's an entitlement error only a probe surfaces.
• ✅ fable: verified — probe replied "ok" or fable: unavailable — "Error: model not available on your plan" (quoted).

Workflow

1. Tiers 1–2 — run the scan. Execute scripts/scan.sh (bash; runs on Git Bash/macOS/Linux) and show the user the per-CLI result. Zero tokens spent, nothing sent anywhere.
2. Tier 3 — probe, unless the user said "quick scan". For each installed CLI, run the probe command from references/cli-registry.md once per seed model (claude: all four aliases; other CLIs: default only) and classify by the table there: verified / unavailable / blocked-by-auth / quota-exhausted / unknown. A login error flips the CLI's auth.status to unauthenticated and marks all its models blocked-by-auth — the "installed but account not active" case, with the error line quoted. A timeout is unknown, never unavailable. One attempt per model; retry once only after changing one named thing; second failure → record unknown with the quoted error and move on. Ollama needs no probe — ollama list already verified its models locally.
3. Build the routing table per the rules below, from probe results only.
4. Write ~/.claude/model-inventory.json (schema below), then report: a per-CLI table (version, auth status, each model's status with evidence), what was probed vs. assumed, and total probe cost. Zero usable CLIs is a valid outcome — write the inventory anyway so consumers see an honest empty rather than a missing file.

Routing rules

routing.agent_tool holds fallback chains of claude aliases only (haiku/sonnet/opus/fable — never dated model ids, they rot; sub-agents spawned via the Agent tool ride the current session's auth). Start from the canonical chains, then delete any alias whose probe said unavailable or blocked-by-auth; never reorder:

{
  "planner":         ["fable", "opus", "sonnet"],
  "coder":           ["sonnet"],
  "coder_high_risk": ["fable", "opus", "sonnet"],
  "scout":           ["haiku", "sonnet"],
  "reviewer":        ["opus", "sonnet"],
  "fixer":           ["sonnet"]
}

The cost policy lives in the shape: the strongest model is the escalation (planning, high-blast-radius coding, review adjudication), never the default for mechanical work. routing.bash_workers lists non-claude CLIs whose default probe verified — candidates for shell-invoked delegation, not Agent-tool spawns.

Consumption contract

• File: ~/.claude/model-inventory.json. Top level: schema, generated_at (UTC ISO), platform, probed (bool), clis[] (name, installed, path, version, auth{status,evidence}, invocation, optional default_model{id,evidence} from the CLI's local config, models[]{id,status,evidence} where a default entry carries resolved_id when the probe banner revealed what actually ran), routing{agent_tool, bash_workers}.
• Consumers take the first entry of a role's chain not marked unavailable/blocked-by-auth/quota-exhausted and pass it as the Agent tool's model param — bare aliases only; skip any other value. Missing, unparseable, generated_at older than 7 days, or probed: false → treat as absent: spawn with no model override and optionally suggest rerunning this skill. Never let a stale inventory block work, and never hand-write this file from a consumer — it's this skill's artifact. Consumers with this skill installed may invoke it once at kickoff to rebuild a missing/stale inventory (logging the discovery run), and may rerun scripts/scan.sh as a free sanity check anytime — but never probe mid-run; mid-run model failures are the consumer's chain-fallback problem, not a rescan trigger.

Examples

Example 1: full scan

User: "scan available models"

Claude: runs scan.sh (finds claude + codex installed, both likely-authenticated; gemini not installed), probes claude's four aliases (haiku/sonnet/opus verified; fable → unavailable, quoted: "not available on your plan") and codex's default (verified), writes the inventory with planner: ["opus","sonnet"] (fable deleted per probe), reports the table + ~$0.03 probe cost.

Example 2: installed but account inactive

User: "refresh the model inventory"

Claude: scan shows codex installed with ~/.codex/auth.json present (tier 2: likely-authenticated). The tier-3 probe returns "Not logged in — run codex login". Inventory records auth.status: "unauthenticated" with that line quoted, default: blocked-by-auth, and codex is left out of bash_workers. The report tells the user codex login would restore it — the skill never runs login flows itself.

Anti-patterns

• ❌ Marking a model verified because the CLI is installed or credentials exist — tier 2 cannot see expired subscriptions or plan entitlements.
• ❌ Recording a probe timeout as unavailable — a flaky network would silently delete your best model from every chain. Timeout = unknown, chain keeps the alias.
• ❌ Writing credential values into evidence — name the signal ("env OPENAI_API_KEY is set"), never print the key.
• ❌ Putting dated model ids in agent_tool chains — aliases only; ids rot and consumers pass these straight into spawns.
• ❌ Re-probing in a loop until a model "comes back" — one attempt, one named-change retry, done.
• ❌ Running codex login / auth flows to "fix" an inactive account — report it; the login is the user's move.
• ✅ Scan free, probe once with quoted evidence, write the inventory, report what's verified vs. assumed vs. blocked.

Notes

• Composes with goal-runner, autopilot, and task-executor as consumers (they resolve each sub-agent role from routing.agent_tool when the inventory is fresh, invoke this skill once at kickoff to rebuild it when it's missing or stale, and degrade to no-override when this skill isn't installed or discovery fails). This skill owns discovery and the file format; consumers never probe mid-run.
• To cover another CLI, follow "Adding a CLI" in references/cli-registry.md — one auth heuristic in scan.sh, one registry section.
• Ollama models are free to run but weak as coding workers — they land in bash_workers with their evidence; consumers decide whether local quality suffices.