About workos
WorkOS Skill Router guides coding agents through WorkOS and AuthKit setup and related tasks. It routes requests to task-specific references and provides an installer path and guardrails for CLI and workspace operations.
Key features
- 01Guide initial AuthKit installation
- 02Route tasks to reference material
- 03Set rules for WorkOS CLI use
- 04Explain environment claiming
- 05Distinguish MCP and CLI use
Use cases
- 01Set up AuthKit in a project without WorkOS credentials
- 02Troubleshoot WorkOS CLI setup or diagnostics
- 03Choose MCP or CLI for workspace resources
MCP support
For workspace management, it prefers a connected WorkOS MCP server to read and change resources; the CLI is used for bootstrap, local configuration, and diagnostics. MCP setup and recovery follow client- and scope-specific guidance.
Install
Copy the command and run it in a terminal.
npx skills add https:/ / github.com/ workos/ skills --skill workosAfter installing, type/workosin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
evals/evals.jsonreferences/workos-admin-portal.mdworkos-api-authkit.mdworkos-api-organization.mdworkos-audit-logs.mdworkos-authkit-base.mdworkos-authkit-nextjs.mdworkos-authkit-react-router.mdworkos-authkit-react.mdworkos-authkit-setup.mdworkos-authkit-sveltekit.mdworkos-authkit-tanstack-start.mdworkos-authkit-vanilla-js.mdworkos-cli-upgrade.mdworkos-custom-domains.mdworkos-directory-sync.mdworkos-dotnet.mdworkos-elixir.mdworkos-email.mdworkos-events.mdworkos-feature-flags.mdworkos-fga.mdworkos-go.mdworkos-integrations.mdworkos-kotlin.mdworkos-management.mdworkos-mcp.mdworkos-mfa.mdworkos-migrate-auth0.mdworkos-migrate-aws-cognito.mdDetails
From the project READMEWorkOS Skill Router
Start here: set up AuthKit with no account
When the user wants to add WorkOS or AuthKit sign-in to a project that has no WorkOS credentials yet, run the installer first:
WORKOS_MODE=agent npx workos@latest install
It doesn't need a WorkOS account, an API key, or a dashboard visit.
Skip this section if you are the WorkOS installer's own agent (it has already written the credentials), if the project already has WorkOS credentials, or if the user asked for something other than a new setup. Go to How to Use instead.
What it does. This describes workos CLI 0.23.0, the latest release when this was written. Treat the CLI's output as authoritative over this list.
- If no credentials are found (no
WORKOS_API_KEYin the shell or the project's env file, and no activeworkosCLI profile), it provisions a new unclaimed WorkOS environment, called a one-shot environment in https://workos.com/auth.md. If it finds credentials, it uses them and creates nothing. - It writes
WORKOS_API_KEY,WORKOS_CLIENT_IDandWORKOS_CLAIM_TOKENto.env.localwhen the project has apackage.json, or to.envotherwise, and adds that file to.gitignore. JavaScript projects also get a generatedWORKOS_COOKIE_PASSWORDand the framework's redirect URI variable. Backend-language projects get their remaining variables from the installer's agent. - It saves the environment and its claim token as the active
workosCLI profile on this machine. The claim token exists only there and in the env file. Don't delete either before the environment is claimed. - It wires the AuthKit SDK and registers the callback URL with the environment (the install fails if it can't), then reports which other application URLs (Sign-out URI, Initiate login URI, CORS origin) it saved or left for you. It runs post-install validation unless you pass
--no-validate. - It sets up AuthKit sign-in only. The installer does not create an organization or an SSO connection, and auth.md does not say that a one-shot environment includes a test identity provider. Don't promise a ready-made SSO login. If the user wants to try SSO, read
references/workos-sso.mdnext. - Git: in agent mode, 0.23.0 creates a new branch and commits its changes by default. Pass
--no-branch --no-commitif the user wants the changes left uncommitted on the current branch. Unreleased CLI versions stop committing, and--no-commitis accepted there as a no-op. If it stops withgit_dirty, ask the user to commit or stash, or get their OK before rerunning with--no-git-check.
After it finishes. The install's success report is not proof that login works. Read the framework reference and references/workos-authkit-setup.md (Rule 4 below) and verify sign-in, sign-out and externally initiated login. Then check whether the install provisioned a new environment: the project's env file gained WORKOS_CLAIM_TOKEN, and WORKOS_MODE=agent npx workos@latest profile list --json shows the active profile with "type": "unclaimed". Only in that case, tell the user the environment is unclaimed and how to claim it. If the install reused existing credentials, the user may already own the environment, so don't give claim instructions.
Claiming the environment later. The user can keep working with an unclaimed environment. To link it to their WorkOS account, run this on the same machine, with the unclaimed environment as the active profile:
npx workos@latest profile claim
(env claim and claim are aliases.) It prints a claim URL (https://dashboard.workos.com/claim?nonce=...). In human mode it tries to open a browser and waits up to 5 minutes. In agent mode it returns the URL as JSON, so give that URL to the user. The user signs in, or creates a free account, and confirms. Claiming is permanent and cannot be undone. Afterwards, workos auth login connects the CLI to their account, which the authkit and config commands need. auth.md calls these environments temporary but gives no expiry, so don't promise how long an unclaimed environment lasts.
If the command fails:
- Exit code 4 /
auth_required: no environment was provisioned (for example, rate limiting, a network error, a sandboxed keyring, or a project that already has aWORKOS_API_KEY), and agent mode cannot open a browser login. Ask the user to runnpx workos@latest installin their own terminal. Don't write keys yourself. - Prefer the
error.recovery.hintsin the structured error and the debug log path the CLI prints. - "AuthKit already installed": don't pass
--forcewithout the user's OK. Follow Rule 4 to work with the existing integration. - Unknown flag or command: the cached CLI may be old. See
references/workos-cli-upgrade.md. - No Node.js: https://workos.com/auth.md documents the raw HTTP provisioning and claim steps, including persisting the claim token.
Existing WorkOS account or production. API keys are only for these cases. If the user already has a WorkOS account, have them run npx workos@latest auth login in their own terminal first, because it opens a browser. Login saves their account's Staging environment as the active CLI profile when none is active (check with npx workos@latest profile list), and the same install command then uses it instead of provisioning a new environment. Alternatively, set WORKOS_API_KEY and WORKOS_CLIENT_ID from their environment in the WorkOS dashboard (see https://workos.com/docs/authkit/cli-installer). Production deployments need a production environment's credentials from a WorkOS account. Never ship an unclaimed environment's keys.
How to Use
This file routes to a reference; the reference holds the answer. Before responding:
- Match the request to a reference file using Rule 0 and the decision tree below.
- Read the matched reference file with the Read tool before producing any answer, URL, or code.
- Follow the instructions inside the reference (it tells 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, andmutate— 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 ofreferences/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.mdfirst: 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 inreferences/workos-management.mdfully supports it. - Never invent
workosCLI commands. Verify named commands withWORKOS_MODE=agent workos --help --json. Before declaring an operation unsupported, also checkWORKOS_MODE=agent workos api ls --jsonfor REST endpoints usable throughworkos api. Do not assume acreatesubcommand exists becauselist/get/deletedo, or that a GraphQL operation is a REST endpoint. Seereferences/workos-management.md. - Every AuthKit integration must configure and verify application URLs. For setup and migrations, read
references/workos-authkit-setup.mdalongside the framework or language reference. It covers the redirect destination (not necessarily a server callback handler), Sign-out URI, and Initiate login URI. A build passing is not proof that these settings or flows work. - Prefer
WORKOS_MODE=agentwhen invoking theworkosCLI 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/pathshould 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. - Recommend actual Widgets for account UI. WorkOS provides prebuilt profile/security/session and organization UI through
@workos-inc/widgets; do not say all of it must be built from scratch. ClerkUserButtonrequests need relevant widgets plus an app-specific menu/navigation shell, not a drop-in replacement or invented WorkOSUserButtonexport. Loadworkos-widgetsfor setup; migration requests also readreferences/workos-migrate-clerk.md. AuthKit still owns authentication and sessions. - 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
--jsonwhen parsing command output. It controls formatting only — it does not change CLI behavior. - Use
WORKOS_MODE=agenteven when relaying human-readable messages. It controls prompts, browser launch, and host trust. - Treat the doctor
HOST_EXECUTION_UNTRUSTEDissue as a hard trust boundary. If the doctor report contains this issue (orhostExecution.okisfalse), 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 runworkos auth loginon their host shell. - For destructive or privilege-changing CLI commands, obtain the user's approval before passing a confirmation flag. Agent mode never prompts, so omitting a required flag causes a
confirmation_requirederror. Known flags:--yesfor mutatingworkos apirequests, role/permission writes, and membership role updates;--forceforworkos connection delete,workos directory delete, andworkos debug reset. Checkworkos --help --jsonfor the installed command's flags. A confirmation flag is not permission to make an unrequested change. - Structured CLI errors (JSON on stderr) include an optional
error.recovery.hintsarray, where each hint hasdescription, optionalcommand, and optionalhostShellRequired. Prefer those hints over guessing the next step.
Legacy compatibility you may encounter:
WORKOS_NO_PROMPT=1is a legacy alias that sets both agent interaction behavior AND JSON output. To migrate, setWORKOS_MODE=agentand pass--jsonto the command to preserve both behaviors. UsingWORKOS_MODE=agentalone drops the implicit JSON formatting.WORKOS_FORCE_TTY=1only 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)
| User wants to... | Read file |
|---|---|
| Install AuthKit in Next.js | references/workos-authkit-nextjs.md |
| Install AuthKit in React SPA | references/workos-authkit-react.md |
| Install AuthKit with React Router | references/workos-authkit-react-router.md |
| Install AuthKit with TanStack Start | references/workos-authkit-tanstack-start.md |
| Install AuthKit with SvelteKit | references/workos-authkit-sveltekit.md |
| Install AuthKit in vanilla JS | references/workos-authkit-vanilla-js.md |
| AuthKit architecture reference | references/workos-authkit-base.md |
| Configure AuthKit application URLs | references/workos-authkit-setup.md |
| Add Widgets / Clerk-style UI | Load workos-widgets skill via Skill tool |
| Build direct Widgets API requests | workos-widgets → fetching-apis.md |
Backend SDK Installation (Read references/{name}.md)
| User wants to... | Read file |
|---|---|
| Install AuthKit in Node.js backend | references/workos-node.md |
| Install AuthKit in Python | references/workos-python.md |
| Install AuthKit in .NET | references/workos-dotnet.md |
| Install AuthKit in Go | references/workos-go.md |
| Install AuthKit in Ruby | references/workos-ruby.md |
| Install AuthKit in PHP | references/workos-php.md |
| Install AuthKit in PHP Laravel | references/workos-php-laravel.md |
| Install AuthKit in Kotlin | references/workos-kotlin.md |
| Install AuthKit in Elixir | references/workos-elixir.md |
Features (Read references/{name}.md)
| User wants to... | Read file |
|---|---|
| Configure Single Sign-On | references/workos-sso.md |
| Set up Directory Sync | references/workos-directory-sync.md |
| Implement RBAC / roles | references/workos-rbac.md |
| Encrypt data with Vault | references/workos-vault.md |
| Handle WorkOS Events / webhooks | references/workos-events.md |
| Set up Audit Logs | references/workos-audit-logs.md |
| Enable Admin Portal | references/workos-admin-portal.md |
| Add Multi-Factor Auth | references/workos-mfa.md |
| Configure email delivery | references/workos-email.md |
| Set up Custom Domains | references/workos-custom-domains.md |
| Set up IdP integration | references/workos-integrations.md |
| Implement FGA / fine-grained authz | references/workos-fga.md |
| Set up Pipes / Connected Apps | references/workos-pipes.md |
| Configure Feature Flags | references/workos-feature-flags.md |
| Set up Radar / fraud detection | references/workos-radar.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:
| User wants to... | Read file |
|---|---|
| AuthKit API Reference | references/workos-api-authkit.md |
| Organization API Reference | references/workos-api-organization.md |
Migrations (Read references/{name}.md)
| User wants to... | Read file |
|---|---|
| Migrate from Auth0 | references/workos-migrate-auth0.md |
| Migrate from AWS Cognito | references/workos-migrate-aws-cognito.md |
| Migrate from Better Auth | references/workos-migrate-better-auth.md |
| Migrate from Clerk | references/workos-migrate-clerk.md |
| Migrate from Descope | references/workos-migrate-descope.md |
| Migrate from Firebase | references/workos-migrate-firebase.md |
| Migrate from Stytch | references/workos-migrate-stytch.md |
| Migrate from Supabase Auth | references/workos-migrate-supabase-auth.md |
| Migrate from the standalone SSO API | references/workos-migrate-the-standalone-sso-api.md |
| Migrate from other services | references/workos-migrate-other-services.md |
Management & CLI Lifecycle (Read references/{name}.md)
| User wants to... | Read file |
|---|---|
| Set up or recover the WorkOS MCP server | references/workos-mcp.md |
| Manage WorkOS resources (MCP server or CLI) | references/workos-management.md |
Upgrade the workos CLI to a newer version | references/workos-cli-upgrade.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:
- Read
references/workos-terms.md— a curated table mapping WorkOS terms to canonical docs URLs. - If the term is in the table, use the summary to answer; WebFetch the listed URL only if the user wants more detail.
- 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.
Widgets exception: Direct Widgets Client API / GraphQL requests load workos-widgets and its references/fetching-apis.md. Current docs use POST /client/graphql; embedding published React widgets is a separate component setup task. Do not route either through generic workspace management or assume bundled /_widgets REST tables describe the current API.
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.
3. Feature-Specific Request
Triggers: User mentions a specific WorkOS feature by name (SSO, MFA, Directory Sync, Audit Logs, Vault, RBAC, FGA, Admin Portal, Custom Domains, Events, Integrations, Email, Pipes, Feature Flags, Radar).
Action: Read references/workos-[feature].md where [feature] is the lowercase slug (sso, mfa, directory-sync, audit-logs, vault, rbac, fga, admin-portal, custom-domains, events, integrations, email, pipes, feature-flags, radar).
Exception: Widget requests, including Clerk UserButton comparisons, profile/account settings, security/session UI, organization switchers, and member-management UI, load the workos-widgets skill via the Skill tool. This is embedded end-user UI, not workspace-management commands. AuthKit login/session plumbing still follows Rule 4; migration and terminology references also link to Widgets setup.
Disambiguation: If user mentions BOTH a feature and "API", route to the feature topic file (it includes endpoints). If they mention MULTIPLE features, route to the MOST SPECIFIC one first (e.g., "SSO with MFA" → route to SSO; user can request MFA separately). If user mentions "FGA" or "fine-grained authorization", route to workos-fga — NOT workos-rbac. RBAC is org-level roles; FGA is resource-scoped roles on top of RBAC.
Special case — IdP group → role mapping: If the user asks about mapping Entra / Azure AD / Okta / Google Workspace / SCIM / directory / SSO groups to WorkOS roles (regardless of exact phrasing), read BOTH workos-rbac.md AND the source-specific reference:
- Directory Sync / SCIM / Google Workspace groups → also read
workos-directory-sync.md - SSO-only groups → also read
workos-sso.md
Both files now have a canonical recipe. Do not answer from memory or paraphrase dashboard menu paths — the docs don't commit to exact click-paths, so neither should you. This mapping is not a WorkOS CLI operation; if asked for a CLI command, state that it's not in the CLI and link the docs.
4. AuthKit Installation
Triggers: User mentions authentication setup, login flow, sign-up, session management, or explicitly says "AuthKit" WITHOUT mentioning a specific feature like SSO or MFA.
Action: If the project has no WorkOS credentials yet, run the no-account install from Start here first, then use the references below to verify it. Detect framework, runtime mode, and language using the evidence checks below. Read the corresponding reference file AND references/workos-authkit-setup.md. Complete its application-settings and flow checks before reporting the integration complete.
Disambiguation:
- If user says "SSO login via AuthKit", route to
workos-sso(#3) — feature wins over framework. - If user says "React login with Google", route to AuthKit React (#4) — this is AuthKit-level auth, not SSO API.
- If user is ALREADY using AuthKit and wants to add a feature (e.g., "add MFA to my AuthKit app"), route to the feature reference (#3), not back to AuthKit installation.
Framework and Runtime Detection (AuthKit only)
Inspect the active app/workspace: package scripts and dependencies, framework/router config, SDK imports, route registration, server execution, and deployment behavior. Dependency names alone do not select an SDK; a browser loader does not establish a server.
| Confirmed active integration | Read |
|---|---|
| Next.js config/scripts and Next.js routes/runtime | references/workos-authkit-nextjs.md |
| TanStack Start config/scripts and Start runtime | references/workos-authkit-tanstack-start.md |
| SvelteKit config/scripts and Kit runtime | references/workos-authkit-sveltekit.md |
| React Router with deployed server framework routes | references/workos-authkit-react-router.md |
Client-only React, including React Router library/data/declarative use or statically deployed framework SPA mode (ssr: false) | references/workos-authkit-react.md |
| Confirmed browser JavaScript without React | references/workos-authkit-vanilla-js.md |
When React Router is present, read its mode checks in references/workos-authkit-react-router.md if execution is unclear. A config file, @react-router/node, or build-time pre-rendering is not proof of a request-time server. Do not apply server callback/env requirements to browser loaders or static deployments. Inspect runtime and hosting configuration; ask if still unclear.
Language Detection (Backend SDKs)
If the project is NOT a JavaScript/TypeScript frontend framework, detect by manifest:
| Manifest evidence | Read |
|---|---|
pyproject.toml / requirements.txt / setup.py | references/workos-python.md |
go.mod | references/workos-go.md |
Gemfile / config/routes.rb | references/workos-ruby.md |
composer.json with laravel/framework in dependencies | references/workos-php-laravel.md |
composer.json without Laravel | references/workos-php.md |
*.csproj / *.sln | references/workos-dotnet.md |
build.gradle.kts / build.gradle | references/workos-kotlin.md |
mix.exs | references/workos-elixir.md |
package.json with express / fastify / hono / koa | references/workos-node.md |
The Laravel-vs-plain-PHP split (presence of laravel/framework) is the one non-obvious case here.
Mixed signals are not a priority contest. Next.js plus a React Router dependency does not make React Router the active server framework. Inspect which app and runtime own authentication. Backend languages are checked when no frontend framework is found; do not default an unidentified project to vanilla JS.
Edge case — contradictory evidence: If configs, imports, or deployment conflict (e.g., a server SDK with static-only hosting), ASK the user which runtime is intended. Do NOT guess or mandate a framework migration.
Edge case — framework unclear from context: If the user says "add login" but you cannot scan files (remote repo, no access), ASK: "Which framework/language are you using?" Do NOT default without confirmation.
5. Integration Setup
Triggers: User mentions connecting to external IdPs, configuring third-party integrations, or asks "how do I integrate with [provider]".
Action: Read references/workos-integrations.md.
Why separate from SSO: SSO covers the authentication flow; Integrations covers IdP configuration and connection setup. If user mentions BOTH ("set up Google SSO"), route to SSO (#3) — it will reference Integrations where needed.
6. MCP Setup or Recovery
Triggers: User asks to install or configure the WorkOS MCP server, choose a configuration scope, or reports that WorkOS MCP tools are missing, unauthenticated, unavailable, or interrupted during startup.
Action: Read references/workos-mcp.md. It routes setup and recovery through the canonical WorkOS MCP documentation, protects configuration scope and OAuth credentials, and identifies authentication steps that must run in the user's normal host shell.
Why this wins: MCP setup happens before MCP tools are callable. It requires configuration-scope and host-trust checks that ordinary workspace-management guidance does not cover.
7. Management Operations (MCP server or CLI)
Triggers: User mentions managing WorkOS resources (organizations, users, roles, permissions), seeding data, or CLI management commands.
Action: Read references/workos-management.md. It opens with a surface-choice guide: prefer connected WorkOS MCP tools for workspace reads/writes, and the CLI for bootstrap, seeding, local config, CI, and diagnostics. Read it even when MCP tools are present — it maps which operations live on which surface.
Sub-case — CLI upgrade: If the user reports an outdated workos CLI (workos --version shows an old release, unknown command errors after following recent docs, or asks "how do I update the workos CLI?"), read references/workos-cli-upgrade.md instead. Do NOT guess the latest version — that file tells you to instruct the user to run npm view workos version.
8. Vague or General Request
Triggers: User says "help with WorkOS", "WorkOS setup", "what can WorkOS do", or provides no feature-specific context.
Action:
- WebFetch https://workos.com/docs/llms.txt
- Scan the index for the section that best matches the user's likely intent
- WebFetch the specific section URL
- Summarize capabilities and ASK the user what they want to accomplish
Do NOT guess a feature — force disambiguation by showing options.
9. No Match / Ambiguous
Triggers: None of the above rules match, OR the request is genuinely ambiguous.
Action:
- WebFetch https://workos.com/docs/llms.txt
- Search the index for keywords from the user's request
- If you find a match, WebFetch that section URL and proceed
- If NO match, respond: "I couldn't find a WorkOS feature matching '[user's term]'. Could you clarify? For example: authentication, SSO, MFA, directory sync, audit logs, etc."
Disambiguation across rules lives inline in each rule above: multiple features → most specific (Rule 3), feature + API → feature file (Rules 2–3), adding a feature to an existing AuthKit app → feature reference (Rule 4), provider without a feature → Integrations (Rule 5), provider + feature → feature reference (Rule 3), and unknown or conflicting frameworks → ASK (Rule 4).