What is adding-models?

This Claude skill provides a comprehensive developer guide for integrating and configuring new Large Language Models (LLMs) within the Letta Code environment. It streamlines the technical workflow for model handle validation, models.json configuration, and CI/CD matrix updates, ensuring seamless multi-provider support for frameworks like Anthropic, OpenAI, and Google AI.

When should I use adding-models?

adding-models is useful in the following scenarios: • New Model Integration: Quickly add the latest LLM releases (e.g., GPT-5, Gemini updates) to your agentic framework by following a standardized configuration workflow. • Configuration Management: Centralize and manage model-specific parameters such as context windows, temperatures, and reasoning settings to ensure consistent performance across different providers. • CI/CD Pipeline Maintenance: Automatically update GitHub Actions test matrices to include new models in automated quality assurance and headless testing suites. • Provider Handle Validation: Efficiently query and verify valid model handles from various API providers (OpenRouter, Vertex AI, etc.) to prevent 'handle not found' errors during deployment.

name	adding-models
description	Guide for adding new LLM models to Letta Code. Use when the user wants to add support for a new model, needs to know valid model handles, or wants to update the model configuration. Covers models.json configuration, CI test matrix, and handle validation.

Adding Models

This skill guides you through adding a new LLM model to Letta Code.

Quick Reference

Key files:

src/models.json - Model definitions (required)
.github/workflows/ci.yml - CI test matrix (optional)
src/tools/manager.ts - Toolset detection logic (rarely needed)

Workflow

Step 1: Find Valid Model Handles

Query the Letta API to see available models:

curl -s https://api.letta.com/v1/models/ | jq '.[] | .handle'

Or filter by provider:

curl -s https://api.letta.com/v1/models/ | jq '.[] | select(.handle | startswith("google_ai/")) | .handle'

Common provider prefixes:

anthropic/ - Claude models
openai/ - GPT models
google_ai/ - Gemini models
google_vertex/ - Vertex AI
openrouter/ - Various providers

Step 2: Add to models.json

Add an entry to src/models.json:

{
  "id": "model-shortname",
  "handle": "provider/model-name",
  "label": "Human Readable Name",
  "description": "Brief description of the model",
  "isFeatured": true,  // Optional: shows in featured list
  "updateArgs": {
    "context_window": 180000,
    "temperature": 1.0  // Optional: provider-specific settings
  }
}

Field reference:

id: Short identifier used with --model flag (e.g., gemini-3-flash)
handle: Full provider/model path from the API (e.g., google_ai/gemini-3-flash-preview)
label: Display name in model selector
description: Brief description shown in selector
isFeatured: If true, appears in featured models section
updateArgs: Model-specific configuration (context window, temperature, reasoning settings, etc.)

Provider prefixes:

anthropic/ - Anthropic (Claude models)
openai/ - OpenAI (GPT models)
google_ai/ - Google AI (Gemini models)
google_vertex/ - Google Vertex AI
openrouter/ - OpenRouter (various providers)

Step 3: Test the Model

Test with headless mode:

bun run src/index.ts --new --model <model-id> -p "hi, what model are you?"

Example:

bun run src/index.ts --new --model gemini-3-flash -p "hi, what model are you?"

Step 4: Add to CI Test Matrix (Optional)

To include the model in automated testing, add it to .github/workflows/ci.yml:

# Find the headless job matrix around line 122
model: [gpt-5-minimal, gpt-4.1, sonnet-4.5, gemini-pro, your-new-model, glm-4.6, haiku]

Toolset Detection

Models are automatically assigned toolsets based on provider:

openai/* → codex toolset
google_ai/* or google_vertex/* → gemini toolset
Others → default toolset

This is handled by isGeminiModel() and isOpenAIModel() in src/tools/manager.ts. You typically don't need to modify this unless adding a new provider.

Common Issues

"Handle not found" error: The model handle is incorrect. Run the validation script to see valid handles.

Model works but wrong toolset: Check src/tools/manager.ts to ensure the provider prefix is recognized.

adding-models

When & Why to Use This Skill

Use Cases