next-cache-components-optimizer: a Claude skill that makes Next.js routes paint instantly

A Next.js team skill that makes Claude speed up what shows on a route at first paint, and locks the gain in with a Playwright test.

Installs: 19.7K; on skills.sh
Stars: 143.5K; on GitHub
Files: 3; besides SKILL.md
Updated: Nov 2026; last repo commit

The skill makes Claude work one route at a time. It writes a failing @next/playwright instant() test, moves request-time work behind focused Suspense boundaries or caches reusable work, then re-runs the test until it passes. The test stays in your repo as the regression guard. It triggers when you ask for a faster first paint, a non-instant navigation, or instant() coverage.

It needs Next.js 16.3 or newer with Cache Components already adopted. Claude also builds your app for production, starts it, runs Playwright, and records the setup in a committed instant-nav.rig.md. Read the safety notes below before you let it run, because it edits config and installs test packages.

Good for

Next.js developers whose route shows a blank or slow first paint
Teams already on Cache Components (Next.js 16.3+) who want a regression test for instant navigation
Developers who want to know which Suspense boundary blocks useful UI

Install next-cache-components-optimizer

Claude Code

Copy this prompt.

Install the next-cache-components-optimizer skill in Claude Code. Run this command:

npx skills add https://github.com/vercel/next.js --skill next-cache-components-optimizer

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.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Optimize the meaningful UI available immediately from a Next.js route on an initial load (hard navigation) or named client-side navigation (soft navigation). Encode the goal as a failing @next/playwright instant() e2e and work it to green, one verified route and entry point at a time; the shipped test then guards against regression. Use when asked to grow a static shell, fix a slow first paint or non-instant navigation, diagnose which Suspense boundary blocks useful UI, or add instant() regression coverage. Requires Next.js 16.3+ with Cache Components already adopted.

Sections in SKILL.md

What is invariant, and what is yours
Two entry points, two instant UI contracts
Goal
Reporting to the user
The workflow
P. PREREQUISITES: current Next.js with Cache Components
0. SETUP: discover this project's rig, once per repo
A. RIG: a production build with the testing API exposed
B. BASELINE (unlocked): development scaffold, do not ship
C. RED (locked) + the VERIFY-RED gate
D. FIX: apply the documented pattern
E. PARITY: the refactor changed only whether the route is instant
F. DIFFERENTIAL
G. REVIEW (PR checklist)
Driving the navigation in tests
Files

Key facts

Author: The Next.js Team, named as author in the nextjs plugin manifest
License: MIT (plugin manifest)
Needs: Next.js 16.3+ with cacheComponents: true, @next/playwright and @playwright/test
Files: 4 files including SKILL.md: rig-template.md, test-template.md and reference/red-test-robustness.md. No scripts.
Installs on skills.sh: 19,667 as of 2026-11-02
GitHub stars: 143,460 for the whole vercel/next.js repo, 2026-11-02
Last repo commit: 2026-11-01
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass

What it includes

Check for Next.js 16.3+ with cacheComponents: true
If your project does not meet the requirements, the skill points to npx @next/codemod upgrade and enabling cacheComponents in next.config.ts.
Runs code · P. Prerequisites
Discover how you build and test, write instant-nav.rig.md
Inspects package.json, Playwright config, next.config and CI once, then writes the answers to a committed instant-nav.rig.md. Installs a minimal Playwright harness if none exists.
Write · 0. Setup
Production build that exposes the testing API
Never measures on next dev. Wires experimental.exposeTestingApiInProductionBuild to a condition that is true for measured builds and never in real production.
Runs code · A. Rig
Check the page marker renders without the lock
A scaffold test that proves the marker is real and reachable as the test user. The skill says to delete it before the PR.
Runs code · B. Baseline
Write the failing instant() test and verify it fails for the right reason
The locked test is the one that ships. Do not optimize until the red is trustworthy.
Runs code · C. Red and C-gate
Apply the documented static-shell pattern
Keeps static UI in the shell, pushes data access down, designs loading states or caches reusable work, following the Next.js Optimizing the static shell guide.
Write · D. Fix
Confirm only whether the route is instant changed
Checks the same content, redirects, side effects and client state before and after.
Runs code · E. Parity
Revert only the fix to see red, re-apply to see green
Proves the test fails without the fix and passes with it.
Runs code · F. Differential
PR checklist of 7 items
Differential shown, parity confirmed, mutations verified, freshness preserved, existing loading UI reused, shell matches the real render, baseline removed.
Read · G. Review
Check for partial prefetching and name the next skill
Runs an rg search for partialPrefetching in config and app folders, then points to next-partial-prefetching-optimizer or next-partial-prefetching-adoption.
Runs code · After optimization

From the official docs

Permissions

Medium risk

Claude edits your Next.js config, installs test packages, writes files and starts local production builds. Work on a branch and review the config change before merging so the testing API never reaches real production.

What it can do

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

Watch out for

It exposes the Next.js testing API on built apps
The skill wires experimental.exposeTestingApiInProductionBuild to a condition that must never be true in real production. Check the condition it writes before you merge. github.com
It can run an upgrade and install packages
If your project is below the requirements, SKILL.md points to npx @next/codemod upgrade, and the rig file says to install @next/playwright and @playwright/test when absent. Review the diff after it runs. github.com
A remote rig means pushing code
The rig template describes a loop of push, wait for the deployed artifact, then test. Decide whether Claude may push before you set that loop up. github.com

Technical details

Talks to	Package installs for @next/playwright and @playwright/test. Any deployed preview URL you record in the rig file
Scopes	Edits next.config and route files Writes instant-nav.rig.md and Playwright test files Runs builds, a local server and Playwright May install @next/playwright and @playwright/test

Questions

What does next-cache-components-optimizer do?

It makes Claude improve what a Next.js route shows immediately on first load or on a client-side link click. Claude writes an instant() Playwright test that fails first, fixes the route until it passes, and leaves the test in your repo.

Which Next.js version does it need?

Next.js 16.3 or newer with cacheComponents: true in next.config.ts, plus @next/playwright on the same release line as next. The skill says its verdicts are not meaningful on older versions.

How do I install it?

Use the install box at the top of this page. The folder holds SKILL.md and three guide files that SKILL.md points to, so keep them together.

Is it safe to run?

It changes your project, so use a branch. Claude can edit next.config, install @next/playwright and @playwright/test, write test files and instant-nav.rig.md, and run builds and a local server. The skill says to expose the Next.js testing API only on builds you measure and never in real production.

Does it need an API key?

None is named in the skill. Its rig file records how your tests log in, such as a fixture or stored session for a test account, and the skill says to ask you only for details the repository cannot answer.

What is the difference from next-partial-prefetching-optimizer?

This skill grows the static shell that commits instantly. SKILL.md hands off to next-partial-prefetching-optimizer when the shell is already instant and you want extra URL-specific content before the click. That is a separate skill in the same Next.js skills folder.

Information

updated Nov 2, 2026

Repository: vercel/next.js
Folder: skills/next-cache-components-optimizer

vercel/next.js skills.sh

Sources

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

Show all 4

SKILL.md · github.com
rig-template.md · github.com
test-template.md · github.com
red-test-robustness.md · github.com