Workos

WorkOS Skill Router

How to Use

This file is a router, NOT the answer. Before responding to the user:

1. Match the request to a reference file using Rule 0 and the decision tree below.
2. You MUST Read the matched reference file with the Read tool before producing any answer, URL, or code. If you have not Read a reference, you have not followed this skill.
3. Follow the instructions inside the reference (it will tell you which live docs to fetch with WebFetch and which gotchas to avoid).

Exception: Widget requests use the workos-widgets skill via the Skill tool — it has its own multi-framework orchestration.

Guardrails (apply to every response)

These apply regardless of which routing rule fires. They exist because the most common failure mode of past WorkOS agent interactions has been plausibly-shaped fabrication of CLI commands and Dashboard paths.

• Check for the WorkOS MCP server before reaching for the CLI on workspace-management tasks. If the session has WorkOS MCP tools connected (a server exposing whoami, list_operations, query, and mutate — tool names may carry a client-specific prefix), prefer those tools for reading and changing workspace resources: they already run as the signed-in dashboard user, with no CLI install and no API key. The CLI remains the right surface for bootstrap, seeding, local project config, and diagnostics. The full decision guide is the "Choosing a surface" section of references/workos-management.md.
• Recover a broken WorkOS MCP connection before relying on it — but never treat MCP setup as a prerequisite for CLI work. When the user asks to set up the WorkOS MCP server, or expects MCP tools that turn out to be missing, unauthenticated, or interrupted during startup, read references/workos-mcp.md first: identify the MCP client and requested configuration scope, and do not modify user-global agent configuration without explicit intent. Authentication that depends on a browser, credential store, or host certificates must be completed in the user's normal host shell. If no MCP server is configured and the user hasn't asked for one, do not divert the request into MCP setup — the CLI path in references/workos-management.md fully supports it.
• Never invent workos CLI commands. If the user asks about CLI support or you're about to suggest a command, verify the command tree first. The authoritative source is WORKOS_MODE=agent workos --help --json — it emits the complete registered command tree. Do not assume a create subcommand exists because list/get/delete do. See references/workos-management.md.
• Prefer WORKOS_MODE=agent when invoking the workos CLI from a coding-agent session. The CLI auto-detects most agent environments (CLAUDECODE, CLAUDE_CODE, CURSOR_AGENT, CODEX_SANDBOX, non-TTY), but the explicit env var is more reliable across sandbox configurations. See the WorkOS CLI in Coding-Agent Sessions section below.
• Never invent Dashboard click-paths. Phrases like "Dashboard > Organizations > X > Roles > Map Groups" or dashboard.workos.com/some/specific/path should not appear unless you have verified them against a docs page you just fetched. The Dashboard UI reorganizes; docs pages are stable. Cite the docs URL and describe the destination conceptually ("the Authorization page", "the directory's settings") instead of committing to a click-path.
• When the user wants to do something not supported by the CLI, say so plainly. Users are better served by "this isn't in the CLI; here's the docs URL for how to do it" than by a fabricated command that fails. See the "Not in the CLI" section of references/workos-management.md.
• Prefer docs URLs over prose when writing recipes. If a reference file tells you to cite a specific docs URL, cite it literally; don't paraphrase the URL's slug.

WorkOS CLI in Coding-Agent Sessions

The CLI resolves two independent axes: interaction mode (human/agent/ci) and output mode (human/json). The CLI auto-detects agent environments via known env vars (CLAUDECODE, CLAUDE_CODE, CURSOR_AGENT, CODEX_SANDBOX, CURSOR_TRACE_ID) and non-TTY detection, but explicit settings are more reliable across sandbox configurations.

Recommended preflight for any setup or debugging task:

WORKOS_MODE=agent workos doctor --json --skip-ai

--skip-ai disables the doctor's AI-powered diagnosis pass, which requires an API key and network round-trip — neither is guaranteed in a sandbox. If --skip-ai errors as an unknown flag, the CLI is outdated — see references/workos-cli-upgrade.md. The structured JSON output is sufficient for programmatic triage.

This returns a structured JSON report with interactionMode ({ mode, source }) and hostExecution ({ ok, failures[] }) fields. Read the JSON before suggesting fixes.

Rules:

