Unique-AG/ai / .claude/skills/model-deployment
model-deployment
VerifiedDeploy a new LLM model via LiteLLM (GitOps) and/or Azure (Terraform + node backend), add it to the ai toolkit, create the required pull requests, and verify end-to-end. Use when rolling out a model to any environment, adding a model to the toolkit, troubleshooting "model not available" errors, or finding pricing/token limits/model ids for any provider.
Model deployment (LLM — any provider)
This skill guides the full lifecycle of deploying a new LLM model across the Unique platform:
- monorepo — LiteLLM proxy config (GitOps), node-chat backend (Azure track), Terraform
- ai repo — toolkit language model registry (
LanguageModelInfo)
Cardinal rule: never guess token limits, capabilities, pricing, provider strings, or Azure sku_capacity. Always cite the source (model card URL, LiteLLM registry, live Azure quota, Jira ticket, or PR). If no authoritative source exists, ask the user.
When to use this skill
- Deploying a new model to Dev, QA, UAT, or Prod (any provider).
- Adding a model to the LiteLLM proxy and/or Azure OpenAI.
- Adding a model to the ai toolkit language model registry.
- Troubleshooting "model not available on cluster" or config-sync issues.
- Finding pricing, token window sizes, or model identifiers for any provider.
Step 0 — Gather information before touching any file
| Question | Why |
|---|---|
Track: azure, litellm, or both | Determines which repos/files to touch |
| Environments and rollout order (e.g. qa → uat01 → prod) | Controls which overlay files are edited and in what sequence |
Model identifiers — For LiteLLM: user-facing model_name + provider model string. For Azure: model name, version, deployment names, API version, capacity | Required for config entries |
| Token limits / capabilities — with a cited source | Required for toolkit LanguageModelInfo |
| Toolkit: already merged / has open PR / needs to be done now? | Avoids duplicate work |
| Allowlist / exposure constraints | Determines selectability — see MODEL-SELECTABILITY.md |
Where to find model facts
| Fact | Where to look |
|---|---|
| Azure model deployments | Azure AI Foundry — Deployments page (single source of truth for Azure) |
| Token window | Vendor model card: OpenAI, Anthropic, Google, LiteLLM registry |
| Pricing | Azure AI Foundry Quota page, OpenAI, Anthropic, Google Cloud |
| Model identifiers / provider prefix | LiteLLM model registry |
| API version (Azure) | Azure AI Foundry Deployments page or Azure REST API changelog |
| Capabilities | Vendor model cards, release blog posts, changelogs |
Repo and file map
| Repo | What you touch |
|---|---|
| monorepo | LiteLLM overlay: gitops-resources/argocd/clusters/<cluster>/<env>/value-overlays/litellm.yaml. Node-chat: language-model enum + Azure factory config. Terraform: azurerm_cognitive_deployment, Key Vault secret. |
| ai repo | Toolkit: LanguageModelName enum + LanguageModelInfo.from_name() case + tests in unique_toolkit/unique_toolkit/language_model/infos.py. |
gitops-resources/argocd/clusters/
├── unique/ # multi-tenant: qa/, uat01/, prod/, us01/
├── <single-tenant>/ # e.g. tree, burger, cat, ...
Track A — LiteLLM (GitOps)
A1) Validate model id and provider prefix
- Search LiteLLM model registry for the model.
- Document the two strings: user-facing key (
model_name, no prefix, hyphens) and provider model (litellm_params.model, with prefix).
See LITELLM-CONFIG.md for config examples and provider prefix conventions.
A2) Update ArgoCD overlay(s)
Edit monorepo/gitops-resources/argocd/clusters/<cluster>/<env>/value-overlays/litellm.yaml. Add a new entry under proxy_config.model_list, following the existing alphabetical grouping style.
A3) Monorepo PR
- Branch:
feat/litellm-<model-name> - Commit:
feat(litellm): add <model_name> model to <envs> - Commit, push, and create the PR after validation. Include the env overlays changed, model names, source links, and verification steps in the PR body.
A4) After merge — sync + restart
- In ArgoCD, sync the LiteLLM application for the target environment.
- Roll the LiteLLM Deployment (not HPA — restarting HPA does not reload pods).
A5) Verify
- Confirm model appears in LiteLLM dashboard.
- Smoke test with the exact model id users will request (e.g.
litellm:<model_name>).
Track B — Azure (Terraform + node backend)
B1) Gather Azure deployment details
Check Azure AI Foundry first — the Deployments page lists all active model deployments with name, version, capacity, rate limits, and retirement dates.
Confirm: Azure OpenAI account, model name + version, deployment names, API version.
Capacity is per subscription, region, and SKU. Do not copy one sku_capacity onto every tenant. A platform request (for example Global Standard 15000 and Data Zone Standard 5000) is only the ceiling you ask for. The value written in oai-models.yaml is the minimum of that request and the live quota for that tenant. See AZURE-NODE-CHAT.md.
B2) Terraform changes
Add azurerm_cognitive_deployment resource(s) in the infrastructure repo. See AZURE-NODE-CHAT.md for Terraform patterns.
B3) Node backend registration
Three files in next/services/node-chat/src/openai/: language-model.enum.ts, azure-sdk-openai.service.factory.ts, azure-sdk-openai.service.ts. See AZURE-NODE-CHAT.md for code examples.
B4) PR + apply workflow
- Create PR; link to Jira ticket and source docs.
- Review Terraform plan — stop if unexpected drift appears.
- Apply via Atlantis, one workspace at a time.
B5) Verify
- Confirm deployments exist in Azure AI Foundry.
- Roll the node-chat Deployment (not HPA).
- Smoke test both plain chat (node-chat) and agentic assistant space (assistants-core) — bugs can hide in one path. See LESSONS-LEARNED.md for why.
Model selectability
Two layers control whether a model is available and user-selectable. See MODEL-SELECTABILITY.md for full details.
Quick decision matrix:
| Want the model to... | UNIQUEAI_SUPPORTED_MODELS | UNIQUEAI_ALLOWED_MODELS |
|---|---|---|
| Be available and selectable by users | Add | Add |
| Be available but only for internal use | Add | Do not add |
| Not be available at all | Do not add | N/A |
Track C — AI toolkit
C1) Check existing state
Check whether the model already exists in unique_toolkit/unique_toolkit/language_model/infos.py (merged, open PR, or needs to be added).
C2) Add model to toolkit
Add LanguageModelName enum entry and LanguageModelInfo.from_name() case. See TOOLKIT-REGISTRY.md for code examples and field reference.
Critical: for default_options, use the string "none" — never Python None. See LESSONS-LEARNED.md.
C3) PR + release
- Branch:
feat/toolkit-<model-slug> - Commit:
feat(toolkit): add <model_name> model info - Commit, push, and create the PR after validation. Include the exact model identifier, cited model specifications, and tests run in the PR body.
- Merge with a conventional commit (
feat(toolkit): add <model_name> model info). release-please updatesunique_toolkitversion andCHANGELOG.mdon the standing Release PR — do not edit those files in the feature PR.
For early exposure before the toolkit release, use the LANGUAGE_MODEL_INFOS env override — see TOOLKIT-REGISTRY.md.
Multi-cluster rollouts
- One monorepo PR touching multiple cluster overlays.
- After merge, rollout per cluster: ArgoCD sync → roll Deployment → verify + smoke test.
- Repeat in the agreed rollout order.
Pull request completion
When implementing a model deployment, finish each repository's code changes by:
- Running the relevant formatter, linter, and targeted tests.
- Committing with the track's conventional commit message.
- Pushing the branch and creating a non-draft PR.
- Linking the Jira ticket and authoritative model sources in the PR body.
- Returning every created PR URL to the user.
Create separate PRs for separate repositories. A direct request to run this skill and implement the deployment authorizes creating the required PRs; stop before PR creation only when the user asks for local changes, a draft, or a plan.
Final checklist (every track)
- Required PRs created and URLs returned
- Correct environment(s) targeted and rollout order followed (qa → uat → prod)
- Config synced in ArgoCD where applicable
- Correct Deployment rolled (not HPA)
- Smoke test succeeded using the exact model id users will request
- Sources cited for token limits, capabilities, and model identifiers
- Model selectability decided: added to
UNIQUEAI_SUPPORTED_MODELS(cluster-available) and, if user-facing, toUNIQUEAI_ALLOWED_MODELSenv var - Rollout notes captured (Jira comment + links + timestamps)
Rollback and safety
- Explicit approvals required before editing committed code, suggesting Atlantis apply, or anything affecting production.
- If Terraform drift or "model not discoverable" looks wrong: stop, explain what you see, propose the smallest safe next action.
- For incident patterns and past mistakes, see LESSONS-LEARNED.md.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |