clerk
π―SkillInstallation
npx skills add g1joshi/agent-skills --skill clerkRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/clerkInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/clerk/ - All projects
~/.claude/skills/clerk/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub βExpert Clerk authentication assistance covering Next.js middleware, React user components, webhooks, and session tokens. Use when integrating Clerk auth, protecting routes, or handling user management.
Clerk
Clerk is a comprehensive user management and authentication service built specifically for the modern web (React, Next.js, Remix). It focuses on providing "Drop-in" UI components (<SignIn />, <UserProfile />) rather than just APIs.
When to Use
- Modern React & Next.js Authentication: Adding drop-in, beautifully designed authentication components to modern frontend stacks.
- B2B SaaS Multi-Tenancy & Organizations: Managing team invites, role assignments, seat limits, and organization switching.
- Passwordless & Passkey Auth: Enabling WebAuthn passkeys, biometric logins, and magic links out of the box.
- Edge-Ready Middleware Verification: Validating JWT session tokens at the network edge (Cloudflare Workers, Next.js Middleware).
Quick Start
// middleware.ts
import { authMiddleware } from "@clerk/nextjs";
export default authMiddleware({});
// layout.tsx
import { ClerkProvider } from '@clerk/nextjs'
export default function RootLayout({ children }) {
return (
<ClerkProvider>
<html><body>{children}</body></html>
</ClerkProvider>
)
}
// page.tsx (Protected)
import { UserButton, currentUser } from "@clerk/nextjs";
export default async function Page() {
const user = await currentUser();
if (!user) return <div>Not signed in</div>;
return <header>Welcome {user.firstName} <UserButton /></header>;
}
Core Concepts
Drop-in Component Architecture (, )
Provides prebuilt, accessible, themed UI components that handle complete auth lifecycles:
// app/layout.tsx
import {
ClerkProvider,
SignInButton,
SignedIn,
SignedOut,
UserButton,
} from "@clerk/nextjs";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<ClerkProvider>
<html lang="en">
<body>
<header className="flex justify-between p-4 border-b">
<h1>Enterprise SaaS</h1>
<SignedOut>
<SignInButton mode="modal" />
</SignedOut>
<SignedIn>
<UserButton afterSignOutUrl="/" />
</SignedIn>
</header>
{children}
</body>
</html>
</ClerkProvider>
);
}
Edge Middleware Session Protection
Protects routes and extracts authenticated user claims at the edge before rendering:
// middleware.ts
import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";
const isProtectedRoute = createRouteMatcher([
"/dashboard(.*)",
"/api/protected(.*)",
]);
export default clerkMiddleware((auth, req) => {
if (isProtectedRoute(req)) {
auth().protect();
}
});
export const config = {
matcher: ["/((?!.*\..*|_next).*)", "/", "/(api|trpc)(.*)"],
};
Multi-Tenant Organizations & Role Checks
Manages multi-organization contexts with granular RBAC permissions:
import { auth } from "@clerk/nextjs/server";
export async function POST() {
const { orgId, orgRole } = auth();
if (!orgId) throw new Error("Unauthorized: Select an organization");
if (orgRole !== "org:admin")
throw new Error("Forbidden: Admin privileges required");
// Execute admin organization mutations
}
Common Patterns
Next.js App Router Route Protection with Clerk Middleware
Problem: Public API endpoints inadvertently exposed without explicit session verification.
Solution:
Enforce route matcher guards in Next.js middleware.ts:
import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";
const isProtectedRoute = createRouteMatcher([
"/dashboard(.*)",
"/api/protected(.*)",
]);
export default clerkMiddleware(async (auth, req) => {
if (isProtectedRoute(req)) await auth.protect();
});
export const config = {
matcher: ["/((?!.*\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
};
Best Practices
Do:
- Verify Webhook Signatures with Svix: Always verify incoming Clerk user lifecycle webhooks using
svixbefore updating local databases. - Use Server-Side
auth()in App Router: ExtractuserIdandorgIdviaauth()in Server Components to eliminate client-side waterfall fetches. - Theme Components with Tailored CSS: Match application design systems using Clerk's
appearanceprop and Tailwind utility variables. - Enable Passkeys by Default: Encourage users to register biometric passkeys to eliminate credential phishing risks.
Don't:
- Expose
CLERK_SECRET_KEYin frontend code: Keep secret keys strictly in server environment variables. - Store database IDs in client state: Treat Clerk's JWT session claims as the single source of truth for the active request.
- Bypass route protection: Always enforce server-side protection in route handlers and middleware; do not rely on UI hiding alone.
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
401 Unauthorized | Middleware not configured. | Ensure middleware.ts matches all routes (/((?!...))). |
Hydration Error | HTML mismatch. | Wrap app in <ClerkProvider>. |
References
More from this repository10
A template skill providing a starter framework for creating new agent skills with structured sections for triggers, quick start examples, and capability descriptions.
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill