# Next.js Skills: official workflows for Next.js apps (vercel/next.js) — skill card for AI agents

> AgentGid skill card. Checked on 2026-10-27 against commit 6352f41 (version 0.1.0).
> Every fact comes from the pack's own files at that commit. Numbers marked "as reported" are the author's.
> Human page: https://agentgid.com/skills/vercel/next.js/

> Note: the pack has changed since this check; re-read its files before relying on details.

## Explain it to a non-programmer
Six step-by-step playbooks from the Next.js team for your AI coding assistant. They help it switch your Next.js app to newer speed features, find what makes pages slow to load, and check every change in a real browser. The same repo also holds 21 skills for people who work on Next.js itself; you can ignore those.

## Who it is for
- You build a site or app with Next.js and use an AI coding assistant such as Claude Code, Codex or Cursor
- You want to turn on Cache Components or Partial Prefetching and have the assistant fix the pages it flags
- Your pages feel slow on first load or when clicking links, and you want a report of why
- You want the assistant to check each change in a running app, not only that the code builds
- Not for: Your app uses only the older pages/ folder: the Cache Components skill stops and says that move is a separate project
- Not for: You are on Next.js older than 16.3: most skills ask you to upgrade first
- Not for: You don't use Next.js: the skills are about Next.js only

## What it is
- Kind: knowledge, scripts
- License: MIT
- Repository: https://github.com/vercel/next.js

## What it does
- Check every edit in the running app: next-dev-loop asks Next.js itself (its built-in /_next/mcp endpoint) and a real Chrome (agent-browser) whether the page compiles, runs without errors and looks right.
- Work in small, checked steps: one part of the app at a time, a passing dev check and a passing build before moving on.
- Prove speed with a test, not a stopwatch: the optimizers first write a Playwright instant() test that fails, fix the page until it passes, and keep the test.
- Follow the official docs: each error links a docs page, and the skills tell the assistant to read it before fixing.
- Audit before fixing: next-bundle-optimizer only reports unless you ask it to change the app.
- Hand-offs between skills: adoption first, then the optimizers; each skill says which one comes next.
- Never cuts: your app's existing data source, freshness, login and permission checks, redirects and error states; the optimizers must leave the page looking and behaving the same

