Skills
skills/clawdbot/skills/model-router

model-router

SKILL.md

Model Router

Intelligent AI model routing across multiple providers for optimal cost-performance balance.

Automatically select the best model for any task based on complexity, type, and your preferences. Support for 6 major AI providers with secure API key management and interactive configuration.

🎯 What It Does

  • Analyzes tasks and classifies them by type (coding, research, creative, simple, etc.)
  • Routes to optimal models from your configured providers
  • Optimizes costs by using cheaper models for simple tasks
  • Secures API keys with file permissions (600) and isolated storage
  • Provides recommendations with confidence scoring and reasoning

🚀 Quick Start

Step 1: Run the Setup Wizard

cd skills/model-router
python3 scripts/setup-wizard.py

The wizard will guide you through:

  1. Provider setup - Add your API keys (Anthropic, OpenAI, Gemini, etc.)
  2. Task mappings - Choose which model for each task type
  3. Preferences - Set cost optimization level

Step 2: Use the Classifier

# Get model recommendation for a task
python3 scripts/classify_task.py "Build a React authentication system"

# Output:
# Recommended Model: claude-sonnet
# Confidence: 85%
# Cost Level: medium
# Reasoning: Matched 2 keywords: build, system

Step 3: Route Tasks with Sessions

# Spawn with recommended model
sessions_spawn --task "Debug this memory leak" --model claude-sonnet

# Use aliases for quick access
sessions_spawn --task "What's the weather?" --model haiku

📊 Supported Providers

Provider Models Best For Key Format
Anthropic claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5 Coding, reasoning, creative sk-ant-...
OpenAI gpt-4o, gpt-4o-mini, o1-mini, o1-preview Tools, deep reasoning sk-proj-...
Gemini gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash Multimodal, huge context (2M) AIza...
Moonshot moonshot-v1-8k/32k/128k Chinese language sk-...
Z.ai glm-4.5-air, glm-4.7 Cheapest, fast Various
GLM glm-4-flash, glm-4-plus, glm-4-0520 Chinese, coding ID.secret

🎛️ Task Type Mappings

Default routing (customizable via wizard):

Task Type Default Model Why
simple glm-4.5-air Fastest, cheapest for quick queries
coding claude-sonnet-4-5 Excellent code understanding
research claude-sonnet-4-5 Balanced depth and speed
creative claude-opus-4-5 Maximum creativity
math o1-mini Specialized reasoning
vision gemini-1.5-flash Fast multimodal
chinese glm-4.7 Optimized for Chinese
long_context gemini-1.5-pro Up to 2M tokens

💰 Cost Optimization

Aggressive Mode

Always uses the cheapest capable model:

  • Simple → glm-4.5-air (~10% cost)
  • Coding → claude-haiku-4-5 (~25% cost)
  • Research → claude-sonnet-4-5 (~50% cost)

Savings: 50-90% compared to always using premium models

Balanced Mode (Default)

Considers cost vs quality:

  • Simple tasks → Cheap models
  • Critical tasks → Premium models
  • Automatic escalation if cheap model fails

Quality Mode

Always uses the best model regardless of cost

🔒 Security

API Key Storage

~/.model-router/
├── config.json       # Model mappings (chmod 600)
└── .api-keys         # API keys (chmod 600)

Features:

  • File permissions restricted to owner (600)
  • Isolated from version control
  • Encrypted at rest (via OS filesystem encryption)
  • Never logged or printed

Best Practices

  1. Never commit .api-keys to version control
  2. Use environment variables for production deployments
  3. Rotate keys regularly via the wizard
  4. Audit access with ls -la ~/.model-router/

📖 Usage Examples

Example 1: Cost-Optimized Workflow

# Classify task first
python3 scripts/classify_task.py "Extract prices from this CSV"

# Result: simple task → use glm-4.5-air
sessions_spawn --task "Extract prices" --model glm-4.5-air

# Then analyze with better model if needed
sessions_spawn --task "Analyze price trends" --model claude-sonnet

Example 2: Progressive Escalation

# Try cheap model first (60s timeout)
sessions_spawn --task "Fix this bug" --model glm-4.5-air --runTimeoutSeconds 60

# If fails, escalate to premium
sessions_spawn --task "Fix complex architecture bug" --model claude-opus

Example 3: Parallel Processing

# Batch simple tasks in parallel with cheap model
sessions_spawn --task "Summarize doc A" --model glm-4.5-air &
sessions_spawn --task "Summarize doc B" --model glm-4.5-air &
sessions_spawn --task "Summarize doc C" --model glm-4.5-air &
wait

Example 4: Multimodal with Gemini

# Vision task with 2M token context
sessions_spawn --task "Analyze these 100 images" --model gemini-1.5-pro

🛠️ Configuration Files

~/.model-router/config.json

{
  "version": "1.1.0",
  "providers": {
    "anthropic": {
      "configured": true,
      "models": ["claude-opus-4-5", "claude-sonnet-4-5", "claude-haiku-4-5"]
    },
    "openai": {
      "configured": true,
      "models": ["gpt-4o", "gpt-4o-mini", "o1-mini", "o1-preview"]
    }
  },
  "task_mappings": {
    "simple": "glm-4.5-air",
    "coding": "claude-sonnet-4-5",
    "research": "claude-sonnet-4-5",
    "creative": "claude-opus-4-5"
  },
  "preferences": {
    "cost_optimization": "balanced",
    "default_provider": "anthropic"
  }
}

~/.model-router/.api-keys

# Generated by setup wizard - DO NOT edit manually
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...
GEMINI_API_KEY=AIza...

🔄 Version 1.1 Changes

New Features

  • ✅ Interactive setup wizard for guided configuration
  • ✅ Secure API key storage with file permissions
  • ✅ Task-to-model mapping customization
  • ✅ Multi-provider support (6 providers)
  • ✅ Cost optimization levels (aggressive/balanced/quality)

Improvements

  • ✅ Better task classification with confidence scores
  • ✅ Provider-specific model recommendations
  • ✅ Enhanced security with isolated storage
  • ✅ Comprehensive documentation

Migration from 1.0

Run the setup wizard to reconfigure:

python3 scripts/setup-wizard.py

📚 Command Reference

Setup Wizard

python3 scripts/setup-wizard.py

Interactive configuration of providers, mappings, and preferences.

Task Classifier

python3 scripts/classify_task.py "your task description"
python3 scripts/classify_task.py "your task" --format json

Get model recommendation with reasoning.

List Models

python3 scripts/setup-wizard.py --list

Show all available models and their status.

🤝 Integration with Other Skills

Skill Integration
model-usage Track cost per provider to optimize routing
sessions_spawn Primary tool for model delegation
session_status Check current model and usage

⚡ Performance Tips

  1. Start simple - Try cheap models first
  2. Batch tasks - Combine multiple simple tasks
  3. Use cleanup - Delete sessions after one-off tasks
  4. Set timeouts - Prevent runaway sub-agents
  5. Monitor usage - Track costs per provider

🐛 Troubleshooting

"No suitable model found"

  • Run setup wizard to configure providers
  • Check API keys are valid
  • Verify permissions on .api-keys file

"Module not found"

pip3 install -r requirements.txt  # if needed

Wrong model selected

  1. Customize task mappings via wizard
  2. Use explicit model in sessions_spawn --model
  3. Adjust cost optimization preference

📖 Additional Resources

Weekly Installs
4
Repository
clawdbot/skills
Installed on
opencode3
windsurf2
clawdbot2
trae2
codex2
claude-code2