OmniRoute Authentication Skill

We read the file at commit 93265ee of diegosouzapw/OmniRoute. This skill is not distributed through skills.sh, so there is no registry copy to compare against; every quote below comes from the repository's own bytes at that commit, verified on 2026-09-02. The listing you are on renders the full file above this section, so the stale capability table discussed in section 6 is reproduced there verbatim; the quotes here add the pinned commit and line anchors the file panel does not carry.

omni-auth at a glance

1. The file announces it is machine-generated, and that manual edits will be overwritten.
2. It documents two different logins in one file: a Bearer key for the API, a password cookie for the dashboard.
3. The OIDC callback is the most carefully specified thing here, down to the JWKS check, the subject allowlist and the 30-day session JWT.
4. Setup is two environment variables and a health check, and it is agent-agnostic.
5. The back half is an older document preserved inside the file, and its provider count trails the repo's own README.
6. Its capability index links 17 sibling skills, and 16 of the links are dead. The catalog moved; the preserved block did not.
7. The errors table maps each status code to one action, which is the behavior change an agent keeps.

1. The file announces it is machine-generated

Most agent skills read like prose someone wrote for a model. The first thing after omni-auth's frontmatter is a notice that nobody wrote this part at all.

<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->

Source: SKILL.md, header comment

OmniRoute generates its skill files from the application's own API surface, the way OpenAPI docs are generated from route definitions. The file runs 7,168 bytes over 150 lines at this commit, small for a start-here skill because it defers request and response schemas to the gateway's OpenAPI spec. That is a real trade. The upside is that the endpoints quoted below cannot drift from the running server the way hand-written docs do. The downside shows up in section 5: the parts the generator does not regenerate are the parts that have gone stale.

2. Two different logins share one file

The whole point of the skill fits in two sentences, and they draw a boundary an agent needs to respect: the credential you hold decides which door you can open.

Remote API requests use a Bearer credential. Dashboard login is different: POST /api/auth/login accepts a management password and returns an auth_token session cookie.

Source: SKILL.md, "Authentication"

For a coding agent the Bearer path is the one that matters: every model call goes to /v1/... with an API key from the dashboard. The password login exists for the management UI, and the file walks through its lifecycle with curl examples against https://localhost:20128, including a logout that requires fetching a CSRF token first. Note the small inconsistency: the examples use https:// while the file's own setup line declares the default as http://localhost:20128. An agent that mixes the two credentials up gets a clean 401, which section 7 tells it how to read.

3. The OIDC callback is the most specified thing in the file

For a generated file, the single-sign-on section is unusually explicit about its checks. This paragraph is where the security posture of the dashboard actually lives.

Validates the state cookie, exchanges the authorization code for tokens, verifies the ID token against the issuer's JWKS (audience = client id), and — if oidcAllowedSubjects is configured — checks the token's sub/email against that allowlist. On success it mints the same 30-day auth_token dashboard-session JWT used by password login and redirects to /dashboard.

Source: SKILL.md, "GET /api/auth/oidc/callback"

The caveats sit in the same lines: a 30-day session token is a long-lived credential, the allowlist only applies when someone configures it, and password login stays available as a fallback while OIDC is on. None of that is unusual for a self-hosted dashboard; it is rare to see it spelled out inside a skill file where the agent, and you, can read it.

4. Setup is two environment variables and a health check

The preserved overview opens with the entire integration surface. The file has no per-agent sections at all, because nothing agent-specific exists to configure: any tool that can send OpenAI-style requests points at the same base URL.

All requests: ${OMNIROUTE_URL}/v1/... with Authorization: Bearer ${OMNIROUTE_KEY}. [...] Verify: curl $OMNIROUTE_URL/api/health → {"ok":true}

Source: SKILL.md, "Setup"

The two variables above that line are OMNIROUTE_URL (the local or tunnel address of your gateway) and OMNIROUTE_KEY (minted in the dashboard under API Keys). That is the answer to the setup question people are searching this week: install the gateway, export the two variables, hit /api/health, and your agent's OpenAI-compatible traffic routes through it. Running the server itself is the sibling skill's job, and we cover it on the OmniRoute CLI Serve listing.

5. The back half is an older document, preserved on purpose

At line 76 the generated file ends and a different one begins, fenced by comments that say exactly what happened.

<!-- Migrated from skills/omniroute/SKILL.md (preserved curated content) --> [...] Local/remote AI gateway exposing OpenAI-compatible REST. One key, 327 providers, auto-fallback, RTK token saver, MCP server, A2A agents.

Source: SKILL.md, preserved-content marker

The preservation is deliberate, and the label is honest. But the numbers inside the preserved block have aged: it says 327 providers, while the repository's README at the same commit says "352 providers" in four places. In fairness, the stale count is not unique to this block: the repo's own skills/README.md still describes a "327-provider catalog" in one row too. Neither figure is ours to adjudicate; what the disagreement proves is that content outside the generator's reach trails the product. Anything you read below that comment deserves a date check, which is exactly what the next section is about.

6. Sixteen of its seventeen capability links are dead

The preserved block ends with the skill's most useful-looking artifact: two tables linking every capability of the gateway to a sibling skill by raw URL, chat, images, TTS, embeddings, routing, compression, the MCP server, the CLI family.

| Chat / code-gen | https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute-chat/SKILL.md |

Source: SKILL.md, "Capability skills"

We fetched all 17 linked URLs on 2026-09-02. Sixteen return 404, and no omniroute-* skill directory exists at the pinned commit either. The only link that resolves is omni-mcp, the only entry whose name matches the current catalog, which uses omni-* and cli-* names. The repo holds 46 SKILL.md files on disk at this commit, and its own skills/README.md indexes 45 of them (the 46th, ponytail, mirrors an external skill and goes unlisted). The defense is printed in the file itself: this block is migrated legacy content, and the generator's notice says manual edits get overwritten, so fixing the table by hand would not stick. Still, the practical consequence lands on the agent: an assistant that follows the start-here skill's own index to load a capability will fetch sixteen 404 pages, while the working index sits one directory up.

7. The errors table maps each status code to one action

The file closes its practical half with four bullets, and this is the section that changes agent behavior most per byte.

• 401 → set/refresh OMNIROUTE_KEY (Dashboard → API Keys)
• 400 Invalid model format → check model exists in /v1/models/<kind>
• 503 Provider circuit open → upstream provider down; retry after Retry-After seconds
• 429 → rate limited; honor Retry-After

Source: SKILL.md, "Errors"

Each line pairs a failure with the one recovery that works, which is what keeps an agent from retry-hammering a provider whose circuit breaker is open. The differentiators list under it makes bigger claims, including that this is the only AI router exposing both MCP and A2A protocols. That is the author's claim at this commit; we did not survey the router market to check it, and a superlative in a preserved block that already carries one stale count has earned a date check before you repeat it.

What changes when an agent loads it

Tools it drives: none that it can run. The file is reference material: curl examples, two environment variables, endpoint contracts. It ships no script and imports nothing. What it changes is whether the agent holds the correct auth model for the gateway before its first request, and what it does after the first 401.

The gateway this skill fronts has real momentum behind it: the repository holds 60,436 GitHub stars as of September 3, 2026, and "omniroute" queries around Claude Code setup are among the fastest-rising skill searches in Google Trends this month (worldwide, past 30 days, captured 2026-09-02). The security census found 87.8% of the 79,848 listings in our catalog have never had a security audit; a gateway that sees every prompt deserves the paragraph of scrutiny above before it earns a place in your stack.