clerk-nextjs-patterns Skill for Claude: What It Does and How to Install It

Makes Claude use Clerk correctly in Next.js, from route protection to Server Actions and caching.

Installs: 54.6K; on skills.sh
Stars: 89; on GitHub
Files: 12; besides SKILL.md
Updated: Oct 2026; last repo commit

This is Clerk's own skill for Next.js patterns. It teaches Claude which auth API to use on the server and the client, how to protect each page, Server Action and API route, how to cache per user, and how to pass the Suspense rules that Cache Components enforce.

The folder holds SKILL.md, 5 reference files, an evals file and a small starter app, 13 files in all. It bundles no scripts. It expects Clerk to be installed already.

Good for

Next.js developers who already have Clerk installed
Teams protecting routes, Server Actions and API handlers
Anyone fixing next build errors from Cache Components

Install clerk-nextjs-patterns

Claude Code

Copy this prompt.

Install the clerk-nextjs-patterns skill in Claude Code. Run this command:

/plugin marketplace add clerk/skills
/plugin install clerk@clerk-skills

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route. The Clerk plugin installs all 20 skills in the repo plus the hosted Clerk MCP server (mcp.clerk.com/mcp) from its .mcp.json; the skills CLI routes install skills only. Per the README, the clerk plugin replaces the earlier clerk-skills@clerk Codex plugin and the earlier core, frameworks, features and mobile Copilot plugins, and Copilot may leave clerk@clerk-skills disabled until you run copilot plugin enable clerk@clerk-skills. This skill points to the clerk skill for the SDK version table, so the skills CLI command here installs both.

From the project README. Source.

What's in the skill

When it loads

Advanced Next.js patterns - middleware, Server Actions, caching with Clerk.

Sections in SKILL.md

What Do You Need?
References
Mental Model
Minimal Pattern
Conditional Rendering with <Show>
Cache Components
Common Pitfalls
Session Tokens & Custom JWTs
getToken() for external APIs
useSession() for session data
Manual JWT verification (no Clerk middleware)
See Also
Docs

Key facts

Author: Clerk (vendor's own repo)
Repo: clerk/skills
License: MIT (README, plugin.json and the SKILL.md frontmatter say MIT; the repo has no LICENSE file)
Installs on skills.sh: 54,569 (Nov 2, 2026)
GitHub stars: 89 for the whole repo (Nov 2, 2026)
Last repo commit: Oct 30, 2026
Audits on skills.sh: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
What it includes: 13 files including SKILL.md: 5 markdown references, an evals file and a 6-file starter Next.js app. It bundles no scripts
Part of: Plugin clerk: 20 skills plus the Clerk MCP server
Needs: Clerk installed (clerk-setup); the clerk skill for the version table

What it includes

await auth() on the server, useAuth() hooks on the client; never mixed
Reference: references/server-vs-client.md.
Write · Server vs client auth
Call auth.protect() in every page and handler; keep clerkMiddleware() bare
Reference: references/middleware-strategies.md. SKILL.md says createRouteMatcher is deprecated in @clerk/nextjs 7.
Try: “Protect this page with auth.protect()”
Write · Route protection
Check auth at the start of every Server Action
Reference: references/server-actions.md.
Write · Server Actions
Return 401 when not signed in and 403 when not allowed
Reference: references/api-routes.md.
Write · API route auth
Pass the userId into use cache functions so users never share cache entries
Reference: references/caching-auth.md.
Write · Auth-aware caching
Render by sign-in state, feature, permission, plan or role
Write · Show component
Wrap auth reads in Suspense so next build passes
Use next build --debug-prerender to list every failing route.
Write · Cache Components fixes
getToken for external APIs; verifyToken or jsonwebtoken for standalone servers
Write · Custom JWTs and manual verification
Seven symptoms with causes and fixes
Common pitfalls table

From the official docs

Permissions

Low risk

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It edits your auth code
Claude changes route protection, Server Actions and API handlers. Mistakes here can expose pages or data, so work on a branch and test signed-out requests before you merge. github.com
The folder includes a starter app
templates/nextjs-basic-auth is a small Next.js app (package.json, proxy.ts, layout and page files) that pins specific versions. Treat it as an example, not something to copy blindly. github.com
The Clerk plugin also adds an MCP server
The plugin bundles .mcp.json, which registers the hosted Clerk MCP server at mcp.clerk.com/mcp. plugin.json lists no hooks. The skills CLI and folder routes do not add it. github.com

Technical details

Turning on read-only	There is no read-only switch. Claude writes code into your project.
Talks to	clerk.com
Sign-in and keys	SKILL.md names NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY, plus CLERK_JWT_KEY or CLERK_PEM_PUBLIC_KEY for manual JWT verification.
Scopes	Edits Next.js middleware (proxy.ts), pages, Server Actions and API routes Fetches Clerk documentation pages with WebFetch

Questions

What does the clerk-nextjs-patterns skill do?

It makes Claude use Clerk correctly in a Next.js app: server vs client auth, route protection, Server Actions, API routes, caching and the Suspense rules that Cache Components need.

How do I install clerk-nextjs-patterns?

Use the install box above. The Clerk plugin installs all 20 skills. With the skills CLI, name the clerk skill too, because this skill uses its version table.

Why does next build fail with "uncached or runtime data during prerendering"?

With cacheComponents on, reading auth() or currentUser() outside a Suspense boundary fails the build. SKILL.md says to wrap the auth-dependent UI in Suspense, or add a loading.tsx next to a page that gates with auth.protect().

Should I use createRouteMatcher?

No for new code. SKILL.md says it is deprecated in @clerk/nextjs 7 and to call auth.protect() in each page instead. Projects that already use it can keep it working.

Does it work with older Clerk versions?

Yes, with callouts. Core 2 differences are marked inline, such as isAuthenticated not existing. Check the SDK version in package.json first.

How is it different from clerk-setup?

clerk-setup installs Clerk into a project. This skill covers patterns after that. SKILL.md sends basic setup to clerk-setup.

Is it safe?

It bundles no scripts. It edits your auth code, and mistakes there can expose pages. Our advice: test signed-out requests to every protected route after Claude changes it.

Does it work in the Claude app?

The README documents Claude Code, Codex, Cursor, GitHub Copilot CLI and the skills CLI. It documents no Claude app upload route, so use one of those.

Is it an official Clerk skill?

It is in Clerk's own repo, and the repo's marketplace.json describes the plugin as "Official Clerk skills for AI coding agents".

Information

updated Nov 2, 2026

Repository: clerk/skills
Folder: skills/clerk-nextjs-patterns

clerk/skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 5

clerk/skills README · github.com
clerk/skills marketplace.json · github.com
clerk plugin.json · github.com
clerk/skills .mcp.json · github.com
clerk-nextjs-patterns SKILL.md · github.com