Skip to content
Skills Library
Programming · Tool integration

workos-setup

/workos-setup

Set up WorkOS AuthKit sign-in in a project with `npx workos@latest install`, which needs no WorkOS account. Use when the user asks to add WorkOS or AuthKit authentication to an app, to scaffold a new app with WorkOS, or to claim the temporary WorkOS environment the installer created.

Repository
skills ↗
Licence
MIT
Last repository change
02.11.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Set up WorkOS AuthKit sign-in in a project with `npx workos@latest install`, which needs no WorkOS account. Use when the user asks to add WorkOS or AuthKit authentication to an app, to scaffold a new app with WorkOS, or to claim the temporary WorkOS environment the installer created.

Original author description

Set up WorkOS AuthKit sign-in in a project with `npx workos@latest install`, which needs no WorkOS account. Use when the user asks to add WorkOS or AuthKit authentication to an app, to scaffold a new app with WorkOS, or to claim the temporary WorkOS environment the installer created.

How it works

  1. Before you start
  2. Run the installer
  3. Verify
  4. Claim the environment
  5. Go further
Original SKILL.md headings · 90 lines, 593 words
SKILL.md preview
---
name: workos-setup
description: Set up WorkOS AuthKit sign-in in a project with `npx workos@latest install`, which needs no WorkOS account. Use when the user asks to add WorkOS or AuthKit authentication to an app, to scaffold a new app with WorkOS, or to claim the temporary WorkOS environment the installer created.
---

# Set up WorkOS

The WorkOS CLI adds AuthKit sign-in to a project. When it finds no WorkOS
credentials, it provisions a temporary WorkOS environment, so the user doesn't
need a WorkOS account to start. They can claim the environment into their
account later.

## Before you start

Tell the user what you will do and wait for a yes:

1. Add WorkOS AuthKit sign-in to this project, or scaffold a new Next.js app if
   the directory is empty.
2. Use the project's existing WorkOS credentials if it has them. Otherwise,
   create a temporary WorkOS environment they can claim later.

If the project already uses a different auth provider, stop and agree on a
migration plan before changing anything. Don't remove existing auth without
approval.

## Run the installer

From the project root:

```bash
WORKOS_MODE=agent npx workos@latest install
```

- It writes `WORKOS_API_KEY`, `WORKOS_CLIENT_ID` and, for a new environment,
  `WORKOS_CLAIM_TOKEN` to `.env.local` (or `.env` when there is no
  `package.json`), and adds that file to `.gitignore`. Don't delete the claim
  token or the CLI profile before the environment is claimed.
- It puts its changes on a new git branch. Pass `--no-branch` to stay on the
  current one. If it stops with `git_dirty`, ask the user to commit or stash
  first.
- In agent mode it prints JSON. On failure, follow `error.recovery.hints`. Exit
  code `4` means it could not provision an environment: ask the user to run
  `npx workos@latest install` in their own terminal, and don't write keys
  yourself.
- If the user already has a WorkOS account, have them run
  `npx workos@latest auth login` in their own terminal first, since it opens a
  browser. The installer then uses their Staging environment instead of
  creating a temporary one.

## Verify

The installer's success report is not proof that sign-in works. It also
reports which application URLs (Sign-out URI, Initiate login URI, CORS origin)
it saved and which it left for you. Start the app and check that:

- Sign-in completes and creates an app session.
- Sign-out ends the session and lands on the configured Sign-out URI.
- A sign-in started outside the app, such as an invitation or password-reset
  email, reaches the Initiate login URI and continues without a loop or
  callback error.

The Initiate login URI must be an app route that starts AuthKit sign-in, not
the callback. Configure any URL the installer left by following the
framework's AuthKit guide at https://workos.com/docs/authkit, or
`references/workos-authkit-setup.md` if the `workos` skill is installed. If you
can't save a setting or test a flow, tell the user exactly which ones remain.
Never call setup complete from the installer's report, a build, or `doctor`
output alone. To diagnose a broken integration, run
`WORKOS_MODE=agent npx workos@latest doctor --json --skip-ai`.

## Claim the environment

Only if the installer created a new environment (the env file gained
`WORKOS_CLAIM_TOKEN`), tell the user it is temporary and how to claim it. On
the same machine:

```bash
WORKOS_MODE=agent npx workos@latest profile claim
```

In agent mode it returns a claim URL as JSON. Give that URL to the user, who
signs in or creates a free account and confirms. Claiming is permanent. Never
ship a temporary environment's keys to production.

## Go further

- WorkOS skills for coding agents: `npx skills add https://workos.com`. Ask
  first, since it writes into the agent's skills folder. The `workos` skill
  covers SSO, Directory Sync, RBAC, migrations, and the rest of WorkOS.
- Documentation index: https://workos.com/docs/llms.txt. Add `.md` to any
  documentation URL to get Markdown.
- Raw HTTP steps for provisioning and claiming an environment without Node.js:
  https://workos.com/auth.md

Versions

The database has no other skills named workos-setup.

Database snapshot: 13.11.2026 · package version fd22641296f2 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100workos
    Start new AuthKit setups with `npx workos@latest install`, which needs no WorkOS account. Use when the user asks for a WorkOS docs URL, term, or dashboard field (Sign-in endpoint, initiate_login_uri, Redirect URI, `WORKOS_*` env vars), or is implementing, debugging, or migrating…
  • 91workos-to-descope
    Use this skill whenever anyone asks about migrating from WorkOS to Descope — whether they're a developer doing it themselves or a technical lead evaluating the move. Triggers on: "how do I migrate from WorkOS", "replace WorkOS with Descope", "we're moving off WorkOS", "WorkOS to…
  • 100workos-webhooks
    Receive and verify WorkOS webhooks. Use when setting up WorkOS webhook handlers, debugging WorkOS-Signature verification, or handling enterprise auth events like dsync.user.created, dsync.group.user_added, connection.activated, user.created, or session.created.
  • 100convex-setup-auth
    Sets up Convex authentication with user management, identity mapping, and access control. Use this skill when adding login or signup to a Convex app, configuring Convex Auth, Clerk, WorkOS AuthKit, Auth0, or custom JWT providers, wiring auth.config.ts, protecting queries and…
  • 85taste-workos
    Replicate the visual aesthetic, typography, color tokens, and component craftsmanship of workos.com (WorkOS). Use when building or restyling UI pages, landing pages, dashboards, or components to match WorkOS's exact design language.
  • 90workos-widgets
    Use when the user is implementing, embedding, or debugging a WorkOS Widget — specifically the User Management, User Profile, Admin Portal SSO Connection, or Admin Portal Domain Verification widgets. Handles the full stack — detecting the frontend (Next.js, React, React Router,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.