## Skills
| Skill | Call | Changes code? | In plain words |
|---|---|---|---|
| next-dev-loop | plain language ("After every edit, verify the page still works at runtime using the next-dev-loop Skill.") | no | Checks each change in your running app through Next.js and a real browser |
| next-bundle-optimizer | plain language ("Use the next-bundle-optimizer skill to produce a report ...") | yes | Finds what makes your pages heavy to load; reports by default, fixes only when you ask |
| next-cache-components-adoption | plain language ("Adopt Cache Components in this project using the next-cache-components-adoption Skill.") | yes | Turns on Cache Components and fixes the pages that block it, one part of the app at a time |
| next-cache-components-optimizer | plain language ("Optimize the static shell for /dashboard using the next-cache-components-optimizer Skill ...") | yes | Makes the useful part of one page appear at once, and adds a test that keeps it that way |
| next-partial-prefetching-adoption | plain language ("Adopt Partial Prefetching in this project using the next-partial-prefetching-adoption Skill.") | yes | Moves your links to Partial Prefetching without losing what they already load ahead of the click |
| next-partial-prefetching-optimizer | plain language ("Make the product title instant when navigating from /products to /products/[id] ...") | yes | Decides what a chosen link loads before the click, and locks it in with a test |
| authoring-skills | loaded automatically (hidden from the / menu) | yes | How to write new skills for the Next.js codebase |
| backport-pr | $backport-pr | yes | Copies a merged fix to an older long-term-support release line |
| create-pr | $create-pr | yes | Makes a branch, pushes it and opens a draft pull request on GitHub |
| dce-edge | $dce-edge | yes | Rules for framework code that must also work in the lightweight edge build |
| deploy-release-test | $deploy-release-test | unclear | Starts the full deployment test suite on GitHub Actions from an internal branch |
| docs-diagrams | /docs-diagrams only (never starts by itself) | yes | Draws light and dark diagrams for the Next.js docs with headless Chrome, no AI images |
| flags | $flags | yes | How to add an experimental feature flag through every layer of the framework |
| gate-tests | loaded automatically (hidden from the / menu) | yes | Marks known-failing tests with @gate instead of quietly skipping them |
| gh-stack | plain language | yes | Splits work into stacked pull requests with GitHub's gh-stack tool (copied from GitHub) |
| insight-error-page | plain language | yes | Writes or checks error help pages for the Next.js dev overlay |
| next-rspack | $next-rspack | yes | Keeps the Rspack bundler packages and their Rust versions up to date |
| pr-status-triage | $pr-status-triage | unclear | Sorts failing checks and review comments on a pull request, worst first |
| react-sync | $react-sync | yes | Builds a local React checkout and copies it into Next.js for testing |
| react-vendoring | $react-vendoring | yes | Rules for the copy of React bundled inside Next.js |
| router-act | loaded automatically (hidden from the / menu) | yes | How to write end-to-end tests that control prefetch timing |
| runtime-debug | $runtime-debug | unclear | Steps to track down bundle size and module loading regressions |
| sandbox-bench | plain language | unclear | Speed comparison of two versions of React or Next.js on paid Vercel Sandbox machines |
| update-docs | plain language | yes | Updates the Next.js documentation to match a code change |
| v8-jit | loaded automatically (hidden from the / menu) | yes | Patterns for fast JavaScript in busy server code paths |
| write-api-reference | plain language | yes | Drafts a Next.js reference page for a function or option |
| write-guide | plain language | yes | Drafts a step-by-step Next.js guide with growing examples |

### next-dev-loop
- Asks for: Your app running with next dev (Next.js 16.3+, Turbopack)
- Asks for: The page address to check
- Asks for: Your login in a visible browser window, if the page needs one
- Gives: A list of the app's pages
- Gives: Build errors, server and browser errors for the page
- Gives: What a user actually sees, checked in the browser
- Gives: Component tree, props and render counts from React DevTools
- Say: "After every edit, verify the page still works at runtime using the next-dev-loop Skill."

### next-bundle-optimizer
- Asks for: The whole app, or one page, package or feature to look at
- Asks for: Audit (report only) or fix
- Gives: Saved before and after snapshots from the Next.js bundle analyzer
- Gives: Ranked candidates with the exact file that pulls each one in
- Gives: In fix mode: one small change at a time, kept only if the number improves and the page still works
- Gives: A report that separates facts from guesses
- Say: "Use the next-bundle-optimizer skill to produce a report of the initial load performance of this site."

### next-cache-components-adoption
- Asks for: An App Router app on Next.js 16.3+ that starts
- Asks for: Your choice: one branch, or a first safe change then one review per feature
- Gives: cacheComponents switched on
- Gives: Pages marked with a to-do opt-out, then fixed one feature at a time (incremental path)
- Gives: A passing build after each feature
- Gives: A table per feature: which page to open and what to look for
- Say: "Adopt Cache Components in this project using the next-cache-components-adoption Skill."

### next-cache-components-optimizer
- Asks for: The page and how users reach it (direct visit or a link click)
- Asks for: What should show at once, for example the header and project list
- Asks for: Next.js 16.3+ with Cache Components already on
- Gives: A setup note for your project's test build (instant-nav.rig.md)
- Gives: A failing instant() test, then the fix that makes it pass
- Gives: Proof: undo the fix and the test fails again
- Gives: One line per page: what shows at once and what streams in
- Say: "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."

