ai-provider-routing
Use whenever a product calls Gemini, DeepSeek, or other LLM APIs; design a Gemini-free-first, project-aware, secure provider router with health tracking, bounded retries, circuit breakers, cache-frien
SKILL.md.agents/skills/ai-provider-routing/SKILL.md
GitHubAI Provider Routing
Read docs/GEMINI_FREE_FIRST.md and .ai/AI_PROVIDER_POLICY.json.
- Put provider calls behind a server-side adapter/router. Never expose raw keys to the browser.
- Prefer Gemini free tier only when privacy policy and required capability allow it.
- Group Gemini credentials by project quota scope. Multiple keys in the same project share rate limits and must not be treated as independent capacity.
- Select the least-loaded healthy quota group/model, not naive key round-robin.
- Classify failures:
- 401 → bad credential, quarantine;
- 403 → permission/policy, quarantine and investigate;
- 404 → model/resource drift, refresh capabilities;
- 429 short rate limit → project/model cooldown;
- 429 daily quota → mark quota group exhausted until reset;
- 5xx/timeout → bounded backoff, circuit breaker, compatible fallback.
- Respect
Retry-After, add jitter, cap total attempts, and avoid duplicate SDK+gateway retry layers. - Discover/configure current model capabilities rather than freezing stale names.
- Fallback only when modality/tools/schema contract can be preserved. DeepSeek is a useful low-cost text/code/reasoning fallback when configured; it is not a substitute for unsupported image/audio/video requirements.
- Prefer stable common prompt prefixes and track cache-hit telemetry where providers expose it.
- Log provider/model/quota-group/latency/status/usage, not raw keys/prompts by default.
- Never rotate projects/keys to evade provider quotas or terms.
- Pair this Skill with
ai-integration-verification.