Kipt

Next.js cache components optimizer skill: make routes instant

next-cache-components-optimizer is the official Next.js skill that grows a route's static shell, proven by a failing instant() test that it turns green.

By the Kipt team · Updated 24 October 2026

Source: vercel/next.js · Maintainer: Vercel · License: MIT · Checked: 24 October 2026

What is the next-cache-components-optimizer skill?

next-cache-components-optimizer is the official Next.js skill for making a route feel instant. It has a coding agent write a failing test that says which UI should appear right away, refactor the route until that test passes, and keep the test as a guard against regressions. It works on initial loads and client-side navigations, and with Claude Code, Codex, Cursor and other agents that read the SKILL.md format.

The skill lives in the skills/ folder of the vercel/next.js repo. The Next.js AI coding agents guide says it "expands a target route's static shell to include the useful UI you want available on an initial load."

Its description opens: "Optimize the meaningful UI available immediately from a Next.js route on an initial load (hard navigation) or named client-side navigation (soft navigation)." It ends: "Requires Next.js 16.3+ with Cache Components already adopted."

As of 24 October 2026, its skills.sh page listed 18.6K installs (snapshot, 24 October 2026).

What does it do?

The skill is test-driven. The SKILL.md works through phases in order, each ending in a gate:

Phase What happens
P, prerequisites Confirms Next.js 16.3+ with cacheComponents: true and a matching @next/playwright
0, setup Once per repo, works out how you build, deploy, sign in and test, and writes a committed instant-nav.rig.md
A, rig Stands up a production build with the testing API exposed
B, baseline Without the lock, confirms the shell marker renders for the test user (deleted before the PR)
C, red Wraps the navigation in instant() and shows the shell does not commit, then checks the failure is trustworthy
D, fix Applies the matching pattern from the Next.js static shell guide until the test passes
E, parity Confirms the route renders the same content, redirects and state as before
F, differential Reverts only the fix to see it fail, then re-applies it to see it pass
G, review Works through a PR checklist

How it measures. instant() from @next/playwright holds back dynamic data during a navigation, so a correctly built route still shows its static shell. The skill calls it "a ruler, not a stopwatch" and avoids hand-timed tests. The Instant navigation guide documents the same testing approach.

How it fixes. Phase D points to the Next.js Optimizing the static shell guide: keep static UI in the shell, push data access down, design loading states, and cache reusable work. A common change is moving a data read below a <Suspense> boundary. It must keep the route's data source, freshness and authorization, and it may not use export const instant = false or ship an empty shell to pass.

How it reports. The skill runs unattended and stops only for a real decision, such as a fix that changes behavior or a security-sensitive read. It reports in terms of what you see, for example which parts of the dashboard now paint instantly and which stream in, rather than test jargon.

What's in the folder:

  • SKILL.md: the phases, gates and PR checklist.
  • rig-template.md: how to set up the production build, test context and loop, recorded in instant-nav.rig.md.
  • test-template.md: the instant() specs for soft and hard navigations, plus the throwaway baseline.
  • reference/red-test-robustness.md: how to tell a trustworthy failing test from one that fails for the wrong reason.

How do you install it?

The Next.js docs give this command for the skills CLI:

npx skills add vercel/next.js --skill next-cache-components-optimizer

skills.sh shows the same install with the full URL, npx skills add https://github.com/vercel/next.js --skill next-cache-components-optimizer. Add -g for all projects or -a claude-code to target Claude Code. In Claude Code the folder lands in .claude/skills/next-cache-components-optimizer/, or ~/.claude/skills/next-cache-components-optimizer/ with -g, per the Claude Code skills docs. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

Your app also needs the testing setup the skill expects. Its prerequisites are cacheComponents: true in next.config.ts, @next/playwright installed alongside @playwright/test, and the testing API flag gated to test builds only, for example:

experimental: {
  exposeTestingApiInProductionBuild: process.env.EXPOSE_TESTING_API === '1',
}

If the repo has no Playwright suite, the skill sets up a minimal one during phase 0.

How do you use it?

Name one route, the entry point (initial load or a click from another page), and the UI that should appear immediately.

The Next.js docs suggest a prompt like:

Optimize the static shell for /dashboard using the next-cache-components-optimizer Skill. On an initial load, the header and project list should be available immediately.

More example prompts (suggestions, not quotes from the docs):

  • Clicking from /projects to /projects/[id] waits before anything paints. Make the project header and tabs instant on that navigation.
  • Which Suspense boundary is blocking the settings page shell? Find it with a failing instant() test before changing code.
  • Add instant() regression coverage for the home page shell without refactoring anything yet.

Requirements: Next.js 16.3 or later with Cache Components already adopted, @next/playwright matching your next version, a production build you can run (local next build && next start, CI or a preview deploy), and a test account the suite can sign in as.

Tips and limits

  • Never measure on next dev. The skill says dev "does not prefetch, and its lock is unreliable for blocking routes."
  • Watch for vacuous passes. If the build doesn't expose the testing API, instant() "silently no-ops and the test passes vacuously." The phase C failure is what proves the lock works.
  • Instant does not mean fresh. The skill notes that instant() "proves readiness, not mutation freshness," so new caches need a mutation test.
  • Partial Prefetching is a different job. For URL-specific content on an already instant destination, it hands off to next-partial-prefetching-optimizer.
  • It commits files. Expect a new instant-nav.rig.md, an instant() test per guarded navigation, and the route refactor.
  • Security audit. On 24 October 2026 its skills.sh page showed Gen Agent Trust Hub: Pass, Socket: Pass, Snyk: Pass.

The vercel/next.js repo is MIT licensed, so you can copy and adapt the skill if you keep the copyright notice.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md along with both templates and the reference/ file. Import next-cache-components-adoption or next-dev-loop the same way if your workflow uses them. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Vercel or the Next.js team.

Similar skills

Questions

What is the next-cache-components-optimizer skill?

It is an official Agent Skill from the Next.js team, kept in the vercel/next.js repo. It makes the useful UI on a Next.js route appear immediately on an initial load or client navigation. It writes a failing @next/playwright instant() test, refactors the route until the test passes, and ships the test as a regression guard.

How do I install the Next.js cache components optimizer skill?

The Next.js docs give npx skills add vercel/next.js --skill next-cache-components-optimizer. skills.sh shows the same install with the full GitHub URL. Add -g for every project or -a claude-code to target Claude Code.

What does the skill require?

Next.js 16.3 or later with cacheComponents: true in next.config.ts, and @next/playwright on the same release line as next. It also needs a production build with experimental.exposeTestingApiInProductionBuild turned on for test builds only. The skill says never to measure on next dev.

Should I use it before adopting Cache Components?

No. The SKILL.md says to reach for it once the app builds under Cache Components. For the migration itself, the Next.js team has a separate next-cache-components-adoption skill that turns the flag on and fixes blocking routes one feature at a time.

What does instant() test?

instant() comes from @next/playwright. It holds back dynamic data while a navigation runs, so a test can assert that the route's static shell still appears. The skill calls it a ruler, not a stopwatch: it checks that the shell commits under the lock, not how many milliseconds it takes.

More in Skill directory

All guides

Keep your prompts and skills in one place, in your own GitHub. Install every skill with one command.

Get started

Kipt is an independent product, not affiliated with or endorsed by Anthropic, OpenAI, Cursor or GitHub. Claude, ChatGPT, Codex, Cursor and GitHub are trademarks of their owners.