[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AJTX04CS2BDSY7TGEYGSB8":3,"skill-same:01M7AJTX04CS2BDSY7TGEYGSB8":60},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":24,"commitSha":25,"skillDirectory":5,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7AJTX04CS2BDSY7TGEYGSB8","clerk-auth",null,"This skill provides comprehensive knowledge for integrating Clerk authentication in React, Next.js, and Cloudflare Workers applications. It should be used when setting up user authentication, implementing protected routes, verifying JWT tokens, creating custom JWT templates with user metadata and organization claims, configuring Clerk middleware, integrating with shadcn\u002Fui components, testing authentication flows, or troubleshooting Clerk authentication errors.\n\nUse when: adding Clerk to React\u002FVite projects, setting up Clerk in Next.js App Router, implementing Clerk authentication in Cloudflare Workers, configuring clerkMiddleware for route protection, creating custom JWT templates with shortcodes (user.id, user.email, user.public_metadata.role), accessing session claims for RBAC, integrating with Supabase\u002FGrafbase, verifying tokens with @clerk\u002Fbackend, integrating Clerk with Hono, using Clerk shadcn\u002Fui components, writing E2E tests with Playwright, generating test session tokens, using test email addresses and phone numbers, or encountering authentication errors.\n\nPrevents 11 documented issues: missing secret key errors, API key migration failures, JWKS cache race conditions, CSRF vulnerabilities from missing authorizedParties, import path errors after Core 2 upgrade, JWT size limit issues, deprecated API version warnings, ClerkProvider JSX component errors, async auth() helper confusion, environment variable misconfiguration, and Vite dev mode 431 header errors.\n\nKeywords: clerk, clerk auth, clerk authentication, @clerk\u002Fnextjs, @clerk\u002Fbackend, @clerk\u002Fclerk-react, clerkMiddleware, createRouteMatcher, verifyToken, useUser, useAuth, useClerk, JWT template, JWT claims, JWT shortcodes, custom JWT, session claims, getToken template, user.public_metadata, org_id, org_slug, org_role, CustomJwtSessionClaims, sessionClaims metadata, clerk webhook, clerk secret key, clerk publishable key, protected routes, Cloudflare Workers auth, Next.js auth, shadcn\u002Fui auth, @hono\u002Fclerk-auth, \"Missing Clerk Secret Key\", \"cannot be used as a JSX component\", JWKS error, authorizedParties, clerk middleware, ClerkProvider, UserButton, SignIn, SignUp, clerk testing, test emails, test phone numbers, +clerk_test, 424242 OTP, session token, testing token, @clerk\u002Ftesting, playwright testing, E2E testing, clerk test mode, bot detection, generate session token, test users","davidanthonyn\u002Fagent-skills","davidanthonyn","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F55152980?v=4","01M7AJ4MY8S5C2RJCGX6626J0G","01M7AJ4MZB7EC7CAP27ANCSE7N",1,"MIT","https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fclerk-auth\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: clerk-auth\ndescription: |\n  This skill provides comprehensive knowledge for integrating Clerk authentication in React, Next.js, and Cloudflare Workers applications. It should be used when setting up user authentication, implementing protected routes, verifying JWT tokens, creating custom JWT templates with user metadata and organization claims, configuring Clerk middleware, integrating with shadcn\u002Fui components, testing authentication flows, or troubleshooting Clerk authentication errors.\n\n  Use when: adding Clerk to React\u002FVite projects, setting up Clerk in Next.js App Router, implementing Clerk authentication in Cloudflare Workers, configuring clerkMiddleware for route protection, creating custom JWT templates with shortcodes (user.id, user.email, user.public_metadata.role), accessing session claims for RBAC, integrating with Supabase\u002FGrafbase, verifying tokens with @clerk\u002Fbackend, integrating Clerk with Hono, using Clerk shadcn\u002Fui components, writing E2E tests with Playwright, generating test session tokens, using test email addresses and phone numbers, or encountering authentication errors.\n\n  Prevents 11 documented issues: missing secret key errors, API key migration failures, JWKS cache race conditions, CSRF vulnerabilities from missing authorizedParties, import path errors after Core 2 upgrade, JWT size limit issues, deprecated API version warnings, ClerkProvider JSX component errors, async auth() helper confusion, environment variable misconfiguration, and Vite dev mode 431 header errors.\n\n  Keywords: clerk, clerk auth, clerk authentication, @clerk\u002Fnextjs, @clerk\u002Fbackend, @clerk\u002Fclerk-react, clerkMiddleware, createRouteMatcher, verifyToken, useUser, useAuth, useClerk, JWT template, JWT claims, JWT shortcodes, custom JWT, session claims, getToken template, user.public_metadata, org_id, org_slug, org_role, CustomJwtSessionClaims, sessionClaims metadata, clerk webhook, clerk secret key, clerk publishable key, protected routes, Cloudflare Workers auth, Next.js auth, shadcn\u002Fui auth, @hono\u002Fclerk-auth, \"Missing Clerk Secret Key\", \"cannot be used as a JSX component\", JWKS error, authorizedParties, clerk middleware, ClerkProvider, UserButton, SignIn, SignUp, clerk testing, test emails, test phone numbers, +clerk_test, 424242 OTP, session token, testing token, @clerk\u002Ftesting, playwright testing, E2E testing, clerk test mode, bot detection, generate session token, test users\nlicense: MIT\n---\n\n# Clerk Authentication\n\n**Status**: Production Ready ✅\n**Last Updated**: 2025-10-28\n**Dependencies**: None\n**Latest Versions**: @clerk\u002Fnextjs@6.33.3, @clerk\u002Fbackend@2.17.2, @clerk\u002Fclerk-react@5.51.0, @clerk\u002Ftesting@1.4.4\n\n---\n\n## Quick Start (10 Minutes)\n\nChoose your framework:\n- [React (Vite)](#react-vite-setup) - ClerkProvider + hooks\n- [Next.js App Router](#nextjs-app-router-setup) - Middleware + async auth()\n- [Cloudflare Workers](#cloudflare-workers-setup) - Backend verification\n\n---\n\n## React (Vite) Setup\n\n### 1. Install Clerk\n\n\\`\\`\\`bash\nnpm install @clerk\u002Fclerk-react\n\\`\\`\\`\n\n**Latest Version**: @clerk\u002Fclerk-react@5.51.0 (verified 2025-10-22)\n\n### 2. Configure ClerkProvider\n\nUpdate \\`src\u002Fmain.tsx\\`:\n\n\\`\\`\\`typescript\nimport React from 'react'\nimport ReactDOM from 'react-dom\u002Fclient'\nimport { ClerkProvider } from '@clerk\u002Fclerk-react'\nimport App from '.\u002FApp.tsx'\nimport '.\u002Findex.css'\n\n\u002F\u002F Get publishable key from environment\nconst PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY\n\nif (!PUBLISHABLE_KEY) {\n  throw new Error('Missing Publishable Key')\n}\n\nReactDOM.createRoot(document.getElementById('root')!).render(\n  \u003CReact.StrictMode>\n    \u003CClerkProvider publishableKey={PUBLISHABLE_KEY}>\n      \u003CApp \u002F>\n    \u003C\u002FClerkProvider>\n  \u003C\u002FReact.StrictMode>,\n)\n\\`\\`\\`\n\n**CRITICAL**:\n- Use \\`VITE_\\` prefix for environment variables in Vite\n- ClerkProvider must wrap your entire app\n- Source: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Freact\u002Fclerk-provider\n\n### 3. Add Environment Variables\n\nCreate \\`.env.local\\`:\n\n\\`\\`\\`bash\nVITE_CLERK_PUBLISHABLE_KEY=pk_test_...\n\\`\\`\\`\n\n**Security Note**: Only \\`VITE_\\` prefixed vars are exposed to client code.\n\n### 4. Use Authentication Hooks\n\n\\`\\`\\`typescript\nimport { useUser, useAuth, useClerk } from '@clerk\u002Fclerk-react'\n\nfunction App() {\n  \u002F\u002F Get user object (includes email, metadata, etc.)\n  const { isLoaded, isSignedIn, user } = useUser()\n\n  \u002F\u002F Get auth state and session methods\n  const { userId, sessionId, getToken } = useAuth()\n\n  \u002F\u002F Get Clerk instance for advanced operations\n  const { openSignIn, signOut } = useClerk()\n\n  \u002F\u002F Always check isLoaded before rendering auth-dependent UI\n  if (!isLoaded) {\n    return \u003Cdiv>Loading...\u003C\u002Fdiv>\n  }\n\n  if (!isSignedIn) {\n    return \u003Cbutton onClick={() => openSignIn()}>Sign In\u003C\u002Fbutton>\n  }\n\n  return (\n    \u003Cdiv>\n      \u003Ch1>Welcome {user.firstName}!\u003C\u002Fh1>\n      \u003Cp>Email: {user.primaryEmailAddress?.emailAddress}\u003C\u002Fp>\n      \u003Cbutton onClick={() => signOut()}>Sign Out\u003C\u002Fbutton>\n    \u003C\u002Fdiv>\n  )\n}\n\\`\\`\\`\n\n**Why This Matters**:\n- \\`isLoaded\\` prevents flash of wrong content\n- \\`useUser()\\` provides full user object with metadata\n- \\`useAuth()\\` provides session tokens and auth state\n- Source: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Freact\u002Fuse-user\n\n---\n\n## Next.js App Router Setup\n\n### 1. Install Clerk\n\n\\`\\`\\`bash\nnpm install @clerk\u002Fnextjs\n\\`\\`\\`\n\n**Latest Version**: @clerk\u002Fnextjs@6.33.3 (verified 2025-10-22)\n- **New in v6**: Async auth() helper, Next.js 15 support, static rendering by default\n- Source: https:\u002F\u002Fclerk.com\u002Fchangelog\u002F2024-10-22-clerk-nextjs-v6\n\n### 2. Configure Environment Variables\n\nCreate \\`.env.local\\`:\n\n\\`\\`\\`bash\nNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...\nCLERK_SECRET_KEY=sk_test_...\n\n# Optional: Customize sign-in\u002Fup pages\nNEXT_PUBLIC_CLERK_SIGN_IN_URL=\u002Fsign-in\nNEXT_PUBLIC_CLERK_SIGN_UP_URL=\u002Fsign-up\nNEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=\u002Fdashboard\nNEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=\u002Fonboarding\n\\`\\`\\`\n\n**CRITICAL**:\n- \\`CLERK_SECRET_KEY\\` must NEVER be exposed to client\n- Use \\`NEXT_PUBLIC_\\` prefix for client-side vars only\n- Source: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Fclerk-environment-variables\n\n### 3. Add Middleware for Route Protection\n\nCreate \\`middleware.ts\\` in project root:\n\n\\`\\`\\`typescript\nimport { clerkMiddleware, createRouteMatcher } from '@clerk\u002Fnextjs\u002Fserver'\n\n\u002F\u002F Define which routes are public (everything else requires auth)\nconst isPublicRoute = createRouteMatcher([\n  '\u002F',\n  '\u002Fsign-in(.*)',\n  '\u002Fsign-up(.*)',\n  '\u002Fapi\u002Fwebhooks(.*)', \u002F\u002F Clerk webhooks should be public\n])\n\nexport default clerkMiddleware(async (auth, request) => {\n  \u002F\u002F Protect all routes except public ones\n  if (!isPublicRoute(request)) {\n    await auth.protect()\n  }\n})\n\nexport const config = {\n  matcher: [\n    \u002F\u002F Skip Next.js internals and static files\n    '\u002F((?!_next|[^?]*\\\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',\n    \u002F\u002F Always run for API routes\n    '\u002F(api|trpc)(.*)',\n  ],\n}\n\\`\\`\\`\n\n**CRITICAL**:\n- \\`auth.protect()\\` is async in v6 (breaking change from v5)\n- \\`createRouteMatcher()\\` accepts glob patterns\n- Alternative: protect specific routes instead of inverting logic\n- Source: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fnextjs\u002Fclerk-middleware\n\n### 4. Wrap App with ClerkProvider\n\nUpdate \\`app\u002Flayout.tsx\\`:\n\n\\`\\`\\`typescript\nimport { ClerkProvider } from '@clerk\u002Fnextjs'\nimport '.\u002Fglobals.css'\n\nexport default function RootLayout({\n  children,\n}: {\n  children: React.ReactNode\n}) {\n  return (\n    \u003CClerkProvider>\n      \u003Chtml lang=\"en\">\n        \u003Cbody>{children}\u003C\u002Fbody>\n      \u003C\u002Fhtml>\n    \u003C\u002FClerkProvider>\n  )\n}\n\\`\\`\\`\n\n### 5. Use auth() in Server Components\n\n\\`\\`\\`typescript\nimport { auth, currentUser } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default async function DashboardPage() {\n  \u002F\u002F Get auth state (lightweight)\n  const { userId, sessionId } = await auth()\n\n  \u002F\u002F Get full user object (heavier, fewer calls)\n  const user = await currentUser()\n\n  if (!userId) {\n    return \u003Cdiv>Unauthorized\u003C\u002Fdiv>\n  }\n\n  return (\n    \u003Cdiv>\n      \u003Ch1>Dashboard\u003C\u002Fh1>\n      \u003Cp>User ID: {userId}\u003C\u002Fp>\n      \u003Cp>Email: {user?.primaryEmailAddress?.emailAddress}\u003C\u002Fp>\n    \u003C\u002Fdiv>\n  )\n}\n\\`\\`\\`\n\n**CRITICAL**:\n- \\`auth()\\` is async in v6 (breaking change)\n- Use \\`auth()\\` for lightweight checks\n- Use \\`currentUser()\\` when you need full user object\n\n---\n\n## Cloudflare Workers Setup\n\n### 1. Install Dependencies\n\n\\`\\`\\`bash\nnpm install @clerk\u002Fbackend hono\n\\`\\`\\`\n\n**Latest Versions**:\n- @clerk\u002Fbackend@2.17.2 (verified 2025-10-22)\n- hono@4.10.1\n\n### 2. Configure Environment Variables\n\nCreate \\`.dev.vars\\` for local development:\n\n\\`\\`\\`bash\nCLERK_SECRET_KEY=sk_test_...\nCLERK_PUBLISHABLE_KEY=pk_test_...\n\\`\\`\\`\n\n**Production**: Use \\`wrangler secret put CLERK_SECRET_KEY\\`\n\n### 3. Implement Token Verification\n\nCreate \\`src\u002Findex.ts\\`:\n\n\\`\\`\\`typescript\nimport { Hono } from 'hono'\nimport { verifyToken } from '@clerk\u002Fbackend'\n\ntype Bindings = {\n  CLERK_SECRET_KEY: string\n  CLERK_PUBLISHABLE_KEY: string\n}\n\ntype Variables = {\n  userId: string | null\n  sessionClaims: any | null\n}\n\nconst app = new Hono\u003C{ Bindings: Bindings; Variables: Variables }>()\n\n\u002F\u002F Middleware: Verify Clerk token\napp.use('\u002Fapi\u002F*', async (c, next) => {\n  const authHeader = c.req.header('Authorization')\n\n  if (!authHeader) {\n    c.set('userId', null)\n    c.set('sessionClaims', null)\n    return next()\n  }\n\n  const token = authHeader.replace('Bearer ', '')\n\n  try {\n    const { data, error } = await verifyToken(token, {\n      secretKey: c.env.CLERK_SECRET_KEY,\n      \u002F\u002F IMPORTANT: Set authorizedParties to prevent CSRF attacks\n      authorizedParties: ['https:\u002F\u002Fyourdomain.com'],\n    })\n\n    if (error) {\n      console.error('Token verification failed:', error)\n      c.set('userId', null)\n      c.set('sessionClaims', null)\n    } else {\n      c.set('userId', data.sub)\n      c.set('sessionClaims', data)\n    }\n  } catch (err) {\n    console.error('Token verification error:', err)\n    c.set('userId', null)\n    c.set('sessionClaims', null)\n  }\n\n  return next()\n})\n\n\u002F\u002F Protected route\napp.get('\u002Fapi\u002Fprotected', (c) => {\n  const userId = c.get('userId')\n\n  if (!userId) {\n    return c.json({ error: 'Unauthorized' }, 401)\n  }\n\n  return c.json({\n    message: 'This is protected',\n    userId,\n    sessionClaims: c.get('sessionClaims'),\n  })\n})\n\nexport default app\n\\`\\`\\`\n\n**CRITICAL**:\n- Always set \\`authorizedParties\\` to prevent CSRF attacks\n- Use \\`secretKey\\`, not deprecated \\`apiKey\\`\n- Source: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Fverify-token\n\n---\n\n## JWT Templates & Custom Claims\n\nClerk allows customizing JWT (JSON Web Token) structure using templates. This enables integration with third-party services, role-based access control, and multi-tenant applications.\n\n### Quick Start: Create a JWT Template\n\n**1. Navigate to Clerk Dashboard**:\n- Go to **Sessions** page\n- Click **Customize session token**\n- Click **Create template**\n\n**2. Define Template**:\n```json\n{\n  \"user_id\": \"{{user.id}}\",\n  \"email\": \"{{user.primary_email_address}}\",\n  \"role\": \"{{user.public_metadata.role || 'user'}}\"\n}\n```\n\n**3. Use Template in Code**:\n```typescript\n\u002F\u002F Frontend (React\u002FNext.js)\nconst { getToken } = useAuth()\nconst token = await getToken({ template: 'my-template' })\n\n\u002F\u002F Backend (Cloudflare Workers)\nconst sessionClaims = c.get('sessionClaims')\nconst role = sessionClaims?.role\n```\n\n### Available Shortcodes\n\n| Category | Shortcodes | Example |\n|----------|-----------|---------|\n| **User ID & Name** | `{{user.id}}`, `{{user.first_name}}`, `{{user.last_name}}`, `{{user.full_name}}` | `\"John Doe\"` |\n| **Contact** | `{{user.primary_email_address}}`, `{{user.primary_phone_address}}` | `\"john@example.com\"` |\n| **Profile** | `{{user.image_url}}`, `{{user.username}}`, `{{user.created_at}}` | `\"https:\u002F\u002F...\"` |\n| **Verification** | `{{user.email_verified}}`, `{{user.phone_number_verified}}` | `true` |\n| **Metadata** | `{{user.public_metadata}}`, `{{user.public_metadata.FIELD}}` | `{\"role\": \"admin\"}` |\n| **Organization** | `org_id`, `org_slug`, `org_role` (in sessionClaims) | `\"org:admin\"` |\n\n### Advanced Features\n\n**String Interpolation**:\n```json\n{\n  \"full_name\": \"{{user.last_name}} {{user.first_name}}\",\n  \"greeting\": \"Hello, {{user.first_name}}!\"\n}\n```\n\n**Conditional Fallbacks**:\n```json\n{\n  \"role\": \"{{user.public_metadata.role || 'user'}}\",\n  \"age\": \"{{user.public_metadata.age || 18}}\",\n  \"verified\": \"{{user.email_verified || user.phone_number_verified}}\"\n}\n```\n\n**Nested Metadata with Dot Notation**:\n```json\n{\n  \"interests\": \"{{user.public_metadata.profile.interests}}\",\n  \"department\": \"{{user.public_metadata.department}}\"\n}\n```\n\n### Default Claims (Auto-Included)\n\nEvery JWT includes these claims automatically (cannot be overridden):\n\n```json\n{\n  \"azp\": \"http:\u002F\u002Flocalhost:3000\",              \u002F\u002F Authorized party\n  \"exp\": 1639398300,                            \u002F\u002F Expiration time\n  \"iat\": 1639398272,                            \u002F\u002F Issued at\n  \"iss\": \"https:\u002F\u002Fyour-app.clerk.accounts.dev\", \u002F\u002F Issuer\n  \"jti\": \"10db7f531a90cb2faea4\",               \u002F\u002F JWT ID\n  \"nbf\": 1639398220,                            \u002F\u002F Not before\n  \"sub\": \"user_1deJLArSTiWiF1YdsEWysnhJLLY\"    \u002F\u002F User ID\n}\n```\n\n### Size Limitation: 1.2KB for Custom Claims\n\n**Problem**: Browser cookies limited to 4KB. Clerk's default claims consume ~2.8KB, leaving **1.2KB for custom claims**.\n\n**⚠️ Development Note**: When testing custom claims in Vite dev mode, you may encounter **\"431 Request Header Fields Too Large\"** error. This is caused by Clerk's handshake token in the URL exceeding Vite's 8KB limit. See [Issue #11](#issue-11-431-request-header-fields-too-large-vite-dev-mode) for solution.\n\n**Solution**:\n```json\n\u002F\u002F ✅ GOOD: Minimal claims\n{\n  \"user_id\": \"{{user.id}}\",\n  \"email\": \"{{user.primary_email_address}}\",\n  \"role\": \"{{user.public_metadata.role}}\"\n}\n\n\u002F\u002F ❌ BAD: Exceeds limit\n{\n  \"bio\": \"{{user.public_metadata.bio}}\",  \u002F\u002F 6KB field\n  \"all_metadata\": \"{{user.public_metadata}}\"  \u002F\u002F Entire object\n}\n```\n\n**Best Practice**: Store large data in database, include only identifiers\u002Froles in JWT.\n\n### TypeScript Type Safety\n\nAdd global type declarations for auto-complete:\n\n**Create `types\u002Fglobals.d.ts`**:\n```typescript\nexport {}\n\ndeclare global {\n  interface CustomJwtSessionClaims {\n    metadata: {\n      role?: 'admin' | 'moderator' | 'user'\n      onboardingComplete?: boolean\n      organizationId?: string\n    }\n  }\n}\n```\n\n### Common Use Cases\n\n**Role-Based Access Control**:\n```json\n{\n  \"email\": \"{{user.primary_email_address}}\",\n  \"role\": \"{{user.public_metadata.role || 'user'}}\",\n  \"permissions\": \"{{user.public_metadata.permissions}}\"\n}\n```\n\n**Multi-Tenant Applications**:\n```json\n{\n  \"user_id\": \"{{user.id}}\",\n  \"org_id\": \"{{user.public_metadata.org_id}}\",\n  \"org_role\": \"{{user.public_metadata.org_role}}\"\n}\n```\n\n**Supabase Integration**:\n```json\n{\n  \"email\": \"{{user.primary_email_address}}\",\n  \"app_metadata\": {\n    \"provider\": \"clerk\"\n  },\n  \"user_metadata\": {\n    \"full_name\": \"{{user.full_name}}\"\n  }\n}\n```\n\n### See Also\n\n- **Complete Reference**: See `references\u002Fjwt-claims-guide.md` for comprehensive documentation\n- **Template Examples**: See `templates\u002Fjwt\u002F` directory for working examples\n- **TypeScript Types**: See `templates\u002Ftypescript\u002Fcustom-jwt-types.d.ts`\n- **Official Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fjwt-templates\n\n---\n\n## Testing\n\nClerk provides comprehensive testing tools for local development and CI\u002FCD pipelines.\n\n### Quick Start: Test Credentials\n\n**Test Emails** (no emails sent, fixed OTP):\n```\njohn+clerk_test@example.com\njane+clerk_test@gmail.com\n```\n\n**Test Phone Numbers** (no SMS sent, fixed OTP):\n```\n+12015550100\n+19735550133\n```\n\n**Fixed OTP Code**: `424242` (works for all test credentials)\n\n### Generate Session Tokens\n\nFor testing API endpoints, generate valid session tokens (60-second lifetime):\n\n```bash\n# Using the provided script\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js\n\n# Create new test user\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js --create-user\n\n# Auto-refresh token every 50 seconds\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js --refresh\n```\n\n**Manual Flow**:\n1. Create user: `POST \u002Fv1\u002Fusers`\n2. Create session: `POST \u002Fv1\u002Fsessions`\n3. Generate token: `POST \u002Fv1\u002Fsessions\u002F{session_id}\u002Ftokens`\n4. Use in header: `Authorization: Bearer \u003Ctoken>`\n\n### E2E Testing with Playwright\n\nInstall `@clerk\u002Ftesting` for automatic Testing Token management:\n\n```bash\nnpm install -D @clerk\u002Ftesting\n```\n\n**Global Setup** (`global.setup.ts`):\n```typescript\nimport { clerkSetup } from '@clerk\u002Ftesting\u002Fplaywright'\nimport { test as setup } from '@playwright\u002Ftest'\n\nsetup('global setup', async ({}) => {\n  await clerkSetup()\n})\n```\n\n**Test File** (`auth.spec.ts`):\n```typescript\nimport { setupClerkTestingToken } from '@clerk\u002Ftesting\u002Fplaywright'\nimport { test } from '@playwright\u002Ftest'\n\ntest('sign up', async ({ page }) => {\n  await setupClerkTestingToken({ page })\n\n  await page.goto('\u002Fsign-up')\n  await page.fill('input[name=\"emailAddress\"]', 'test+clerk_test@example.com')\n  await page.fill('input[name=\"password\"]', 'TestPassword123!')\n  await page.click('button[type=\"submit\"]')\n\n  \u002F\u002F Verify with fixed OTP\n  await page.fill('input[name=\"code\"]', '424242')\n  await page.click('button[type=\"submit\"]')\n\n  await expect(page).toHaveURL('\u002Fdashboard')\n})\n```\n\n### Testing Tokens (Bot Detection Bypass)\n\nTesting Tokens bypass bot detection in test suites.\n\n**Obtain Token**:\n```bash\ncurl -X POST https:\u002F\u002Fapi.clerk.com\u002Fv1\u002Ftesting_tokens \\\n  -H \"Authorization: Bearer sk_test_...\"\n```\n\n**Use in Frontend API Requests**:\n```\nPOST https:\u002F\u002Fyour-app.clerk.accounts.dev\u002Fv1\u002Fclient\u002Fsign_ups?__clerk_testing_token=TOKEN\n```\n\n**Note**: `@clerk\u002Ftesting` handles this automatically for Playwright\u002FCypress.\n\n### Production Limitations\n\nTesting Tokens work in both development and production, but:\n- ❌ Code-based auth (SMS\u002FEmail OTP) not supported in production\n- ✅ Email + password authentication supported\n- ✅ Magic links supported\n\n### See Also\n\n- **Complete Guide**: See `references\u002Ftesting-guide.md` for comprehensive testing documentation\n- **Session Token Script**: See `scripts\u002Fgenerate-session-token.js`\n- **Demo Repository**: https:\u002F\u002Fgithub.com\u002Fclerk\u002Fclerk-playwright-nextjs\n- **Official Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Ftesting\u002Foverview\n\n---\n\n## Known Issues Prevention\n\nThis skill prevents **11 documented issues**:\n\n### Issue #1: Missing Clerk Secret Key\n**Error**: \"Missing Clerk Secret Key or API Key\"\n**Source**: https:\u002F\u002Fstackoverflow.com\u002Fquestions\u002F77620604\n**Prevention**: Always set in \\`.env.local\\` or via \\`wrangler secret put\\`\n\n### Issue #2: API Key → Secret Key Migration\n**Error**: \"apiKey is deprecated, use secretKey\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Replace \\`apiKey\\` with \\`secretKey\\` in all calls\n\n### Issue #3: JWKS Cache Race Condition\n**Error**: \"No JWK available\"\n**Source**: https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fblob\u002Fmain\u002Fpackages\u002Fbackend\u002FCHANGELOG.md\n**Prevention**: Use @clerk\u002Fbackend@2.17.2 or later (fixed)\n\n### Issue #4: Missing authorizedParties (CSRF)\n**Error**: No error, but CSRF vulnerability\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Fverify-token\n**Prevention**: Always set \\`authorizedParties: ['https:\u002F\u002Fyourdomain.com']\\`\n\n### Issue #5: Import Path Changes (Core 2)\n**Error**: \"Cannot find module\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Update import paths for Core 2\n\n### Issue #6: JWT Size Limit Exceeded\n**Error**: Token exceeds size limit\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fbackend-requests\u002Fmaking\u002Fcustom-session-token\n**Prevention**: Keep custom claims under 1.2KB\n\n### Issue #7: Deprecated API Version v1\n**Error**: \"API version v1 is deprecated\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Use latest SDK versions (API v2025-04-10)\n\n### Issue #8: ClerkProvider JSX Component Error\n**Error**: \"cannot be used as a JSX component\"\n**Source**: https:\u002F\u002Fstackoverflow.com\u002Fquestions\u002F79265537\n**Prevention**: Ensure React 19 compatibility with @clerk\u002Fclerk-react@5.51.0+\n\n### Issue #9: Async auth() Helper Confusion\n**Error**: \"auth() is not a function\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fchangelog\u002F2024-10-22-clerk-nextjs-v6\n**Prevention**: Always await: \\`const { userId } = await auth()\\`\n\n### Issue #10: Environment Variable Misconfiguration\n**Error**: \"Missing Publishable Key\" or secret leaked\n**Prevention**: Use correct prefixes (\\`NEXT_PUBLIC_\\`, \\`VITE_\\`), never commit secrets\n\n### Issue #11: 431 Request Header Fields Too Large (Vite Dev Mode)\n**Error**: \"431 Request Header Fields Too Large\" when signing in\n**Source**: Common in Vite dev mode when testing custom JWT claims\n**Cause**: Clerk's `__clerk_handshake` token in URL exceeds Vite's 8KB header limit\n**Prevention**:\n\nAdd to `package.json`:\n\\`\\`\\`json\n{\n  \"scripts\": {\n    \"dev\": \"NODE_OPTIONS='--max-http-header-size=32768' vite\"\n  }\n}\n\\`\\`\\`\n\n**Temporary Workaround**: Clear browser cache, sign out, sign back in\n\n**Why**: Clerk dev tokens are larger than production; custom JWT claims increase handshake token size\n\n**Note**: This is different from Issue #6 (session token size). Issue #6 is about cookies (1.2KB), this is about URL parameters in dev mode (8KB → 32KB).\n\n---\n\n## Critical Rules\n\n### Always Do\n\n✅ Set \\`authorizedParties\\` when verifying tokens\n✅ Use \\`CLERK_SECRET_KEY\\` environment variable\n✅ Check \\`isLoaded\\` before rendering auth UI\n✅ Use \\`getToken()\\` fresh for each request\n✅ Await \\`auth()\\` in Next.js v6+\n✅ Use \\`NEXT_PUBLIC_\\` prefix for client vars only\n✅ Store secrets via \\`wrangler secret put\\`\n✅ Implement middleware for route protection\n✅ Use API version 2025-04-10 or later\n\n### Never Do\n\n❌ Store \\`CLERK_SECRET_KEY\\` in client code\n❌ Use deprecated \\`apiKey\\` parameter\n❌ Store tokens in localStorage\n❌ Skip \\`authorizedParties\\` check\n❌ Exceed 1.2KB for custom JWT claims\n❌ Forget to check \\`isLoaded\\`\n❌ Expose secrets with \\`NEXT_PUBLIC_\\` prefix\n❌ Use API version v1\n\n---\n\n## Official Documentation\n\n- **Clerk Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\n- **Next.js Guide**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Fnextjs\u002Foverview\n- **React Guide**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Freact\u002Foverview\n- **Backend SDK**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Foverview\n- **JWT Templates**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fjwt-templates\n- **shadcn\u002Fui Integration**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Fshadcn-cli\n- **Context7 Library ID**: \\`\u002Fclerk\u002Fclerk-docs\\`\n\n---\n\n## Package Versions (Verified 2025-10-22)\n\n\\`\\`\\`json\n{\n  \"dependencies\": {\n    \"@clerk\u002Fnextjs\": \"^6.33.3\",\n    \"@clerk\u002Fclerk-react\": \"^5.51.0\",\n    \"@clerk\u002Fbackend\": \"^2.17.2\"\n  }\n}\n\\`\\`\\`\n","# Clerk Authentication\n\n**Status**: Production Ready ✅\n**Last Updated**: 2025-10-28\n**Dependencies**: None\n**Latest Versions**: @clerk\u002Fnextjs@6.33.3, @clerk\u002Fbackend@2.17.2, @clerk\u002Fclerk-react@5.51.0, @clerk\u002Ftesting@1.4.4\n\n---\n\n## Quick Start (10 Minutes)\n\nChoose your framework:\n- [React (Vite)](#react-vite-setup) - ClerkProvider + hooks\n- [Next.js App Router](#nextjs-app-router-setup) - Middleware + async auth()\n- [Cloudflare Workers](#cloudflare-workers-setup) - Backend verification\n\n---\n\n## React (Vite) Setup\n\n### 1. Install Clerk\n\n\\`\\`\\`bash\nnpm install @clerk\u002Fclerk-react\n\\`\\`\\`\n\n**Latest Version**: @clerk\u002Fclerk-react@5.51.0 (verified 2025-10-22)\n\n### 2. Configure ClerkProvider\n\nUpdate \\`src\u002Fmain.tsx\\`:\n\n\\`\\`\\`typescript\nimport React from 'react'\nimport ReactDOM from 'react-dom\u002Fclient'\nimport { ClerkProvider } from '@clerk\u002Fclerk-react'\nimport App from '.\u002FApp.tsx'\nimport '.\u002Findex.css'\n\n\u002F\u002F Get publishable key from environment\nconst PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY\n\nif (!PUBLISHABLE_KEY) {\n  throw new Error('Missing Publishable Key')\n}\n\nReactDOM.createRoot(document.getElementById('root')!).render(\n  \u003CReact.StrictMode>\n    \u003CClerkProvider publishableKey={PUBLISHABLE_KEY}>\n      \u003CApp \u002F>\n    \u003C\u002FClerkProvider>\n  \u003C\u002FReact.StrictMode>,\n)\n\\`\\`\\`\n\n**CRITICAL**:\n- Use \\`VITE_\\` prefix for environment variables in Vite\n- ClerkProvider must wrap your entire app\n- Source: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Freact\u002Fclerk-provider\n\n### 3. Add Environment Variables\n\nCreate \\`.env.local\\`:\n\n\\`\\`\\`bash\nVITE_CLERK_PUBLISHABLE_KEY=pk_test_...\n\\`\\`\\`\n\n**Security Note**: Only \\`VITE_\\` prefixed vars are exposed to client code.\n\n### 4. Use Authentication Hooks\n\n\\`\\`\\`typescript\nimport { useUser, useAuth, useClerk } from '@clerk\u002Fclerk-react'\n\nfunction App() {\n  \u002F\u002F Get user object (includes email, metadata, etc.)\n  const { isLoaded, isSignedIn, user } = useUser()\n\n  \u002F\u002F Get auth state and session methods\n  const { userId, sessionId, getToken } = useAuth()\n\n  \u002F\u002F Get Clerk instance for advanced operations\n  const { openSignIn, signOut } = useClerk()\n\n  \u002F\u002F Always check isLoaded before rendering auth-dependent UI\n  if (!isLoaded) {\n    return \u003Cdiv>Loading...\u003C\u002Fdiv>\n  }\n\n  if (!isSignedIn) {\n    return \u003Cbutton onClick={() => openSignIn()}>Sign In\u003C\u002Fbutton>\n  }\n\n  return (\n    \u003Cdiv>\n      \u003Ch1>Welcome {user.firstName}!\u003C\u002Fh1>\n      \u003Cp>Email: {user.primaryEmailAddress?.emailAddress}\u003C\u002Fp>\n      \u003Cbutton onClick={() => signOut()}>Sign Out\u003C\u002Fbutton>\n    \u003C\u002Fdiv>\n  )\n}\n\\`\\`\\`\n\n**Why This Matters**:\n- \\`isLoaded\\` prevents flash of wrong content\n- \\`useUser()\\` provides full user object with metadata\n- \\`useAuth()\\` provides session tokens and auth state\n- Source: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Freact\u002Fuse-user\n\n---\n\n## Next.js App Router Setup\n\n### 1. Install Clerk\n\n\\`\\`\\`bash\nnpm install @clerk\u002Fnextjs\n\\`\\`\\`\n\n**Latest Version**: @clerk\u002Fnextjs@6.33.3 (verified 2025-10-22)\n- **New in v6**: Async auth() helper, Next.js 15 support, static rendering by default\n- Source: https:\u002F\u002Fclerk.com\u002Fchangelog\u002F2024-10-22-clerk-nextjs-v6\n\n### 2. Configure Environment Variables\n\nCreate \\`.env.local\\`:\n\n\\`\\`\\`bash\nNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...\nCLERK_SECRET_KEY=sk_test_...\n\n# Optional: Customize sign-in\u002Fup pages\nNEXT_PUBLIC_CLERK_SIGN_IN_URL=\u002Fsign-in\nNEXT_PUBLIC_CLERK_SIGN_UP_URL=\u002Fsign-up\nNEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=\u002Fdashboard\nNEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=\u002Fonboarding\n\\`\\`\\`\n\n**CRITICAL**:\n- \\`CLERK_SECRET_KEY\\` must NEVER be exposed to client\n- Use \\`NEXT_PUBLIC_\\` prefix for client-side vars only\n- Source: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Fclerk-environment-variables\n\n### 3. Add Middleware for Route Protection\n\nCreate \\`middleware.ts\\` in project root:\n\n\\`\\`\\`typescript\nimport { clerkMiddleware, createRouteMatcher } from '@clerk\u002Fnextjs\u002Fserver'\n\n\u002F\u002F Define which routes are public (everything else requires auth)\nconst isPublicRoute = createRouteMatcher([\n  '\u002F',\n  '\u002Fsign-in(.*)',\n  '\u002Fsign-up(.*)',\n  '\u002Fapi\u002Fwebhooks(.*)', \u002F\u002F Clerk webhooks should be public\n])\n\nexport default clerkMiddleware(async (auth, request) => {\n  \u002F\u002F Protect all routes except public ones\n  if (!isPublicRoute(request)) {\n    await auth.protect()\n  }\n})\n\nexport const config = {\n  matcher: [\n    \u002F\u002F Skip Next.js internals and static files\n    '\u002F((?!_next|[^?]*\\\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',\n    \u002F\u002F Always run for API routes\n    '\u002F(api|trpc)(.*)',\n  ],\n}\n\\`\\`\\`\n\n**CRITICAL**:\n- \\`auth.protect()\\` is async in v6 (breaking change from v5)\n- \\`createRouteMatcher()\\` accepts glob patterns\n- Alternative: protect specific routes instead of inverting logic\n- Source: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fnextjs\u002Fclerk-middleware\n\n### 4. Wrap App with ClerkProvider\n\nUpdate \\`app\u002Flayout.tsx\\`:\n\n\\`\\`\\`typescript\nimport { ClerkProvider } from '@clerk\u002Fnextjs'\nimport '.\u002Fglobals.css'\n\nexport default function RootLayout({\n  children,\n}: {\n  children: React.ReactNode\n}) {\n  return (\n    \u003CClerkProvider>\n      \u003Chtml lang=\"en\">\n        \u003Cbody>{children}\u003C\u002Fbody>\n      \u003C\u002Fhtml>\n    \u003C\u002FClerkProvider>\n  )\n}\n\\`\\`\\`\n\n### 5. Use auth() in Server Components\n\n\\`\\`\\`typescript\nimport { auth, currentUser } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default async function DashboardPage() {\n  \u002F\u002F Get auth state (lightweight)\n  const { userId, sessionId } = await auth()\n\n  \u002F\u002F Get full user object (heavier, fewer calls)\n  const user = await currentUser()\n\n  if (!userId) {\n    return \u003Cdiv>Unauthorized\u003C\u002Fdiv>\n  }\n\n  return (\n    \u003Cdiv>\n      \u003Ch1>Dashboard\u003C\u002Fh1>\n      \u003Cp>User ID: {userId}\u003C\u002Fp>\n      \u003Cp>Email: {user?.primaryEmailAddress?.emailAddress}\u003C\u002Fp>\n    \u003C\u002Fdiv>\n  )\n}\n\\`\\`\\`\n\n**CRITICAL**:\n- \\`auth()\\` is async in v6 (breaking change)\n- Use \\`auth()\\` for lightweight checks\n- Use \\`currentUser()\\` when you need full user object\n\n---\n\n## Cloudflare Workers Setup\n\n### 1. Install Dependencies\n\n\\`\\`\\`bash\nnpm install @clerk\u002Fbackend hono\n\\`\\`\\`\n\n**Latest Versions**:\n- @clerk\u002Fbackend@2.17.2 (verified 2025-10-22)\n- hono@4.10.1\n\n### 2. Configure Environment Variables\n\nCreate \\`.dev.vars\\` for local development:\n\n\\`\\`\\`bash\nCLERK_SECRET_KEY=sk_test_...\nCLERK_PUBLISHABLE_KEY=pk_test_...\n\\`\\`\\`\n\n**Production**: Use \\`wrangler secret put CLERK_SECRET_KEY\\`\n\n### 3. Implement Token Verification\n\nCreate \\`src\u002Findex.ts\\`:\n\n\\`\\`\\`typescript\nimport { Hono } from 'hono'\nimport { verifyToken } from '@clerk\u002Fbackend'\n\ntype Bindings = {\n  CLERK_SECRET_KEY: string\n  CLERK_PUBLISHABLE_KEY: string\n}\n\ntype Variables = {\n  userId: string | null\n  sessionClaims: any | null\n}\n\nconst app = new Hono\u003C{ Bindings: Bindings; Variables: Variables }>()\n\n\u002F\u002F Middleware: Verify Clerk token\napp.use('\u002Fapi\u002F*', async (c, next) => {\n  const authHeader = c.req.header('Authorization')\n\n  if (!authHeader) {\n    c.set('userId', null)\n    c.set('sessionClaims', null)\n    return next()\n  }\n\n  const token = authHeader.replace('Bearer ', '')\n\n  try {\n    const { data, error } = await verifyToken(token, {\n      secretKey: c.env.CLERK_SECRET_KEY,\n      \u002F\u002F IMPORTANT: Set authorizedParties to prevent CSRF attacks\n      authorizedParties: ['https:\u002F\u002Fyourdomain.com'],\n    })\n\n    if (error) {\n      console.error('Token verification failed:', error)\n      c.set('userId', null)\n      c.set('sessionClaims', null)\n    } else {\n      c.set('userId', data.sub)\n      c.set('sessionClaims', data)\n    }\n  } catch (err) {\n    console.error('Token verification error:', err)\n    c.set('userId', null)\n    c.set('sessionClaims', null)\n  }\n\n  return next()\n})\n\n\u002F\u002F Protected route\napp.get('\u002Fapi\u002Fprotected', (c) => {\n  const userId = c.get('userId')\n\n  if (!userId) {\n    return c.json({ error: 'Unauthorized' }, 401)\n  }\n\n  return c.json({\n    message: 'This is protected',\n    userId,\n    sessionClaims: c.get('sessionClaims'),\n  })\n})\n\nexport default app\n\\`\\`\\`\n\n**CRITICAL**:\n- Always set \\`authorizedParties\\` to prevent CSRF attacks\n- Use \\`secretKey\\`, not deprecated \\`apiKey\\`\n- Source: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Fverify-token\n\n---\n\n## JWT Templates & Custom Claims\n\nClerk allows customizing JWT (JSON Web Token) structure using templates. This enables integration with third-party services, role-based access control, and multi-tenant applications.\n\n### Quick Start: Create a JWT Template\n\n**1. Navigate to Clerk Dashboard**:\n- Go to **Sessions** page\n- Click **Customize session token**\n- Click **Create template**\n\n**2. Define Template**:\n```json\n{\n  \"user_id\": \"{{user.id}}\",\n  \"email\": \"{{user.primary_email_address}}\",\n  \"role\": \"{{user.public_metadata.role || 'user'}}\"\n}\n```\n\n**3. Use Template in Code**:\n```typescript\n\u002F\u002F Frontend (React\u002FNext.js)\nconst { getToken } = useAuth()\nconst token = await getToken({ template: 'my-template' })\n\n\u002F\u002F Backend (Cloudflare Workers)\nconst sessionClaims = c.get('sessionClaims')\nconst role = sessionClaims?.role\n```\n\n### Available Shortcodes\n\n| Category | Shortcodes | Example |\n|----------|-----------|---------|\n| **User ID & Name** | `{{user.id}}`, `{{user.first_name}}`, `{{user.last_name}}`, `{{user.full_name}}` | `\"John Doe\"` |\n| **Contact** | `{{user.primary_email_address}}`, `{{user.primary_phone_address}}` | `\"john@example.com\"` |\n| **Profile** | `{{user.image_url}}`, `{{user.username}}`, `{{user.created_at}}` | `\"https:\u002F\u002F...\"` |\n| **Verification** | `{{user.email_verified}}`, `{{user.phone_number_verified}}` | `true` |\n| **Metadata** | `{{user.public_metadata}}`, `{{user.public_metadata.FIELD}}` | `{\"role\": \"admin\"}` |\n| **Organization** | `org_id`, `org_slug`, `org_role` (in sessionClaims) | `\"org:admin\"` |\n\n### Advanced Features\n\n**String Interpolation**:\n```json\n{\n  \"full_name\": \"{{user.last_name}} {{user.first_name}}\",\n  \"greeting\": \"Hello, {{user.first_name}}!\"\n}\n```\n\n**Conditional Fallbacks**:\n```json\n{\n  \"role\": \"{{user.public_metadata.role || 'user'}}\",\n  \"age\": \"{{user.public_metadata.age || 18}}\",\n  \"verified\": \"{{user.email_verified || user.phone_number_verified}}\"\n}\n```\n\n**Nested Metadata with Dot Notation**:\n```json\n{\n  \"interests\": \"{{user.public_metadata.profile.interests}}\",\n  \"department\": \"{{user.public_metadata.department}}\"\n}\n```\n\n### Default Claims (Auto-Included)\n\nEvery JWT includes these claims automatically (cannot be overridden):\n\n```json\n{\n  \"azp\": \"http:\u002F\u002Flocalhost:3000\",              \u002F\u002F Authorized party\n  \"exp\": 1639398300,                            \u002F\u002F Expiration time\n  \"iat\": 1639398272,                            \u002F\u002F Issued at\n  \"iss\": \"https:\u002F\u002Fyour-app.clerk.accounts.dev\", \u002F\u002F Issuer\n  \"jti\": \"10db7f531a90cb2faea4\",               \u002F\u002F JWT ID\n  \"nbf\": 1639398220,                            \u002F\u002F Not before\n  \"sub\": \"user_1deJLArSTiWiF1YdsEWysnhJLLY\"    \u002F\u002F User ID\n}\n```\n\n### Size Limitation: 1.2KB for Custom Claims\n\n**Problem**: Browser cookies limited to 4KB. Clerk's default claims consume ~2.8KB, leaving **1.2KB for custom claims**.\n\n**⚠️ Development Note**: When testing custom claims in Vite dev mode, you may encounter **\"431 Request Header Fields Too Large\"** error. This is caused by Clerk's handshake token in the URL exceeding Vite's 8KB limit. See [Issue #11](#issue-11-431-request-header-fields-too-large-vite-dev-mode) for solution.\n\n**Solution**:\n```json\n\u002F\u002F ✅ GOOD: Minimal claims\n{\n  \"user_id\": \"{{user.id}}\",\n  \"email\": \"{{user.primary_email_address}}\",\n  \"role\": \"{{user.public_metadata.role}}\"\n}\n\n\u002F\u002F ❌ BAD: Exceeds limit\n{\n  \"bio\": \"{{user.public_metadata.bio}}\",  \u002F\u002F 6KB field\n  \"all_metadata\": \"{{user.public_metadata}}\"  \u002F\u002F Entire object\n}\n```\n\n**Best Practice**: Store large data in database, include only identifiers\u002Froles in JWT.\n\n### TypeScript Type Safety\n\nAdd global type declarations for auto-complete:\n\n**Create `types\u002Fglobals.d.ts`**:\n```typescript\nexport {}\n\ndeclare global {\n  interface CustomJwtSessionClaims {\n    metadata: {\n      role?: 'admin' | 'moderator' | 'user'\n      onboardingComplete?: boolean\n      organizationId?: string\n    }\n  }\n}\n```\n\n### Common Use Cases\n\n**Role-Based Access Control**:\n```json\n{\n  \"email\": \"{{user.primary_email_address}}\",\n  \"role\": \"{{user.public_metadata.role || 'user'}}\",\n  \"permissions\": \"{{user.public_metadata.permissions}}\"\n}\n```\n\n**Multi-Tenant Applications**:\n```json\n{\n  \"user_id\": \"{{user.id}}\",\n  \"org_id\": \"{{user.public_metadata.org_id}}\",\n  \"org_role\": \"{{user.public_metadata.org_role}}\"\n}\n```\n\n**Supabase Integration**:\n```json\n{\n  \"email\": \"{{user.primary_email_address}}\",\n  \"app_metadata\": {\n    \"provider\": \"clerk\"\n  },\n  \"user_metadata\": {\n    \"full_name\": \"{{user.full_name}}\"\n  }\n}\n```\n\n### See Also\n\n- **Complete Reference**: See `references\u002Fjwt-claims-guide.md` for comprehensive documentation\n- **Template Examples**: See `templates\u002Fjwt\u002F` directory for working examples\n- **TypeScript Types**: See `templates\u002Ftypescript\u002Fcustom-jwt-types.d.ts`\n- **Official Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fjwt-templates\n\n---\n\n## Testing\n\nClerk provides comprehensive testing tools for local development and CI\u002FCD pipelines.\n\n### Quick Start: Test Credentials\n\n**Test Emails** (no emails sent, fixed OTP):\n```\njohn+clerk_test@example.com\njane+clerk_test@gmail.com\n```\n\n**Test Phone Numbers** (no SMS sent, fixed OTP):\n```\n+12015550100\n+19735550133\n```\n\n**Fixed OTP Code**: `424242` (works for all test credentials)\n\n### Generate Session Tokens\n\nFor testing API endpoints, generate valid session tokens (60-second lifetime):\n\n```bash\n# Using the provided script\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js\n\n# Create new test user\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js --create-user\n\n# Auto-refresh token every 50 seconds\nCLERK_SECRET_KEY=sk_test_... node scripts\u002Fgenerate-session-token.js --refresh\n```\n\n**Manual Flow**:\n1. Create user: `POST \u002Fv1\u002Fusers`\n2. Create session: `POST \u002Fv1\u002Fsessions`\n3. Generate token: `POST \u002Fv1\u002Fsessions\u002F{session_id}\u002Ftokens`\n4. Use in header: `Authorization: Bearer \u003Ctoken>`\n\n### E2E Testing with Playwright\n\nInstall `@clerk\u002Ftesting` for automatic Testing Token management:\n\n```bash\nnpm install -D @clerk\u002Ftesting\n```\n\n**Global Setup** (`global.setup.ts`):\n```typescript\nimport { clerkSetup } from '@clerk\u002Ftesting\u002Fplaywright'\nimport { test as setup } from '@playwright\u002Ftest'\n\nsetup('global setup', async ({}) => {\n  await clerkSetup()\n})\n```\n\n**Test File** (`auth.spec.ts`):\n```typescript\nimport { setupClerkTestingToken } from '@clerk\u002Ftesting\u002Fplaywright'\nimport { test } from '@playwright\u002Ftest'\n\ntest('sign up', async ({ page }) => {\n  await setupClerkTestingToken({ page })\n\n  await page.goto('\u002Fsign-up')\n  await page.fill('input[name=\"emailAddress\"]', 'test+clerk_test@example.com')\n  await page.fill('input[name=\"password\"]', 'TestPassword123!')\n  await page.click('button[type=\"submit\"]')\n\n  \u002F\u002F Verify with fixed OTP\n  await page.fill('input[name=\"code\"]', '424242')\n  await page.click('button[type=\"submit\"]')\n\n  await expect(page).toHaveURL('\u002Fdashboard')\n})\n```\n\n### Testing Tokens (Bot Detection Bypass)\n\nTesting Tokens bypass bot detection in test suites.\n\n**Obtain Token**:\n```bash\ncurl -X POST https:\u002F\u002Fapi.clerk.com\u002Fv1\u002Ftesting_tokens \\\n  -H \"Authorization: Bearer sk_test_...\"\n```\n\n**Use in Frontend API Requests**:\n```\nPOST https:\u002F\u002Fyour-app.clerk.accounts.dev\u002Fv1\u002Fclient\u002Fsign_ups?__clerk_testing_token=TOKEN\n```\n\n**Note**: `@clerk\u002Ftesting` handles this automatically for Playwright\u002FCypress.\n\n### Production Limitations\n\nTesting Tokens work in both development and production, but:\n- ❌ Code-based auth (SMS\u002FEmail OTP) not supported in production\n- ✅ Email + password authentication supported\n- ✅ Magic links supported\n\n### See Also\n\n- **Complete Guide**: See `references\u002Ftesting-guide.md` for comprehensive testing documentation\n- **Session Token Script**: See `scripts\u002Fgenerate-session-token.js`\n- **Demo Repository**: https:\u002F\u002Fgithub.com\u002Fclerk\u002Fclerk-playwright-nextjs\n- **Official Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Ftesting\u002Foverview\n\n---\n\n## Known Issues Prevention\n\nThis skill prevents **11 documented issues**:\n\n### Issue #1: Missing Clerk Secret Key\n**Error**: \"Missing Clerk Secret Key or API Key\"\n**Source**: https:\u002F\u002Fstackoverflow.com\u002Fquestions\u002F77620604\n**Prevention**: Always set in \\`.env.local\\` or via \\`wrangler secret put\\`\n\n### Issue #2: API Key → Secret Key Migration\n**Error**: \"apiKey is deprecated, use secretKey\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Replace \\`apiKey\\` with \\`secretKey\\` in all calls\n\n### Issue #3: JWKS Cache Race Condition\n**Error**: \"No JWK available\"\n**Source**: https:\u002F\u002Fgithub.com\u002Fclerk\u002Fjavascript\u002Fblob\u002Fmain\u002Fpackages\u002Fbackend\u002FCHANGELOG.md\n**Prevention**: Use @clerk\u002Fbackend@2.17.2 or later (fixed)\n\n### Issue #4: Missing authorizedParties (CSRF)\n**Error**: No error, but CSRF vulnerability\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Fverify-token\n**Prevention**: Always set \\`authorizedParties: ['https:\u002F\u002Fyourdomain.com']\\`\n\n### Issue #5: Import Path Changes (Core 2)\n**Error**: \"Cannot find module\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Update import paths for Core 2\n\n### Issue #6: JWT Size Limit Exceeded\n**Error**: Token exceeds size limit\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fbackend-requests\u002Fmaking\u002Fcustom-session-token\n**Prevention**: Keep custom claims under 1.2KB\n\n### Issue #7: Deprecated API Version v1\n**Error**: \"API version v1 is deprecated\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fupgrade-guides\u002Fcore-2\u002Fbackend\n**Prevention**: Use latest SDK versions (API v2025-04-10)\n\n### Issue #8: ClerkProvider JSX Component Error\n**Error**: \"cannot be used as a JSX component\"\n**Source**: https:\u002F\u002Fstackoverflow.com\u002Fquestions\u002F79265537\n**Prevention**: Ensure React 19 compatibility with @clerk\u002Fclerk-react@5.51.0+\n\n### Issue #9: Async auth() Helper Confusion\n**Error**: \"auth() is not a function\"\n**Source**: https:\u002F\u002Fclerk.com\u002Fchangelog\u002F2024-10-22-clerk-nextjs-v6\n**Prevention**: Always await: \\`const { userId } = await auth()\\`\n\n### Issue #10: Environment Variable Misconfiguration\n**Error**: \"Missing Publishable Key\" or secret leaked\n**Prevention**: Use correct prefixes (\\`NEXT_PUBLIC_\\`, \\`VITE_\\`), never commit secrets\n\n### Issue #11: 431 Request Header Fields Too Large (Vite Dev Mode)\n**Error**: \"431 Request Header Fields Too Large\" when signing in\n**Source**: Common in Vite dev mode when testing custom JWT claims\n**Cause**: Clerk's `__clerk_handshake` token in URL exceeds Vite's 8KB header limit\n**Prevention**:\n\nAdd to `package.json`:\n\\`\\`\\`json\n{\n  \"scripts\": {\n    \"dev\": \"NODE_OPTIONS='--max-http-header-size=32768' vite\"\n  }\n}\n\\`\\`\\`\n\n**Temporary Workaround**: Clear browser cache, sign out, sign back in\n\n**Why**: Clerk dev tokens are larger than production; custom JWT claims increase handshake token size\n\n**Note**: This is different from Issue #6 (session token size). Issue #6 is about cookies (1.2KB), this is about URL parameters in dev mode (8KB → 32KB).\n\n---\n\n## Critical Rules\n\n### Always Do\n\n✅ Set \\`authorizedParties\\` when verifying tokens\n✅ Use \\`CLERK_SECRET_KEY\\` environment variable\n✅ Check \\`isLoaded\\` before rendering auth UI\n✅ Use \\`getToken()\\` fresh for each request\n✅ Await \\`auth()\\` in Next.js v6+\n✅ Use \\`NEXT_PUBLIC_\\` prefix for client vars only\n✅ Store secrets via \\`wrangler secret put\\`\n✅ Implement middleware for route protection\n✅ Use API version 2025-04-10 or later\n\n### Never Do\n\n❌ Store \\`CLERK_SECRET_KEY\\` in client code\n❌ Use deprecated \\`apiKey\\` parameter\n❌ Store tokens in localStorage\n❌ Skip \\`authorizedParties\\` check\n❌ Exceed 1.2KB for custom JWT claims\n❌ Forget to check \\`isLoaded\\`\n❌ Expose secrets with \\`NEXT_PUBLIC_\\` prefix\n❌ Use API version v1\n\n---\n\n## Official Documentation\n\n- **Clerk Docs**: https:\u002F\u002Fclerk.com\u002Fdocs\n- **Next.js Guide**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Fnextjs\u002Foverview\n- **React Guide**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freferences\u002Freact\u002Foverview\n- **Backend SDK**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Freference\u002Fbackend\u002Foverview\n- **JWT Templates**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fsessions\u002Fjwt-templates\n- **shadcn\u002Fui Integration**: https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Fshadcn-cli\n- **Context7 Library ID**: \\`\u002Fclerk\u002Fclerk-docs\\`\n\n---\n\n## Package Versions (Verified 2025-10-22)\n\n\\`\\`\\`json\n{\n  \"dependencies\": {\n    \"@clerk\u002Fnextjs\": \"^6.33.3\",\n    \"@clerk\u002Fclerk-react\": \"^5.51.0\",\n    \"@clerk\u002Fbackend\": \"^2.17.2\"\n  }\n}\n\\`\\`\\`\n",{"name":5,"license":14,"description":23},"This skill provides comprehensive knowledge for integrating Clerk authentication in React, Next.js, and Cloudflare Workers applications. It should be used when setting up user authentication, implementing protected routes, verifying JWT tokens, creating custom JWT templates with user metadata and organization claims, configuring Clerk middleware, integrating with shadcn\u002Fui components, testing authentication flows, or troubleshooting Clerk authentication errors.\n\nUse when: adding Clerk to React\u002FVite projects, setting up Clerk in Next.js App Router, implementing Clerk authentication in Cloudflare Workers, configuring clerkMiddleware for route protection, creating custom JWT templates with shortcodes (user.id, user.email, user.public_metadata.role), accessing session claims for RBAC, integrating with Supabase\u002FGrafbase, verifying tokens with @clerk\u002Fbackend, integrating Clerk with Hono, using Clerk shadcn\u002Fui components, writing E2E tests with Playwright, generating test session tokens, using test email addresses and phone numbers, or encountering authentication errors.\n\nPrevents 11 documented issues: missing secret key errors, API key migration failures, JWKS cache race conditions, CSRF vulnerabilities from missing authorizedParties, import path errors after Core 2 upgrade, JWT size limit issues, deprecated API version warnings, ClerkProvider JSX component errors, async auth() helper confusion, environment variable misconfiguration, and Vite dev mode 431 header errors.\n\nKeywords: clerk, clerk auth, clerk authentication, @clerk\u002Fnextjs, @clerk\u002Fbackend, @clerk\u002Fclerk-react, clerkMiddleware, createRouteMatcher, verifyToken, useUser, useAuth, useClerk, JWT template, JWT claims, JWT shortcodes, custom JWT, session claims, getToken template, user.public_metadata, org_id, org_slug, org_role, CustomJwtSessionClaims, sessionClaims metadata, clerk webhook, clerk secret key, clerk publishable key, protected routes, Cloudflare Workers auth, Next.js auth, shadcn\u002Fui auth, @hono\u002Fclerk-auth, \"Missing Clerk Secret Key\", \"cannot be used as a JSX component\", JWKS error, authorizedParties, clerk middleware, ClerkProvider, UserButton, SignIn, SignUp, clerk testing, test emails, test phone numbers, +clerk_test, 424242 OTP, session token, testing token, @clerk\u002Ftesting, playwright testing, E2E testing, clerk test mode, bot detection, generate session token, test users\n","main","6b73b29e4866f997b1eb47fe8d9631396265fc24",0,"https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills","https:\u002F\u002Fgithub.com\u002Fdavidanthonyn","2026-09-09 16:06:07",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add davidanthonyn\u002Fagent-skills --skill clerk-auth",{"tool":36,"command":37},"bunx","bunx skills add davidanthonyn\u002Fagent-skills --skill clerk-auth",{"tool":39,"command":40},"pnpm","pnpm dlx skills add davidanthonyn\u002Fagent-skills --skill clerk-auth","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fclerk-auth\u002FSKILL.md",true,[44,50,54],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"README.md","REFERENCE","参考文档",5383,"https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fclerk-auth\u002FREADME.md",{"path":51,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":52,"sourceHtmlUrl":53},"SKILL.json",22979,"https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fclerk-auth\u002FSKILL.json",{"path":55,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":58,"sourceHtmlUrl":59},"SKILL.md.backup","OTHER","其他",22694,"https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fclerk-auth\u002FSKILL.md.backup",[61,68,76,83,90,99],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":18},"01M7AQNJDXVNVMN08N5BHBGZBF","zustand-state-management","Production-tested setup for Zustand state management in React applications with TypeScript.\nThis skill provides comprehensive patterns for building scalable, type-safe global state.\n\nUse when: setting up global state in React, migrating from Redux or Context API, implementing\nstate persistence with localStorage, configuring TypeScript with Zustand, using slices pattern\nfor modular stores, adding devtools middleware for debugging, handling Next.js SSR hydration,\nor encountering hydration errors, TypeScript inference issues, or persist middleware problems.\n\nPrevents 5 documented issues: Next.js hydration mismatches, TypeScript double parentheses\nsyntax errors, persist middleware export errors, infinite render loops, and slices pattern\ntype inference failures.\n\nKeywords: zustand, state management, React state, TypeScript state, persist middleware,\ndevtools, slices pattern, global state, React hooks, create store, useBoundStore,\nStateCreator, hydration error, text content mismatch, infinite render, localStorage,\nsessionStorage, immer middleware, shallow equality, selector pattern, zustand v5","https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fzustand-state-management\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":72,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":18},"01M7AQN2DW9DTPM8BYNZSHQANC","zetic-mlange","Help users integrate the ZETIC Melange (MLange) on-device AI SDK into Android (Kotlin\u002FJava) and iOS (Swift) mobile apps. Use this skill whenever the user mentions Zetic, MLange, Melange, ZeticMLangeModel, ZeticMLangeLLMModel, ZeticMLangeHFModel, on-device NPU inference for mobile, or deploying ML models to Android\u002FiOS with NPU acceleration. Also trigger when users ask about running LLMs on-device with GGUF quantization, mobile NPU model deployment, or converting PyTorch\u002FONNX models for mobile inference. Covers general model inference, LLM inference (streaming token generation), and HuggingFace model loading.","https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fzetic-mlange\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fzetic-mlange\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":18},"01M7AQMEK370FBPC75N2W8WA4W","youtube-downloader","Download videos, audio, playlists, and channels from YouTube and 1000+ websites using yt-dlp. Supports quality selection, format conversion, subtitle download, playlist filtering, metadata extraction, thumbnail download, and batch operations. Use when downloading YouTube videos in any quality (4K, 8K, HDR), extracting audio as MP3\u002FM4A\u002FFLAC, downloading entire playlists\u002Fchannels, getting subtitles in multiple languages, converting to specific formats, downloading live streams, archiving content, or batch processing multiple URLs. Optimized for reliability with automatic retries, rate limiting, and error handling.","https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fyoutube-downloader\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":18},"01M7AQHKQ4VQB04NH6BG4SV9Q7","wordpress-plugin-core","This skill provides comprehensive knowledge for WordPress plugin development, covering core patterns, security best practices, database interactions, hooks\u002Ffilters, Settings API, custom post types, REST API, and AJAX. This skill should be used when creating WordPress plugins, troubleshooting security issues, implementing custom post types\u002Ftaxonomies, building admin interfaces, or working with the WordPress database.\n\nUse when: Creating new WordPress plugins, implementing nonces\u002Fsanitization\u002Fescaping, working with $wpdb and prepared statements, building Settings API pages, registering custom post types or taxonomies, implementing REST API endpoints, handling AJAX requests, debugging plugin activation\u002Fdeactivation issues, preventing SQL injection\u002FXSS\u002FCSRF vulnerabilities.\n\nKeywords: wordpress plugin development, wordpress security, wordpress hooks, wordpress filters, wordpress database, wpdb prepare, sanitize_text_field, esc_html, wp_nonce, custom post type, register_post_type, settings api, rest api, admin-ajax, wordpress sql injection, wordpress xss, wordpress csrf, plugin header, activation hook, deactivation hook, wordpress coding standards, wordpress plugin architecture","https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fwordpress-plugin-core\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":94,"licenseFileUrl":95,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":18},"01M7AQH4JW8F2MJFS1C43TZ2TY","webapp-testing","Test local web applications with Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, or inspect browser logs.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fwebapp-testing\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fwebapp-testing\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":18},"01M7AQH0PWD6Z1NN66V15DT25M","web-performance-audit","Audit web performance using Chrome DevTools MCP. Use when asked to audit, profile, debug, or optimize page load performance, Lighthouse scores, or site speed.","https:\u002F\u002Fgithub.com\u002Fdavidanthonyn\u002Fagent-skills\u002Fblob\u002Fmain\u002Fweb-performance-audit\u002FSKILL.md",[],[]]