--- title: "Next.js 16.3: AI Improvements" description: Actionable errors with paste-ready fix prompts, first-party Skills for the dev loop and Cache Components, and tooling that keeps coding agents in sync with your project. url: "https://nextjs.org/blog/next-16-3-ai-improvements" docs_index: /docs/llms.txt publishedAt: June 26th 2026 authors: - Aurora Scharff - Jude Gao --- As the Next.js 16.3 Preview nears a stable release, we're sharing a series of posts about what's inside. The first post, [Instant Navigations](/blog/next-16-3-instant-navigations), covers the new rendering and prefetching primitives. This second post focuses on AI improvements. Next.js has grown a lot since the App Router went stable, and more and more of that growth is driven by code written through agents like Claude Code, Cursor, and Codex. What would Next.js look like if it were designed primarily for agent-driven development? We're not all the way there yet, but we're getting closer with every release. [Next.js 16](/blog/next-16#nextjs-devtools-mcp) added the DevTools MCP server, and [Next.js 16.2](/blog/next-16-2-ai) brought bundled docs and [`next-browser`](/blog/next-16-2-ai#experimental-agent-devtools), an experimental CLI for letting agents drive a real browser. In Next.js 16.3, we're extending this with: - [**Bundled docs through AGENTS.md**](#bundled-docs-through-agentsmd): Keeps agents reading version-matched docs instead of their training data - [**First-party Skills**](#first-party-skills): Skills that help agents drive multi-step workflows - [**Agent Browser with React introspection**](#agent-browser-with-react-introspection): Drive a real browser and inspect React state from `agent-browser` - [**Actionable errors**](#actionable-errors): Copy the fix you picked from the dev overlay as a paste-ready prompt, mirrored in the terminal and per-rule docs pages - [**A smaller, more focused MCP server**](#a-smaller-more-focused-mcp-server): New tools for build diagnostics, with the knowledge-base ones retired - [**Docs as Markdown**](#docs-as-markdown): Append `.md` to any docs URL for a plain Markdown version ## Bundled docs through AGENTS.md In our previous 16.2 release, we started [bundling](/blog/next-16-2-ai#agent-ready-create-next-app) the Next.js documentation into your project so agents can read it locally. Projects created with `create-next-app` on 16.2 or later already point `AGENTS.md` to those docs. In 16.3, `next dev` writes and updates that pointer automatically, so existing projects stay current as you upgrade. On 16.1 or earlier, run the `agents-md` codemod manually: ```bash filename="terminal" npx @next/codemod@canary agents-md ``` Here's what `next dev` inserts into your `AGENTS.md`: ```md filename="AGENTS.md" # This is NOT the Next.js you know This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices. ``` The block is only written when `next dev` detects an [AI coding agent](/docs/app/guides/ai-agents) in the environment and the markers aren't already there. Anything outside the markers is preserved, and you can opt out with `agentRules: false` in `next.config.ts`. Commit the block as-is, even if it shows up as an uncommitted change. ## First-party Skills Skills give agents framework-specific context. You may have installed our earlier [_knowledge_ Skills](https://github.com/vercel-labs/next-skills) from [skills.sh](https://skills.sh), which covered App Router conventions and caching APIs. With the bundled docs now reaching agents through [the managed AGENTS.md block](#bundled-docs-through-agentsmd), we're retiring those Skills. Run `npx skills update` to remove them from your installed set. Skills are still useful for multi-step _workflows_ that docs alone can't drive end to end. Next.js 16.3 adds three new first-party [Skills](https://github.com/vercel/next.js/tree/canary/skills) for those. ### `next-dev-loop` The [`next-dev-loop` Skill](https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop) gives your coding agent access to the full development feedback loop. It can drive the browser, read the console, follow network requests, and inspect the React tree as it iterates. - **`/_next/mcp`**, the framework's view of routes, server logs, and compilation issues. - **`agent-browser`**, the browser's view of the DOM, console, network, and React tree. The Skill requires [`agent-browser`](#agent-browser-with-react-introspection) version 0.27 or later. ```bash filename="terminal" npx skills add vercel/next.js --skill next-dev-loop ``` Then prompt your agent with something like: ```text After every edit, verify the page still works at runtime using the next-dev-loop skill. ```
Claude editing, compiling, reloading, and inspecting the result through `next-dev-loop`.
### `next-cache-components-adoption` The [`next-cache-components-adoption` Skill](https://github.com/vercel/next.js/tree/canary/skills/next-cache-components-adoption) turns Cache Components on in your project and works through the app one feature at a time, checking in with you at the boundary of each feature so you stay in control of the scope. It works in one of two modes: - **Incremental.** Lands a single mechanical PR up front that opts every route out of validation, so you can ship features as you go in follow-up PRs. - **Direct.** Adopts every route in place on one branch. The per-feature loop is the same in both: the Skill reads the [actionable error](#actionable-errors), fetches the per-error docs page it links to, applies that fix to the route, then drives the browser through [`next-dev-loop`](#next-dev-loop) to confirm the static shell renders the right content. ```bash filename="terminal" npx skills add vercel/next.js --skill next-cache-components-adoption ``` Then prompt your agent with something like: ```text Adopt Cache Components in this project using the next-cache-components-adoption skill. ```
Claude turning Cache Components on and adopting routes one feature at a time.
### `next-cache-components-optimizer` The [`next-cache-components-optimizer` Skill](https://github.com/vercel/next.js/tree/canary/skills/next-cache-components-optimizer) optimizes a Cache Components route for instant navigation, by running an [observe-fix-iterate loop](https://preview.nextjs.org/docs/app/guides/instant-navigation#ai-workflow) against the static shell. Use it whenever you want a route to feel faster, by growing the static shell so more of the page is ready at request time. It works in one of two modes: - **Page-render mode.** Increases how much of a single page can render statically by pushing I/O deeper into the component tree or caching it with `'use cache'`. - **Nav mode.** Ensures navigations between pages are instant. Any server-side work needed for the next page streams in without blocking the navigation. The Skill screenshots before and after each change through [`next-dev-loop`](#next-dev-loop). Identical screenshots roll the change back. ```bash filename="terminal" npx skills add vercel/next.js --skill next-cache-components-optimizer ``` Then prompt your agent with something like: ```text Increase the static shell on /dashboard using the next-cache-components-optimizer skill. ```
Claude growing the static shell of a route, with before/after screenshots to verify the change landed.
## Agent Browser with React introspection The experimental [`next-browser`](/blog/next-16-2-ai#experimental-agent-devtools) from Next.js 16.2 has merged into the general-purpose [`agent-browser`](https://www.npmjs.com/package/agent-browser) CLI. Everything `next-browser` did is now in `agent-browser`, and it works beyond Next.js too. Version 0.27 adds React DevTools introspection on top of the existing DOM, console, network, and Web Vitals access. Agents can list the component tree with `react tree`, inspect a single component with `react inspect `, profile re-renders with `react renders start` and `stop`, and see what's holding a render with `react suspense --only-dynamic --json`. The [`next-dev-loop`](#next-dev-loop) Skill launches `agent-browser` with React DevTools enabled so these commands are available during verification. To install or upgrade, run `npm install -g agent-browser@^0.27`. The React commands require `--enable react-devtools` at launch. ## Actionable errors With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, an `await` on the server is a choice. [Instant Insights](/blog/next-16-3-instant-navigations#stream-cache-or-block) presents that choice as an error with three specific fixes: - **Stream** the data behind a `` boundary - **Cache** it with `"use cache"` - **Block** the route with `export const instant = false` These are product decisions with trade-offs. Picking the right one needs context, whether you or your coding agent is making the choice. ### Instant Insights fix prompts An Instant Insight presents the error with labeled fixes, with a **Copy as prompt** button that packages the chosen fix into a paste-ready prompt for your coding agent. The prompt walks the agent through identifying the failing code, reading the matching error page, applying the canonical pattern, and verifying the result at runtime through the [`next-dev-loop`](#next-dev-loop) Skill. For example, say we hit an uncached `fetch()` call in a page. We pick **Stream** and click **Copy as prompt**, and get:
The prompt your agent can use ```text Apply the [Stream] "Wrap in or move into Suspense" fix to the Next.js Insight raised in this project. Steps: 1. Make sure you can drive a browser before you start. The fix isn't verified until you've reloaded the route and looked at what renders. If you don't already have browser tooling set up, install the next-dev-loop skill (https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop) first. 2. Identify the failing code in the error block below. It may be a data-access call, a hook call, a metadata or viewport export, or a component. Keep the fix focused on that code. If you think a related refactor (a sibling component, a shared layout, a wrapping boundary) would make the result meaningfully better, name it and check with the user before doing it — don't expand the scope silently. 3. Read the rule docs at https://nextjs.org/docs/messages/blocking-prerender-dynamic for the full Insight explanation, then read the fix section at https://nextjs.org/docs/messages/blocking-prerender-dynamic#wrap-in-or-move-into-suspense. Pick the pattern under "### Patterns" that matches the failing code, then read "### Gotchas" before editing — they list constraints that are easy to miss. Use the canonical imports and code shape from the page; don't improvise variations. 4. Apply the chosen pattern to the code identified in step 2. Don't narrate the change with new comments — the code should explain itself. Only leave a comment when the *why* isn't clear (e.g. a deliberate Block with a reason). 5. Verify the fix at runtime. The Insight clearing in the dev overlay confirms the build is happy, but not what actually renders. Reload the route in a browser and confirm the static shell still paints first and any new fallback resolves to its real content. 6. Check the shell isn't empty. A boundary placed too high (around the whole page body, or with `fallback={null}`) can leave the build reporting a shell while the shell itself contains nothing and everything streams. If that's what you see, pull the boundary down closer to the actual dynamic read. 7. If the fix touched shared code (a layout, a wrapper, a sidebar), re-check the sibling routes too — a shell-level change can fix one route and break another. A before/after capture of the affected routes is a useful sanity check: the visible UI may look the same (the fix often just changes what's in the shell vs streamed), but if anything regressed visually, you'll see it. When you reply to the user, just summarize what you changed and why in plain prose. Don't echo this checklist back as headers, sections, or bullet lists labeled "Verification" or "Scope" — those are your internal steps, not the user's report. ## Error Type Blocking Route ## Error Message Route "/products/[slug]": Next.js encountered uncached data during prerendering or a navigation. `fetch(...)` or `connection()` accessed outside of `` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience. at ProductPage (app/products/[slug]/page.tsx:52:32) ## Code Frame 50 | props: PageProps<"/products/[slug]">, 51 | ) { > 52 | const featured = await fetch(`/api/products/${slug}`); | ^ 53 | 54 | return ( 55 |
Next.js version: 16.3.0 (Turbopack) ```
### Structured console output The same fix menu shows up in the terminal during `next dev`, and `next build` emits it when an error stops a prerender. That means an agent reading errors from `next build`, CI logs, or any terminal session where the dev overlay isn't available still gets the same labeled fixes, linked to the matching section of the error page: ```text filename="terminal" Error: Route "/products/[slug]": Next.js encountered uncached data during prerendering or a navigation. `fetch(...)` or `connection()` accessed outside of `` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience. Ways to fix this: - [stream] Provide a placeholder with `` around the data access https://nextjs.org/docs/messages/blocking-prerender-dynamic#wrap-in-or-move-into-suspense - [cache] Cache the data access with `"use cache"` (does not apply to `connection()`) https://nextjs.org/docs/messages/blocking-prerender-dynamic#cache-the-component-or-data - [block] Set `export const instant = false` to silence this error and allow a blocking route https://nextjs.org/docs/messages/blocking-prerender-dynamic#allow-blocking-route at ProductPage (app/products/[slug]/page.tsx:52:32) 50 | props: PageProps<"/products/[slug]">, 51 | ) { > 52 | const featured = await fetch(`/api/products/${slug}`); | ^ 53 | 54 | return ( 55 |
``` ### Error pages written for agents The overlay and console show you _which_ fix to apply. But each fix is a pattern with constraints, edge cases, and trade-offs that don't fit in an error message. So every error gets its own page on `nextjs.org/docs/messages`, written for agents to read. Every fix section follows the same shape: the canonical **Patterns**, the **Trade-offs** against the other fixes, and the **Gotchas** an agent is likely to miss on a first attempt. For example, our uncached `fetch()` call lands on [`blocking-prerender-dynamic`](https://nextjs.org/docs/messages/blocking-prerender-dynamic), with our Stream choice at [Wrap in or move into Suspense](https://nextjs.org/docs/messages/blocking-prerender-dynamic#wrap-in-or-move-into-suspense). This is the most common one. There are 10+ similar pages under `/docs/messages`, each with its own considerations. An agent applying the fix on its own can read the trade-offs and pick what fits. Together, the **Copy as prompt** button, the structured console output, and the per-rule docs pages give agents the context to write performant, idiomatic Cache Components code. ## A smaller, more focused MCP server The [DevTools MCP server](/docs/app/guides/mcp) used to include its own Next.js knowledge base, along with upgrade and Cache Components helpers. With the bundled docs now serving that purpose, we've removed those tools from the MCP server, [as we did with the knowledge Skills](#first-party-skills). In 16.3, the MCP server adds two new compilation tools: `get_compilation_issues` for the whole project, and `compile_route` for a single route. Agents often run `next build` just to check whether the code compiles, which is overkill while you're still editing. These tools answer the same question from the running dev server, much faster. Skills like [`next-dev-loop`](#next-dev-loop) call the underlying `/_next/mcp` endpoints directly, so they work without any extra setup. To use these tools from your own agent client, add [`next-devtools-mcp`](/docs/app/guides/mcp) to your `.mcp.json`. The client finds the running `next dev` automatically. ## Docs as Markdown Append `.md` to any Next.js docs URL to get the page as plain markdown. This works for any page on `nextjs.org/docs`, including the per-error pages. Clients that send an `Accept: text/markdown` header get the markdown version too. The full index is at [`/docs/llms.txt`](https://nextjs.org/docs/llms.txt), and [`/docs/llms-full.txt`](https://nextjs.org/docs/llms-full.txt) bundles all doc pages into a single file. Both follow the [`llms.txt` convention](https://llmstxt.org/), so any agent that already reads `llms.txt` for other tools can read Next.js docs the same way. ## Feedback and community Share your feedback and help shape the future of Next.js: - [GitHub Discussions](https://github.com/vercel/next.js/discussions) - [GitHub Issues](https://github.com/vercel/next.js/issues) - [Discord Community](https://nextjs.org/discord)