Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Clerk Authentication · terminalskills | DecimalAI

terminalskills/clerk-auth

SkillScore86Maintained

Add authentication to web apps with Clerk — social login, email/password, magic links, organizations, RBAC, session management, webhooks, and multi-framework support. Use when tasks involve user authentication, team/org management, role-based access control, or integrating auth into Next.js, React, Remix, or Express applications.

codingby terminalskills

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Coding pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/terminalskills-clerk-auth/SKILL.md

decimalai skills pull terminalskills-clerk-auth --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/terminalskills-clerk-auth/SKILL.md https://app.decimal.ai/s/terminalskills-clerk-auth/SKILL.md

Raw file: /s/terminalskills-clerk-auth/SKILL.md ↗ · machine-readable summary at /s/terminalskills-clerk-auth.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 54d ago

Yes — +32% lift · at higher cost+62% tokens0% turns86% of whole cases pass with skill (19/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-10	✗→✓	▲ Improved	72%	0%
case-02	✗→✓	▲ Improved	35%	0%
case-04	✗→✓	▲ Improved	60%	0%
case-11	✗→✓	▲ Improved	21%	0%
case-05	✗→✓	▲ Improved	114%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/1/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

terminalskills / skills

skills/clerk-auth/SKILL.md

View on GitHub ↗

License Apache-2.0Imported 8/1/2026Version v1

Skill contents

SKILL.md

Clerk Authentication

Drop-in authentication for modern web apps. Handles login UI, social providers, session management, organizations, and RBAC.

Setup (Next.js)

bash
npm install @clerk/nextjs

env
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_SECRET_KEY=sk_live_...

typescript
// app/layout.tsx — Wrap app in ClerkProvider
import { ClerkProvider } from '@clerk/nextjs';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <ClerkProvider>
      <html><body>{children}</body></html>
    </ClerkProvider>
  );
}

Middleware (Route Protection)

typescript
// middleware.ts — Protect routes at the edge
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';

const isPublicRoute = createRouteMatcher([
  '/',
  '/pricing',
  '/sign-in(.*)',
  '/sign-up(.*)',
  '/api/webhooks(.*)',
]);

export default clerkMiddleware(async (auth, req) => {
  if (!isPublicRoute(req)) {
    await auth.protect();
  }
});

export const config = {
  matcher: ['/((?!.*\\..*|_next).*)', '/', '/(api|trpc)(.*)'],
};

Server-Side Auth

Server Components (App Router)

typescript
import { auth, currentUser } from '@clerk/nextjs/server';

export default async function Page() {
  // Quick access to IDs and role
  const { userId, orgId, orgRole } = await auth();

  // Full user object when needed
  const user = await currentUser();

  return <p>Hello {user?.firstName}</p>;
}

API Routes

typescript
import { auth } from '@clerk/nextjs/server';
import { NextResponse } from 'next/server';

export async function GET() {
  const { userId, orgId } = await auth();
  if (!userId) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  // ... fetch data scoped to orgId
}

Server Actions

typescript
'use server';
import { auth } from '@clerk/nextjs/server';

export async function createProject(name: string) {
  const { userId, orgId, orgRole } = await auth();
  if (!orgId || (orgRole !== 'org:admin' && orgRole !== 'org:owner')) {
    throw new Error('Forbidden');
  }
  return db.projects.create({ data: { name, orgId, createdBy: userId } });
}

Client-Side Auth

typescript
'use client';
import { useAuth, useUser, useOrganization } from '@clerk/nextjs';

export function ProfileCard() {
  const { isSignedIn, userId } = useAuth();
  const { user } = useUser();
  const { organization, membership } = useOrganization();

  if (!isSignedIn) return <p>Not signed in</p>;

  return (
    <div>
      <p>{user?.fullName}</p>
      <p>Org: {organization?.name}</p>
      <p>Role: {membership?.role}</p>
    </div>
  );
}

Pre-Built Components

typescript
import {
  SignIn,             // Full sign-in page
  SignUp,             // Full sign-up page
  UserButton,         // Avatar dropdown (profile, sign out)
  UserProfile,        // Full profile management page
  OrganizationSwitcher,  // Org dropdown + create org
  OrganizationList,      // List orgs + join/create
  OrganizationProfile,   // Org settings (members, roles)
} from '@clerk/nextjs';

// Sign-in page
// app/sign-in/[[...sign-in]]/page.tsx
export default function SignInPage() {
  return <SignIn />;
}

// Header with org switcher and user menu
export function Header() {
  return (
    <nav>
      <OrganizationSwitcher hidePersonal={true} />
      <UserButton afterSignOutUrl="/" />
    </nav>
  );
}

Organizations (Multi-Tenant)

Enable at dashboard.clerk.com → Organizations.

Create Organization

typescript
import { auth, clerkClient } from '@clerk/nextjs/server';

async function createOrg(name: string) {
  const { userId } = await auth();
  const client = await clerkClient();
  return client.organizations.createOrganization({
    name,
    createdBy: userId!,
  });
}

Invite Members

