clerk-setup

SKILL.md

Framework-agnostic Clerk authentication setup following official quickstart guides.

Detects framework from package.json dependencies and fetches the corresponding Clerk quickstart documentation (supports Next.js, Remix, Astro, Nuxt, React Router, TanStack Start, React SPA, Vue, Express, Fastify, Expo, Chrome Extension, Android, iOS, and Vanilla JavaScript)

Handles environment variable setup, provider configuration, and middleware/proxy file creation with version-specific guidance for Core 2 SDK differences

Includes migration detection and planning for projects with existing auth providers (NextAuth, Supabase, Firebase, Auth0, Passport, custom JWT)

Applies shadcn/ui theming automatically if components.json is detected; supports both keyless auto-generation and manual dashboard API key retrieval

Documents critical pitfalls including async auth() calls, secret key exposure, middleware matchers, and ClerkProvider placement rules

Adding Clerk

Version: Check package.json for the SDK version — see clerk skill for the version table. Core 2 differences are noted inline with > **Core 2 ONLY (skip if current SDK):** callouts.

This skill sets up Clerk for authentication by following the official quickstart documentation. For agents, the clerk CLI handles most of this end to end — see the next section.

Agent-first: Provision via CLI

The clerk CLI replaces most Dashboard clicks. Three scenarios cover almost everything:

Scenario A — New project, new Clerk app

clerk init --framework <next|react|vue|nuxt|astro|react-router|tanstack-react-start|expressjs|fastify|expo> -y

clerk init creates the Clerk app via PLAPI, links the project, writes the framework-specific publishable + secret keys to the right env file (e.g. .env.local for Next.js, .env for Vite-based projects), and installs the SDK package.

Scenario B — Existing project, existing Clerk app