### next-partial-prefetching-adoption
- Asks for: Next.js 16.3+ with Cache Components on and a passing build
- Asks for: A production-like build it can run, with the real environment
- Asks for: One branch, or one review per page
- Gives: An audit of every link that prefetches today, as a table
- Gives: Browser tests that pass before and after the switch
- Gives: partialPrefetching switched on and leftover settings removed by the official codemod
- Gives: Marked candidates for extra per-link prefetching, decided with you later
- Say: "Adopt Partial Prefetching in this project using the next-partial-prefetching-adoption Skill."

### next-partial-prefetching-optimizer
- Asks for: The link and the page it opens
- Asks for: What must be ready before the click and what can wait
- Asks for: Cache Components and Partial Prefetching already on
- Gives: One test per link that clicks it and checks the result
- Gives: The smallest change that makes it pass
- Gives: A click-through list: what is ready before the click, what waits, when prefetching starts
- Say: "Make the product title instant when navigating from /products to /products/[id]. Use the next-partial-prefetching-optimizer Skill."

## Know before installing
- Two audiences in one repo: only the six skills in skills/ are meant for your app. The 21 in .agents/skills/ are tagged internal and help with work on Next.js itself; installing them into your app does nothing useful.
- The Cache Components adoption skill tells your assistant to install next-dev-loop without asking you first, also in unattended runs. It only says to tell you if you are present.
- next-dev-loop needs the agent-browser tool installed globally on your computer, and it saves the browser's cookies and local storage so you stay logged in between checks.
- The optimizers and Partial Prefetching adoption run your app as a production build with its real database and secrets, and switch on a testing option. The skills say to keep that option off for real production builds.
- Saving to git stays with you: the adoption skill suggests a save point after each feature but never makes one without your yes.
- Feedback to the Next.js team: next-dev-loop joins Next.js's agent feedback only when you turned that feature on; it is off by default and nothing is sent until you press Send feedback.

## Install (official commands)
- Any agent (skills tool): `npx skills add vercel/next.js --skill next-dev-loop` && `npx skills add vercel/next.js --skill next-bundle-optimizer` && `npx skills add vercel/next.js --skill next-cache-components-adoption` && `npx skills add vercel/next.js --skill next-cache-components-optimizer` && `npx skills add vercel/next.js --skill next-partial-prefetching-adoption` && `npx skills add vercel/next.js --skill next-partial-prefetching-optimizer` — One command per skill; install only the ones you need. The Next.js docs list these commands on the AI Coding Agents page.
- Any agent (skills tool, by folder link): `npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop` — The form the skills themselves use when one skill needs another.
- Claude Code (plugin): The repo ships a Claude Code plugin marketplace named "nextjs" with one plugin, "nextjs", that holds the six app skills. The repo does not print the install commands for it.
- Next.js contributors: The 21 internal skills load from .agents/skills/ (with .claude/skills pointing there) when an agent works inside a Next.js checkout. No install.

## What runs on the user's machine
- Code on the machine: yes (three contributor skills that ship scripts (docs-diagrams, react-sync, sandbox-bench); the six app skills are markdown only)
- Network: True
- Install of the app skills: Markdown files only. No hooks, no scripts, no plugin hooks key.
- App skills at work: They tell your assistant to run commands in your project: next dev, next build, next start, next analyze, Playwright tests and official codemods (npx @next/codemod). These change files in your app.
- App skills at work (network): Your assistant installs tools (agent-browser globally, other Next.js skills, codemods through npx) and fetches Next.js docs pages from nextjs.org for each error.
- next-dev-loop: Talks to your local dev server at /_next/mcp and drives a headless Chrome through agent-browser, which saves cookies and local storage per checkout so the next check stays logged in.
- next-bundle-optimizer: Writes analyzer snapshots and exports them to /tmp/analyze-app-before.jsonl.gz (example path); in Codex it must capture outside the sandbox because it opens a network port.
- Contributor: docs-diagrams: A shell script runs Node and headless Chrome to render diagrams to PNG; the pages load the Inter font from Google Fonts.
- Contributor: react-sync: A shell script builds React from a local React checkout into build/oss-stable and build/oss-experimental.
- Contributor: sandbox-bench: Node scripts start billed Vercel Sandbox machines through the Vercel command line tool and store team and project in ~/.config/sandbox-bench/config.json and a cache in ~/.cache/sandbox-bench.

