model-discovery

name	model-discovery
description	Fetch current model names from AI providers (Anthropic, OpenAI, Gemini, Ollama), classify them into tiers (fast/default/heavy), and detect new models. Use when needing up-to-date model IDs for API calls or when other skills reference model names.

Model Discovery Skill

Fetch the most recent model names from AI providers using their APIs. Includes tier classification (fast/default/heavy) for routing decisions and automatic detection of new models.

Variables

Variable	Default	Description
CACHE_TTL_HOURS	24	How long to cache model lists before refreshing
ENABLED_ANTHROPIC	true	Fetch Claude models from Anthropic API
ENABLED_OPENAI	true	Fetch GPT models from OpenAI API
ENABLED_GEMINI	true	Fetch Gemini models from Google API
ENABLED_OLLAMA	true	Fetch local models from Ollama
OLLAMA_HOST	http://localhost:11434	Ollama API endpoint
AUTO_CLASSIFY	true	Auto-classify new models using pattern matching

Instructions

MANDATORY - Follow the Workflow steps below in order. Do not skip steps.

• Before referencing model names in any skill, check if fresh data exists
• Use tier mappings to select appropriate models (fast for speed, heavy for capability)
• Check for new models periodically and classify them

Red Flags - STOP and Reconsider

If you're about to:

• Hardcode a model version like gpt-5.2 or claude-sonnet-4-5
• Use model names from memory without checking current availability
• Call APIs without checking if API keys are configured
• Skip new model classification when prompted

STOP -> Read the appropriate cookbook file -> Use the fetch script

Workflow

Fetching Models

1. Determine which provider(s) you need models from
2. Check if cached model list exists: cache/models.json
3. If cache is fresh (< CACHE_TTL_HOURS old), use cached data
4. If stale/missing, run: uv run python scripts/fetch_models.py --force
5. CHECKPOINT: Verify no API errors in output
6. Use the model IDs as needed

Checking for New Models

1. Run: uv run python scripts/check_new_models.py --json
2. If new models found, review the output
3. For auto-classification: uv run python scripts/check_new_models.py --auto
4. For interactive classification: uv run python scripts/check_new_models.py
5. CHECKPOINT: All models assigned to tiers (fast/default/heavy)

Getting Tier Recommendations

1. Read: config/model_tiers.json for current tier mappings
2. Use the appropriate model for task complexity:
   • fast: Simple tasks, high throughput, cost-sensitive
   • default: General purpose, balanced
   • heavy: Complex reasoning, research, difficult tasks

Model Tier Reference

Anthropic Claude

Tier	Model	CLI Name
fast	claude-haiku-4-5	haiku
default	claude-sonnet-4-5	sonnet
heavy	claude-opus-4-5	opus

OpenAI

Tier	Model	Notes
fast	gpt-5.2-mini	Speed optimized
default	gpt-5.2	Balanced flagship
heavy	gpt-5.2-pro	Maximum capability

Codex (for coding):

Tier	Model
fast	gpt-5.2-codex-mini
default	gpt-5.2-codex
heavy	gpt-5.2-codex-max

Google Gemini

Tier	Model	Context
fast	gemini-3-flash-lite	See API output
default	gemini-3-pro	See API output
heavy	gemini-3-deep-think	See API output

Ollama (Local)

Tier	Suggested Model	Notes
fast	phi3.5:latest	Small; fast
default	llama3.2:latest	Balanced
heavy	llama3.3:70b	Large; requires GPU

CLI Mappings (for spawn:agent skill)

CLI Tool	Fast	Default	Heavy
claude-code	haiku	sonnet	opus
codex-cli	gpt-5.2-codex-mini	gpt-5.2-codex	gpt-5.2-codex-max
gemini-cli	gemini-3-flash-lite	gemini-3-pro	gemini-3-deep-think
cursor-cli	gpt-5.2	sonnet-4.5	sonnet-4.5-thinking
opencode-cli	anthropic/claude-haiku-4-5	anthropic/claude-sonnet-4-5	anthropic/claude-opus-4-5
copilot-cli	claude-sonnet-4.5	claude-sonnet-4.5	claude-sonnet-4.5

Quick Reference

Scripts

# Fetch all models (uses cache if fresh)
uv run python scripts/fetch_models.py

# Force refresh from APIs
uv run python scripts/fetch_models.py --force

# Fetch and check for new models
uv run python scripts/fetch_models.py --force --check-new

# Check for new unclassified models (JSON output for agents)
uv run python scripts/check_new_models.py --json

# Auto-classify new models using patterns
uv run python scripts/check_new_models.py --auto

# Interactive classification
uv run python scripts/check_new_models.py

Config Files

File	Purpose
config/model_tiers.json	Static tier mappings and CLI model names
config/known_models.json	Registry of all classified models with timestamps
cache/models.json	Cached API responses

API Endpoints

Provider	Endpoint	Auth
Anthropic	GET /v1/models	x-api-key header
OpenAI	GET /v1/models	Bearer token
Gemini	GET /v1beta/models	?key= param
Ollama	GET /api/tags	None

Output Examples

Fetch Models Output

{
  "fetched_at": "2025-12-17T05:53:25Z",
  "providers": {
    "anthropic": [{"id": "claude-opus-4-5", "name": "Claude Opus 4.5"}],
    "openai": [{"id": "gpt-5.2", "name": "gpt-5.2"}],
    "gemini": [{"id": "models/gemini-3-pro", "name": "Gemini 3 Pro"}],
    "ollama": [{"id": "phi3.5:latest", "name": "phi3.5:latest"}]
  }
}

Check New Models Output (--json)

{
  "timestamp": "2025-12-17T06:00:00Z",
  "has_new_models": true,
  "total_new": 2,
  "by_provider": {
    "openai": {
      "count": 2,
      "models": [
        {"id": "gpt-5.2-mini", "inferred_tier": "fast", "needs_classification": false},
        {"id": "gpt-5.2-pro", "inferred_tier": "heavy", "needs_classification": false}
      ]
    }
  }
}

Integration

Other skills should reference this skill for model names:

## Model Names

For current model names and tiers, use the `model-discovery` skill:
- Tiers: Read `config/model_tiers.json`
- Fresh data: Run `uv run python scripts/fetch_models.py`
- New models: Run `uv run python scripts/check_new_models.py --json`

**Do not hardcode model version numbers** - they become stale quickly.

New Model Detection

When new models are detected:

1. The script will report them with suggested tiers based on naming patterns
2. Models matching these patterns are auto-classified:
   • heavy: -pro, -opus, -max, thinking, deep-research
   • fast: -mini, -nano, -flash, -lite, -haiku
   • default: Base model names without modifiers
3. Models not matching patterns require manual classification
4. Specialty models (TTS, audio, transcribe) are auto-excluded

Agent Query for New Models

When checking for new models programmatically:

# Returns exit code 1 if new models need attention
uv run python scripts/check_new_models.py --json

# Example agent workflow
if ! uv run python scripts/check_new_models.py --json > /tmp/new_models.json 2>&1; then
    echo "New models detected - review /tmp/new_models.json"
fi