• Use --json when parsing command output. It controls formatting only — it does not change CLI behavior.
• Use WORKOS_MODE=agent even when relaying human-readable messages. It controls prompts, browser launch, and host trust.
• Treat the doctor HOST_EXECUTION_UNTRUSTED issue as a hard trust boundary. If the doctor report contains this issue (or hostExecution.ok is false), the current shell may be sandboxed. Auth, config, keychain, and API failures from this shell are not authoritative. Ask the user to re-run host-sensitive commands (workos auth login, workos doctor, workos env add) on their host shell before drawing conclusions.
• Do not assume browser-based auth (workos auth login) works in a sandbox. If auth is required, surface the manual URL/code fallback that the CLI prints, or ask the user to run workos auth login on their host shell.
• For destructive CLI commands in agent mode, pass the explicit confirmation flag. Agent mode never prompts, so omitting the flag causes a confirmation_required error. Known flags: --yes for workos api (mutating methods), --force for workos connection delete, workos directory delete, and workos debug reset. If unsure which flag a command expects, run workos <cmd> --help --json to check.
• Structured CLI errors (JSON on stderr) include an optional error.recovery.hints array, where each hint has description, optional command, and optional hostShellRequired. Prefer those hints over guessing the next step.

Legacy compatibility you may encounter:

• WORKOS_NO_PROMPT=1 is a legacy alias that sets both agent interaction behavior AND JSON output. To migrate, set WORKOS_MODE=agent and pass --json to the command to preserve both behaviors. Using WORKOS_MODE=agent alone drops the implicit JSON formatting.
• WORKOS_FORCE_TTY=1 only affects output formatting; it does not change interaction mode.

Topic → Reference Map

Terminology lookups — "what is X", "docs URL for X" — are handled by Rule 0 below, not this topic map. They route to references/workos-terms.md.

AuthKit Installation (Read references/{name}.md)

Backend SDK Installation (Read references/{name}.md)

Features (Read references/{name}.md)

API References (Read references/{name}.md)

Feature topic files above include endpoint tables for their respective APIs. Use these API-only references when no feature topic exists:

Migrations (Read references/{name}.md)

Management & CLI Lifecycle (Read references/{name}.md)

Routing Decision Tree

Apply these rules in order. First match wins.

0. Terminology / Docs URL Lookup

Triggers: Lookup-shaped phrasing — "what is X", "what does X mean", "docs URL for X", "where's the docs on X", "canonical link for X", "where do I configure X in the dashboard" — where X is a WorkOS-specific config field, endpoint, env var, or term. Examples: initiate_login_uri, "Sign-in endpoint", "Redirect URI", dashboard field names, WORKOS_* environment variables.

Do NOT fire Rule 0 for setup-shaped phrasing like "set up Vault", "enable Admin Portal", "configure MFA" — those route to Rule 3 (Feature-Specific).

Action:

1. Read references/workos-terms.md — a curated table mapping WorkOS terms to canonical docs URLs.
2. If the term is in the table, use the summary to answer; WebFetch the listed URL only if the user wants more detail.
3. If the term is NOT in the table, follow the "Still not here?" fallback at the bottom of that file. When you find the canonical URL, answer the user and suggest they open a PR to add a row.

For terminology lookups, do NOT WebFetch llms.txt or guess workos.com/docs/... URLs before reading the terms file. (Rules 8 and 9 use llms.txt for different purposes — this prohibition is scoped to Rule 0 only.)

Why this wins: Terminology lookups happen independent of feature/framework/migration context. They need to short-circuit routing, not fall through to "Vague or General" (Rule 8).

1. Migration Context

Triggers: User mentions migrating FROM another provider (Auth0, Clerk, Cognito, Firebase, Supabase, Stytch, Descope, Better Auth, standalone SSO API).

Action: Read references/workos-migrate-[provider].md where [provider] matches the source system. If provider is not in the table, read references/workos-migrate-other-services.md.

Why this wins: Migration context overrides feature-specific routing because users need provider-specific data export and transformation steps.

2. API Reference Request

Triggers: User explicitly asks about "API endpoints", "request format", "response schema", "API reference", or mentions inspecting HTTP details.

Action: For features with topic files (SSO, Directory Sync, RBAC, Vault, Events, Audit Logs, Admin Portal), read the feature topic file — it includes an endpoint table. For AuthKit or Organization APIs, read references/workos-api-[domain].md.

Why this wins: API references are low-level; feature topics are high-level but include endpoint tables for quick reference.