## Settings
- `NEXT_MCP_URL`: Address of the dev server's /_next/mcp endpoint when next dev does not run on port 3000 (next-dev-loop)
- `AGENT_BROWSER_SESSION`: agent-browser session id for this checkout (next-dev-loop)
- `AGENT_BROWSER_RESTORE`: agent-browser key for saved login state (next-dev-loop)
- `experimental.exposeTestingApiInProductionBuild`: next.config option the optimizers switch on for test builds only
- `SANDBOX_BENCH_CACHE`: cache folder for the contributor sandbox-bench scripts

## Examples (from the pack's own files)
- A next-cache-components-adoption opt-out marker: output format defined in skills/next-cache-components-adoption/SKILL.md
- The test template for an instant page (soft navigation): output format defined in skills/next-cache-components-optimizer/test-template.md
- Prompts from the official docs: output format defined in docs/01-app/02-guides/ai-agents.mdx

## Author's numbers (as reported, not run by AgentGid)
- In the Next.js team's agent evaluations, bundled docs in AGENTS.md reached a 100% pass rate, compared with up to 79% for skill-based approaches (Vercel research linked from the docs; the Next.js docs therefore keep framework knowledge in bundled docs and use skills only for multi-step workflows). Source: vercel/next.js/docs/01-app/02-guides/ai-agents.mdx

## Steps only the person can do
- Choose one branch, or a first pull request plus one review per feature, when the adoption skill asks (skills/next-cache-components-adoption/SKILL.md) Then: The agent follows that plan and checks in after each feature
- Log in to your app in the visible browser window when a page needs a login (skills/next-dev-loop/SKILL.md) Then: The agent continues checks in the same saved browser session
- Provide the app's real environment (database, auth, secrets) for the production run (skills/next-partial-prefetching-adoption/SKILL.md) Then: The agent builds and starts the app and verifies prefetching against it
- Approve each commit the adoption skill suggests (skills/next-cache-components-adoption/SKILL.md) Then: The agent commits only after your yes
- Contributors only: name the Vercel team and project for sandbox-bench, which bills sandbox machines (.agents/skills/sandbox-bench/SKILL.md) Then: The scripts start the benchmark machines under that team and project

## Mistakes to avoid
- Not: Install the skills from .agents/skills/ into your own app. Instead: Install only the six skills in skills/ (the "nextjs" plugin); the rest are for work on Next.js itself. Why: The .agents/skills/ ones are tagged internal and describe the Next.js codebase, not your app
- Not: Run an optimizer on an app that has not adopted Cache Components or Partial Prefetching yet. Instead: Run the adoption skill first, then the optimizer. Why: The optimizers assume the features are already on and send you back to adoption otherwise
- Not: Use next-dev-loop on an app whose dev script runs webpack. Instead: Switch to Turbopack, or use the adoption skill's build-only check if you must stay on webpack. Why: next-dev-loop needs Turbopack's compile check and stops on webpack
- Not: Treat the instant-false codemod's "0 ok" result as a finished adoption. Instead: Read the file count and rerun with the correct app directory if it is zero. Why: A wrong path does not raise an error
- Not: Delete or move the .next folder while next dev is running. Instead: Leave .next in place; give a separate production build its own distDir. Why: The dev server loses its generated state and caches

