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

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

OpenAI

Codex (for coding):

Google Gemini

Ollama (Local)

CLI Mappings (for spawn:agent skill)

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

config/model_tiers.json

config/known_models.json

cache/models.json

API Endpoints

GET /v1/models

x-api-key

GET /v1/models

GET /v1beta/models

?key=

GET /api/tags

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