output-dev-model-selection

Picking a Model for an Output SDK Prompt

This skill is the single source of truth for model selection across Output SDK skills and agents. Other skills link here instead of pinning specific model IDs, because model rosters drift faster than docs.

Live model snapshot

We run this at skill-load time to fetch the 10 most recently released models per provider from the Vercel AI Gateway:

output=$(curl -fsS https://ai-gateway.vercel.sh/v1/models 2>/dev/null | jq '
  .data as $models
  | {
      anthropic: ([ $models[] | select(.id | startswith("anthropic/")) ] | sort_by(.released) | reverse | .[0:10]),
      openai:    ([ $models[] | select(.id | startswith("openai/"))    ] | sort_by(.released) | reverse | .[0:10]),
      google:    ([ $models[] | select(.id | startswith("google/"))    ] | sort_by(.released) | reverse | .[0:10])
    }
' 2>/dev/null)
if [ -n "$output" ]; then printf '%s\n' "$output"; else echo "(snapshot unavailable)"; fi

Snapshot Data

output=$(curl -fsS https://ai-gateway.vercel.sh/v1/models 2>/dev/null | jq '
  .data as $models
  | {
      anthropic: ([ $models[] | select(.id | startswith("anthropic/")) ] | sort_by(.released) | reverse | .[0:10]),
      openai:    ([ $models[] | select(.id | startswith("openai/"))    ] | sort_by(.released) | reverse | .[0:10]),
      google:    ([ $models[] | select(.id | startswith("google/"))    ] | sort_by(.released) | reverse | .[0:10])
    }
' 2>/dev/null)
if [ -n "$output" ]; then printf '%s\n' "$output"; else echo "(snapshot unavailable)"; fi

Snapshot Fallback

If the block above is empty, the script didn't execute automatically — likely because part of it (jq, curl, or network access) is missing. Query and filter the snapshot yourself before continuing.

Snapshot shape

{
  "anthropic": [ <model>, ..., <up to 10> ],
  "openai":    [ <model>, ..., <up to 10> ],
  "google":    [ <model>, ..., <up to 10> ]
}

Each <model> is the unmodified gateway payload. Useful fields per model:

Decision flow

Step 1 — Determine task priority

Pick the first row that fits. If unclear, default to reasoning.

Step 2 — Determine provider

Scan existing *.prompt files in the workflow (and its siblings under src/workflows/) and tally what provider: they declare.

• If the workflow (or sibling workflows) already use one provider, match it. Mixing providers means the runtime needs API keys for each — operational footgun.
• If no existing prompts, default to anthropic.
• Only switch provider when the user explicitly asks, or when a feature you need (eg Gemini's useSearchGrounding, OpenAI's maxToolCalls) is provider-specific.

Step 3 — Map provider name to snapshot key

Output SDK provider: values don't always line up with the snapshot keys, since Vercel groups Gemini under google/:

Step 4 — Pick a model from the provider's list

The list is already sorted newest-first. Walk it top-down and pick the first model whose id matches the tier for your priority.

Skip these by default:

• type != "language" (eg gpt-image-2, gemini-embedding-2) — not valid for .prompt files.
• IDs containing preview, alpha, or beta. Use stable / GA models only, even if a newer preview/alpha/beta exists. Only pick a non-stable model when the user explicitly asks for it ("use the preview", "I want the new beta", etc.).

Tie-breakers when multiple stable models match:

• Prefer the unversioned alias (claude-sonnet-4.6) over a dated snapshot (claude-sonnet-4-20250514) unless reproducibility is required (eg eval judges).
• If two truly equivalent rows exist, take the one with the larger context_window, then lower pricing.input.

If every match in the snapshot is a preview/alpha/beta — meaning the entire tier is in pre-release — surface that to the user and ask before picking one. Don't silently use a preview because it was the only thing available.

Step 5 — Translate the gateway ID into a prompt-file model string

Gateway IDs carry a provider prefix and use dots; prompt-file IDs strip the prefix and use hyphens. Apply two transformations: drop everything up to and including the first /, then replace . with -.

Drop the translated string into your .prompt frontmatter:

---
provider: anthropic
model: claude-sonnet-4-6
temperature: 0.7
maxTokens: 4096
---

See also

• output-dev-prompt-file — overall .prompt file structure
• output-dev-upgrade-prompt-models — bulk-upgrade existing prompts to the latest version of their current family
• output-eval-judge-prompt — judge-specific selection guidance (start small, escalate on TPR/TNR failures)