typescript
async function inviteMember(orgId: string, email: string, role: string) {
  const client = await clerkClient();
  return client.organizations.createOrganizationInvitation({
    organizationId: orgId,
    emailAddress: email,
    role,  // 'org:admin', 'org:member', or custom roles
    inviterUserId: (await auth()).userId!,
  });
}

Custom Roles

Define at dashboard.clerk.com → Organizations → Roles:

org:owner    — Full access, can delete org
org:admin    — Manage members, settings
org:member   — Standard access
org:viewer   — Read-only (custom)
org:billing  — Billing management only (custom)

Check roles in code:

typescript
const { orgRole, has } = await auth();

// Direct role check
if (orgRole === 'org:admin') { ... }

// Permission-based check (preferred — decouples code from role names)
if (has({ permission: 'org:projects:manage' })) { ... }

Webhooks

Sync Clerk events to your database:

typescript
// app/api/webhooks/clerk/route.ts
import { Webhook } from 'svix';
import { WebhookEvent } from '@clerk/nextjs/server';

export async function POST(req: Request) {
  const wh = new Webhook(process.env.CLERK_WEBHOOK_SECRET!);
  const body = await req.text();
  const svixHeaders = {
    'svix-id': req.headers.get('svix-id')!,
    'svix-timestamp': req.headers.get('svix-timestamp')!,
    'svix-signature': req.headers.get('svix-signature')!,
  };

  const event = wh.verify(body, svixHeaders) as WebhookEvent;

  switch (event.type) {
    case 'user.created':
      await db.users.create({ data: {
        clerkId: event.data.id,
        email: event.data.email_addresses[0]?.email_address,
        name: `${event.data.first_name} ${event.data.last_name}`.trim(),
      }});
      break;
    case 'user.deleted':
      await db.users.delete({ where: { clerkId: event.data.id } });
      break;
    case 'organization.created':
      await db.orgs.create({ data: {
        clerkOrgId: event.data.id,
        name: event.data.name,
        slug: event.data.slug,
      }});
      break;
  }

  return new Response('OK');
}

Key events: user.created, user.updated, user.deleted, organization.created, organization.updated, organizationMembership.created, organizationMembership.deleted.

JWT Templates (API Auth)

For external APIs or microservices that need to verify Clerk tokens:

typescript
// Configure at dashboard.clerk.com → JWT Templates
// Template name: "api-token"
// Claims: { "userId": "{{user.id}}", "orgId": "{{org.id}}", "role": "{{org.role}}" }

// Client: get a custom JWT
const { getToken } = useAuth();
const token = await getToken({ template: 'api-token' });

// External API: verify the JWT
import { createClerkClient } from '@clerk/backend';
const clerk = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY });

async function verifyRequest(req: Request) {
  const token = req.headers.get('Authorization')?.replace('Bearer ', '');
  if (!token) throw new Error('No token');
  return clerk.verifyToken(token);
}

Express.js

typescript
import { ClerkExpressRequireAuth } from '@clerk/clerk-sdk-node';

// Protect routes
app.use('/api', ClerkExpressRequireAuth());

app.get('/api/me', (req, res) => {
  res.json({ userId: req.auth.userId, orgId: req.auth.orgId });
});

Guidelines

Middleware is the primary protection layer — don't rely on component-level checks alone. Middleware runs at the edge before any page code.
Use auth() in server components, not useAuth() — server-side checks can't be bypassed by the client
Webhook signature verification is mandatory — use svix library to verify every webhook payload
Sync to your database via webhooks — don't query Clerk's API for every database operation. Keep a local copy of users and orgs.
Use organizations for B2B — even if you think you only need simple auth now. Adding multi-tenancy later is much harder than starting with it.
Permission-based checks over role checks — has({ permission: 'X' }) is more maintainable than role === 'org:admin'
hidePersonal={true} for B2B apps — personal workspaces confuse users in team-based products
Configure sign-in/up URLs in env vars — Clerk uses these for redirects after auth flows

Illustrative Want to see what terminalskills/clerk-auth would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/4/2026, 22:33 UTC · 22 cases

Lift

+32%

86% vs 55%

Agent turns

1.0 vs 1.0

Tokens

+62%

3,563.41 vs 2,197.86

