|
| 1 | +--- |
| 2 | +name: model-provider-setup |
| 3 | +description: Configure Claude Code to use alternative AI model providers by setting up custom API endpoints and authentication. Use this skill when users want to switch from default Anthropic models to providers like Z.AI, OpenRouter, or other custom endpoints with compatible APIs. |
| 4 | +--- |
| 5 | + |
| 6 | +# Model Provider Setup |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +This skill configures `.claude/settings.local.json` to use alternative AI model providers that offer Anthropic-compatible APIs. It guides the setup of custom base URLs, model selections, and API authentication for providers beyond the default Anthropic service. |
| 11 | + |
| 12 | +## When to Use This Skill |
| 13 | + |
| 14 | +Use this skill when users: |
| 15 | +- Want to switch to alternative model providers (Z.AI, OpenRouter, etc.) |
| 16 | +- Need to configure custom API endpoints for Claude Code |
| 17 | +- Ask about setting up API keys for different providers |
| 18 | +- Request help configuring model provider settings |
| 19 | + |
| 20 | +## Setup Workflow |
| 21 | + |
| 22 | +### Step 1: Read Provider Configurations |
| 23 | + |
| 24 | +Read the provider configurations from `references/providers.json` to understand available providers, their base URLs, and supported models. |
| 25 | + |
| 26 | +The JSON structure contains: |
| 27 | +- Provider ID and display name |
| 28 | +- Description of the provider |
| 29 | +- Base URL for API requests |
| 30 | +- List of available models with IDs and descriptions |
| 31 | + |
| 32 | +### Step 2: Present Provider Options to User |
| 33 | + |
| 34 | +Use the `AskUserQuestion` tool to present available providers to the user. Structure the question as follows: |
| 35 | + |
| 36 | +**Question format:** |
| 37 | +- Header: "Provider" |
| 38 | +- Question: "Which model provider would you like to configure?" |
| 39 | +- Options: Build from providers.json, using provider name as label and description as the option description |
| 40 | +- multiSelect: false (single provider selection) |
| 41 | + |
| 42 | +### Step 3: Present Model Options for Selected Provider |
| 43 | + |
| 44 | +After the user selects a provider, use `AskUserQuestion` again to let them choose a model from that provider's available models. |
| 45 | + |
| 46 | +**Question format:** |
| 47 | +- Header: "Model" |
| 48 | +- Question: "Which model would you like to use?" |
| 49 | +- Options: Build from the selected provider's models array, using model name as label and description as the option description |
| 50 | +- multiSelect: false (single model selection) |
| 51 | + |
| 52 | +### Step 4: Collect API Key |
| 53 | + |
| 54 | +Use `AskUserQuestion` to collect the API key for the selected provider. |
| 55 | + |
| 56 | +**Question format:** |
| 57 | +- Header: "API Key" |
| 58 | +- Question: "Please enter your API key for [provider name]:" |
| 59 | +- Options: Provide 2 options: |
| 60 | + - Label: "I'll enter my API key", Description: "Type or paste your API key in the 'Other' field below" |
| 61 | + - Label: "I'll add it manually later", Description: "Set up the configuration with a placeholder that you'll replace later" |
| 62 | +- multiSelect: false |
| 63 | + |
| 64 | +**Important:** If the user selects "Other" and provides a custom text input, that is their API key. If they choose "I'll add it manually later", use the placeholder `"<YOUR_API_KEY_HERE>"`. |
| 65 | + |
| 66 | +### Step 5: Update .claude/settings.local.json |
| 67 | + |
| 68 | +Read the existing `.claude/settings.local.json` file if it exists. If it doesn't exist, create a new one. |
| 69 | + |
| 70 | +Update or create the configuration with the following structure: |
| 71 | + |
| 72 | +```json |
| 73 | +{ |
| 74 | + "env": { |
| 75 | + "ANTHROPIC_BASE_URL": "<selected provider's baseUrl>", |
| 76 | + "ANTHROPIC_MODEL": "<selected model's id>", |
| 77 | + "ANTHROPIC_AUTH_TOKEN": "<user's API key or placeholder>" |
| 78 | + } |
| 79 | +} |
| 80 | +``` |
| 81 | + |
| 82 | +**Important considerations:** |
| 83 | +- Preserve any existing configuration in settings.local.json that is not related to these three env variables |
| 84 | +- Merge the new env variables with existing ones |
| 85 | +- Use proper JSON formatting with 2-space indentation |
| 86 | + |
| 87 | +### Step 6: Confirm Setup |
| 88 | + |
| 89 | +After updating the configuration file, inform the user: |
| 90 | +1. Which provider and model were configured |
| 91 | +2. The location of the settings file: `.claude/settings.local.json` |
| 92 | +3. If a placeholder was used, remind them to replace `<YOUR_API_KEY_HERE>` with their actual API key |
| 93 | +4. Note that they need to restart Claude Code for the changes to take effect |
| 94 | + |
| 95 | +## Adding New Providers |
| 96 | + |
| 97 | +To add new model providers to this skill, edit `references/providers.json` and add a new provider object with the following structure: |
| 98 | + |
| 99 | +```json |
| 100 | +{ |
| 101 | + "id": "unique-provider-id", |
| 102 | + "name": "Display Name", |
| 103 | + "description": "Brief description of the provider", |
| 104 | + "baseUrl": "https://api.example.com/v1", |
| 105 | + "models": [ |
| 106 | + { |
| 107 | + "id": "model-identifier", |
| 108 | + "name": "Model Display Name", |
| 109 | + "description": "Brief description of the model" |
| 110 | + } |
| 111 | + ] |
| 112 | +} |
| 113 | +``` |
| 114 | + |
| 115 | +## Resources |
| 116 | + |
| 117 | +### references/providers.json |
| 118 | + |
| 119 | +Contains the configuration database for all supported model providers. This file includes: |
| 120 | +- Provider metadata (ID, name, description) |
| 121 | +- API base URLs |
| 122 | +- Available models for each provider |
| 123 | + |
| 124 | +This file should be read at the start of the workflow to populate the provider and model selection options. |
0 commit comments