## What leaves the machine
- Requests for Next.js docs pages linked from each error → nextjs.org, During adoption, for every distinct error. Opt out: No opt-out in the skill; the fetch is part of the workflow
- Package downloads for agent-browser, codemods and other Next.js skills → The npm registry and GitHub (through npm and npx skills add), When the agent installs tools the skills need. Opt out: Install the tools yourself at fixed versions before starting
- An anonymized report about a Next.js issue, which you review first → The Next.js team, through a review form opened in your browser, Only if experimental.agentFeedback is on and you press Send feedback. Opt out: Leave agentFeedback off (the default)
- Contributors only: React or Next.js builds and benchmark runs → Vercel Sandbox machines under your Vercel team (billed), When sandbox-bench runs. Opt out: Do not use sandbox-bench
- Contributors only: a font request while rendering docs diagrams → Google Fonts, When docs-diagrams renders. Opt out: Do not use docs-diagrams

## Lines in the pack aimed at agents (ask the person first)
- "You don't need permission to install `next-dev-loop` itself." (skills/next-cache-components-adoption/SKILL.md): Tell the person before installing any skill or tool, also in unattended runs
- "Install or upgrade `agent-browser`: `npm i -g agent-browser@latest`." (skills/next-dev-loop/SKILL.md): A global install of an unpinned version; ask the person first and pin a version (the skill needs 0.31.1 or later)
- "npx @next/codemod@latest cache-components-instant-false ./app" (skills/next-cache-components-adoption/SKILL.md): Runs the latest codemod from npm and edits files; confirm with the person and check the result with git diff
- "If the agent’s sandbox blocks TCP port binding (as Codex’s does), it MUST run the `next analyze --output` capture outside the sandbox." (skills/next-bundle-optimizer/SKILL.md): Leaving the sandbox needs the person's approval in the agent; ask first

## May I use it like this?
- commercial-app: yes (MIT: keep the copyright and permission notice)
- redistribute-files: yes (MIT: include the copyright and permission notice in copies; gh-stack is copied from GitHub's own pack, check its source for its terms)
- client-work: yes (MIT allows use in work for others)
- inside-app-bundle: yes (The plugin manifest also states MIT; keep the notice)

## Which one to pick
- If You want step-by-step workflows to adopt Cache Components or Partial Prefetching and check them in a running Next.js app: skill:vercel/next.js
- If You want rule books for React, Next.js and React Native code plus page and docs reviews and Vercel deploys: skill:vercel-labs/agent-skills
- If You want a speed, accessibility, search and security audit of any website, not only Next.js: skill:addyosmani/web-quality-skills

## Works well with
- tool:next: The skills work only on Next.js apps, version 16.3 or later
- tool:agent-browser: next-dev-loop drives the browser through agent-browser
- tool:skills: The docs install each skill with npx skills add
- agent:claude-code: The repo ships a Claude Code plugin marketplace with the six app skills

## Works in and needs
- Works in Claude Code: plugin
- Works in Any agent with a skills folder: skills CLI
- Works in Codex: skills folder
- Needs Next.js 16.3 or later: All six app skills need it
- Needs Turbopack: next-dev-loop's compile check works only on Turbopack
- Needs agent-browser 0.31.1 or later: next-dev-loop drives Chrome through it
- Needs @next/playwright: The optimizers and Partial Prefetching adoption write instant() browser tests with it
- Needs The app's real environment (database, auth, secrets): Partial Prefetching is verified on a production run

## How to tell it works
On a Next.js 16.3+ app, install next-bundle-optimizer and say "Use the next-bundle-optimizer skill to produce a report of the initial load performance of this site." You should get a ranked list with the file behind each item, and your app's code should be unchanged, because report-only is the default.

## Related
- vercel-labs/agent-browser
- github/gh-stack

## Safety
Install only from github.com/vercel/next.js (folders skills/ and .agents/skills/) or with the skills tool pointing there. The app skills install other tools (agent-browser, more Next.js skills, codemods) and run production builds with your real secrets; keep the testing option off in real production builds. Skills are instructions your agent follows: read them before installing.
