name: vercel-ai-gateway-setup
description: Set up Claude Code to route requests through Vercel AI Gateway for monitoring and observability
compatibility: Designed for Claude Code

Vercel AI Gateway Setup Skill

Description

This skill sets up Claude Code to route requests through Vercel AI Gateway for monitoring and observability. It supports two modes: API Key mode (using a Vercel AI Gateway API key) and Claude Max mode (using an existing Claude Code Max subscription through the gateway).

Instructions

When the user invokes this skill, guide them through the Vercel AI Gateway setup interactively. Never ask for or handle API keys directly. The user must enter their own keys. Never read the user's shell config file (~/.zshrc, ~/.bashrc, ~/.bash_profile, ~/.profile, etc.) during setup — it may already contain secrets. Only append to it.

Step 1: Check prerequisites

Run the following to confirm Claude Code CLI is installed:

command -v claude

If not found, tell the user to install it with npm install -g @anthropic-ai/claude-code.

Step 2: Ask the user which mode they want

Present two options:

1. API Key mode — Uses a Vercel AI Gateway API key for all requests. The user provides their own API key in their shell config.
2. Claude Max mode — Uses the user's existing Claude Code Max subscription, routing through the gateway for observability only.

Step 3: Ask about macOS Keychain (macOS only)

If the platform is macOS (darwin), ask if they want to store the key in macOS Keychain for extra security.

Step 4: Run the setup script

Execute the setup script using named arguments based on the user's choices from Steps 2 and 3. Always use named arguments — never run the script without them.

Available arguments:
- --mode apikey or --mode max — the setup mode chosen by the user
- --keychain or --no-keychain — whether to use macOS Keychain (macOS only)
- --confirm — auto-confirm appending config to the shell profile
- --logout or --no-logout — whether to log out of Claude Code (API key mode)

Examples:

# API Key mode with Keychain
bash scripts/setup-vercel-ai-gateway.sh --mode apikey --keychain --confirm --logout

# Claude Max mode without Keychain
bash scripts/setup-vercel-ai-gateway.sh --mode max --no-keychain --confirm

The script will:
- Detect the user's shell config file (~/.zshrc, ~/.bashrc, etc.)
- Generate the appropriate environment variable block
- Show the user what will be added
- Append it to their shell config
- Optionally log out of Claude Code (for API key mode)

Step 5: Remind the user of manual steps

After the script completes, remind the user they need to:

1. Replace the placeholder <YOUR_AI_GATEWAY_API_KEY> in their shell config with their actual key (or store it in Keychain if they chose that option). Claude Code must never see or handle the actual API key.
2. Reload their shell: source ~/.zshrc (or their shell config)
3. Start Claude Code: claude

Environment variables reference

API Key mode:

ANTHROPIC_BASE_URL="https://ai-gateway.vercel.sh"
ANTHROPIC_AUTH_TOKEN="<key>"
ANTHROPIC_API_KEY=""           # must be empty so AUTH_TOKEN is used

Claude Max mode:

ANTHROPIC_BASE_URL="https://ai-gateway.vercel.sh"
ANTHROPIC_CUSTOM_HEADERS="x-ai-gateway-api-key: Bearer <key>"

macOS Keychain storage:

security add-generic-password -a "$USER" -s "ANTHROPIC_AUTH_TOKEN" -w "<key>"

macOS Keychain retrieval (used in shell config):

export ANTHROPIC_AUTH_TOKEN=$(security find-generic-password -a "$USER" -s "ANTHROPIC_AUTH_TOKEN" -w)

Important security notes

• Never ask the user to paste their API key into the chat or any tool call.
• Never read, echo, or log the value of ANTHROPIC_AUTH_TOKEN or any API key variable.
• Never read the user's shell config file (e.g. ~/.zshrc) — it may contain existing secrets. Only append new config blocks to it.
• The script uses <YOUR_AI_GATEWAY_API_KEY> as a placeholder. The user replaces it manually.
• If using Keychain, the user runs the security add-generic-password command themselves in their terminal.