teak: Skill for Claude Code

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. Verify named commands with WORKOS_MODE=agent workos --help --json. Before declaring an operation unsupported, also check WORKOS_MODE=agent workos api ls --json for REST endpoints usable through workos api. Do not assume a create subcommand exists because list/get/delete do, or that a GraphQL operation is a REST endpoint. See references/workos-management.md.
• Every AuthKit integration must configure and verify application URLs. For setup and migrations, read references/workos-authkit-setup.md alongside 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=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.