Add LLM Model
Developmentadd-llm-modelAdd LLM Model is an Agent Skill for development published in the stagewise-io/stagewise repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when adding a new LLM/model to stagewise model catalogs, provider routing, validation, docs, or showcase UI.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/stagewise-io/stagewise/blob/HEAD/.agents/skills/add-llm-model/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/add-llm-model, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Add LLM Model
Use this workflow when adding or updating model support in stagewise.
Required Checks
-
Inspect existing provider entries before editing.
- Read
apps/browser/src/shared/available-models.tsaround the provider. - Keep still-supported sibling models. Do not replace old models with the new one unless explicitly requested.
- Read
-
Wire the model through all relevant product surfaces.
- Model catalog:
apps/browser/src/shared/available-models.ts. - Provider routing:
apps/browser/src/backend/agents/model-provider.ts. - API-key validation:
apps/browser/src/backend/utils/validate-api-keys.ts. - Coding plans:
apps/browser/src/shared/coding-plans.ts. - Website showcase:
apps/website/src/app/(home)/_components/model-provider-showcase.tsx. - README files and localized README variants.
- Model catalog:
-
Keep plan docs aligned with plan config.
- If
featuredModelIdslists multiple models, README subscription tables must list the same featured lineup in readable display names. - The later full model lists may include more models, but must not contradict the plan table.
- If
-
Preserve showcase truthfulness.
- If the homepage showcase is curated, make that intentional.
- Otherwise include still-supported sibling models so marketing does not understate provider support.
-
Handle provider-native IDs everywhere requests can route.
- Internal model IDs may differ from native provider IDs.
- Apply native ID mapping in official provider mode.
- Apply the same default native ID mapping for built-in models routed through custom endpoints.
- Explicit
customEndpoint.modelIdMappingmust always override default mapping.
-
Validate API keys with broadly accessible probes.
- Do not validate a provider exclusively against the newest or highest-tier model if older supported models remain available.
- Prefer a cheap broadly available model, or fallback probes that accept success from any supported entitlement.
- Keep validation errors compatible with existing
{ success: false; error: string }callers.
-
Always verify subscription-plan base URLs.
- Many providers use different API endpoints for subscription/token-plan keys vs. pay-as-you-go (BYOK) keys.
- Example: GLM uses
https://api.z.ai/api/paas/v4for BYOK buthttps://api.z.ai/api/coding/paas/v4for coding-plan subscriptions. Xiaomi MiMo useshttps://api.xiaomimimo.com/v1for BYOK buthttps://token-plan-cn.xiaomimimo.com/v1for token-plan subscriptions. - The two key types are often non-interchangeable — a subscription key will be rejected by the BYOK endpoint and vice versa.
- Before finalizing a coding-plan entry, always check the provider's official documentation to confirm:
- Whether subscription tokens require a separate
baseUrl/validationBaseUrl. - The correct cluster or region-specific URL (some providers offer multiple regional endpoints for subscriptions).
- The API key format prefix (e.g.
tp-for MiMo token plan vssk-for BYOK).
- Whether subscription tokens require a separate
- Set
baseUrl,validationBaseUrl,validationModelId,apiKeyPattern, andendpointHelpTexton the coding-plan entry accordingly. - If the provider exposes documentation via
llms.txt, fetch it — it links to raw markdown doc pages that contain the authoritative endpoint and auth details. - Update
apiKeyUrlandhelpTextto point to the subscription management page (not the BYOK API keys page) when the two are separate.
Validation
After changes:
- Run targeted LSP/lint diagnostics on edited files.
- Search for the new model ID and display name across code/docs.
- Confirm request routing uses native provider IDs in official and built-in custom endpoint modes.
- Confirm docs, coding-plan
featuredModelIds, and showcase entries are intentionally aligned.