fail → pass · 7pass → pass · 12fail → fail · 3

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-10 Write a TypeScript server function that sends an invitation to join an organization using backend SDK methods given an organization ID, recipient email, and role.	fail→pass	10,056	6,383	-37%	1	1	0%	2,110	3,623	+72%	0	0	—
case-01 Write the root layout component for a Next.js App Router application integrating authentication. Show how to wrap the layout hierarchy using @clerk/nextjs to enable context across client components.	pass→pass	8,357	9,749	+17%	1	1	0%	1,743	3,706	+113%	0	0	—
case-02 Write a Next.js middleware file in TypeScript that guards non-public endpoints at the edge. Configure public route matching for root, pricing, sign-in, sign-up, and webhooks, ensuring unauthenticated requests to protected paths are stopped.	fail→pass	11,869	5,266	-56%	1	1	0%	2,556	3,451	+35%	0	0	—
case-03 Create a Next.js App Router server component page in TypeScript that extracts the authenticated user ID and organization ID without pulling down the full user object payload.	pass→pass	11,708	5,038	-57%	1	1	0%	2,338	3,345	+43%	0	0	—
case-04 Write a Next.js App Router server component that displays the logged-in user's first name by fetching the complete user record on the server.	fail→pass	9,240	4,283	-54%	1	1	0%	1,889	3,018	+60%	0	0	—
case-11 Demonstrate how to write an authorization check in a Next.js server context using helper utilities, preferring explicit permission checks over static role string comparisons.	fail→pass	16,326	8,974	-45%	1	1	0%	3,556	4,301	+21%	0	0	—
case-05 Create a Next.js API Route Handler for GET requests that checks session context and returns an HTTP 401 response if no active user session exists.	fail→pass	9,174	3,482	-62%	1	1	0%	1,397	2,984	+114%	0	0	—
case-06 Write a Next.js Server Action named createProject in TypeScript that verifies the user belongs to an organization as an admin or owner before writing to the database.	fail→fail	11,410	6,113	-46%	1	1	0%	2,800	3,589	+28%	0	0	—
case-07 Write a client-side React component named ProfileCard using authentication client hooks to display the user's full name, current organization name, and active membership role.	pass→pass	12,859	5,659	-56%	1	1	0%	2,872	3,604	+25%	0	0	—
case-08 Create a navigation header component for a multi-tenant B2B application using pre-built UI components. Include an organization switcher component configured so users cannot select personal account workspaces.	fail→pass	18,750	6,113	-67%	1	1	0%	4,301	3,643	-15%	0	0	—
case-09 Write a TypeScript server function that creates a new organization using backend SDK methods, setting the current authenticated user as creator.	pass→pass	11,447	5,071	-56%	1	1	0%	2,414	3,339	+38%	0	0	—
case-12 Create a Next.js App Router API Route Handler (POST /api/webhooks/clerk) that validates incoming webhook HTTP headers for signature authenticity using Svix.	pass→pass	10,142	9,240	-9%	1	1	0%	2,365	4,585	+94%	0	0	—
case-13 Write a TypeScript webhook handler switch block that processes user creation, user deletion, and organization creation webhook events to synchronize records to a database.	pass→pass	11,344	9,267	-18%	1	1	0%	2,409	3,915	+63%	0	0	—
case-14 Write a client-side React code snippet that retrieves a custom JWT token named api-token using client hooks to authorize calls to a separate microservice.	fail→pass	11,966	5,891	-51%	1	1	0%	1,950	3,709	+90%	0	0	—
case-15 Write a backend token verification function for a standalone Node.js service using @clerk/backend to validate incoming bearer tokens.	fail→fail	11,165	7,521	-33%	1	1	0%	2,234	3,976	+78%	0	0	—
case-16 Write an Express.js router setup that protects all routes under /api using official Node SDK auth middleware.	fail→fail	10,557	6,701	-37%	1	1	0%	2,123	3,765	+77%	0	0	—
case-17 Create a Next.js App Router catch-all page file app/sign-in/[[...sign-in]]/page.tsx that renders the standard pre-built sign-in flow UI.	pass→pass	5,604	7,161	+28%	1	1	0%	1,236	2,893	+134%	0	0	—
case-18 List the standard environment variable names required for configuring frontend publishable keys and backend secret keys in a Next.js application.	pass→pass	7,316	3,182	-57%	1	1	0%	1,633	2,907	+78%	0	0	—
case-19 Provide the exported matcher configuration object for middleware.ts in Next.js to bypass static files and internal Next.js assets while matching pages and API routes.	pass→pass	6,798	3,480	-49%	1	1	0%	1,397	2,934	+110%	0	0	—
case-20 Write a Next.js middleware file using @auth0/nextjs-auth0 to protect routing and enforce session cookie validation.	pass→pass	9,219	10,829	+17%	1	1	0%	1,899	4,131	+118%	0	0	—
case-21 Write a Prisma schema definition specifying a one-to-many relationship between User and Post models with cascading deletion on post author.	pass→pass	7,097	4,092	-42%	1	1	0%	811	3,106	+283%	0	0	—
case-22 Create a Next.js API Route Handler in TypeScript that receives Stripe webhooks and validates event signatures using stripe.webhooks.constructEvent.	pass→pass	11,109	8,253	-26%	1	1	0%	2,320	3,871	+67%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted. The headline lift of +32 percentage points is the difference between those two pass rates over the 22 comparable cases.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 54.6%
Pass rate with the skill: 86.4%
Cases attempted: 22
Cases counted toward lift: 22
Cases that regressed: 0
Skill version measured: v1
Run completed: 8/4/2026, 22:33 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-10

Prompt

Write a TypeScript server function that sends an invitation to join an organization using backend SDK methods given an organization ID, recipient email, and role.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run86

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+81% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 54 days ago

Other measured skills in the registry, with their headline benchmark lift.