Clerk Setup

# Set up Clerk

Use the [Clerk CLI](https://clerk.com/docs/cli) to add authentication. In agent environments, supported frameworks default to accountless setup: `npx -y clerk@latest init` provisions a claimable application and writes temporary development keys without requiring a Clerk account.

## Before you start

Show the user this checklist and wait for a yes:

``` Here's what I'll do to get you set up with Clerk.

1. Set up Clerk in this project, or scaffold a new app if this directory is empty. 2. Install Clerk's agent skills for the coding agents on this machine, if they aren't installed yet. 3. Start your app with Clerk installed.

Shall I proceed? ```

## Existing authentication

Before `init`, inspect auth dependencies, routes, middleware, sessions, and user records — never environment files. If a different auth provider exists, stop and get approval for a migration plan covering:

- Backend API user import, stable external IDs, compatible password hashes, and OAuth continuity. - Protected routes, tokens, session cutover, and rollout strategy.

Do not modify or remove existing auth without approval.

See the [migration guide](https://clerk.com/docs/guides/development/migrating/overview).

## Existing Clerk projects

If the project already uses Clerk, skip `init` in Steps 1a and 1b: a signed-out agent run could create another application and replace the project's Clerk keys. If Clerk already works and the user asked for setup, report that no setup is needed. If the user reports missing keys, restore them through the existing-application branch below. If inspection finds missing provider, middleware, or auth routes, add only those pieces from the matching quickstart in Step 2. Never create a replacement application.

Inspect its Clerk package versions before changing anything and use the version table in the [clerk skill](https://clerk.com/.well-known/skills/clerk/SKILL.md) to identify its SDK generation. Preserve that generation unless the user asks to upgrade it, and apply these differences in every step below for Core 2 projects:

- React and Expo use `@clerk/clerk-react` and `@clerk/clerk-expo` instead of `@clerk/react` and `@clerk/expo`. - Control components are `<SignedIn>` and `<SignedOut>` instead of `<Show>`. - Next.js `ClerkProvider` can wrap `<html>` instead of going inside `<body>`. - The minimum Node.js version is 18.17.0 instead of 20.9.0. - Themes come from `@clerk/themes` and `@clerk/themes/shadcn.css` instead of `@clerk/ui`.

## Use an existing Clerk application (optional)

Follow this branch when the user asks to use an existing Clerk application or an existing Clerk project needs its keys restored. Have them authenticate from their host terminal before targeting account-level resources:

```bash npx -y clerk@latest auth login ```

If they supplied an application ID, keep it for `init` or `link` as appropriate. Otherwise, list the applications:

```bash npx -y clerk@latest apps list --json ```

Show the names and IDs and ask which application to use. Never choose an application for them. For a new Clerk integration, pass the selected ID as `--app <application_id>` to `init`. For a project already using Clerk, do not run `init`. If it is not already linked to the selected application, link it:

```bash npx -y clerk@latest link --app <application_id> ```

For missing development keys, pull them:

```bash npx -y clerk@latest env pull ```

Only when the user needs production keys, use `npx -y clerk@latest env pull --instance prod` instead. Do not replace working keys or switch applications without the user's confirmation.

## Step 1a: Existing project without Clerk

For a project that does not already use Clerk, run from the project root:

```bash npx -y clerk@latest init ```

`init` detects the framework and package manager, installs the SDK, and configures the provider, middleware, auth routes, and environment. It also installs Clerk's agent skills globally. If the user declined them, or they're already available to you, such as when you loaded this as the `clerk-setup` skill, add `--no-skills` to skip that step. Don't pass `--framework` or `--pm` unless asked. Add `--app <application_id>` only when the user selected an application in the optional branch above.

## Step 1b: Empty directory

Ask which framework and package manager to use, defaulting to Next.js and npm:

```bash npx -y clerk@latest init --framework <framework> --pm <package-manager> ```

`init` creates the app in a new subdirectory, such as `my-clerk-next-app`, not in the current directory. Run the remaining steps from that subdirectory. As in Step 1a, add `--no-skills` if Clerk's skills are already available to you or the user declined them.

`init` can create Next.js, React Router, Astro, Nuxt, TanStack Start, React, Vue, JavaScript/Vite, and Expo apps. For Express, Fastify, iOS, or Android, create the project with that platform's own tooling first, then follow Step 1a.

## Step 1c: Accountless development keys

For