Guide · Agent skill

How to use the Next.js and Turbopack Guide agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The nextjs-turbopack skill gives your AI agent reference knowledge about Next.js 16 and later, focused on Turbopack, the default bundler for local development. Once installed, the agent can explain how Turbopack and its filesystem cache affect dev startup and hot reload, when to switch back to webpack, and why proxy.ts is the correct middleware filename in Next.js 16. This guide shows you what the skill does, how to install it, how to ask for it, and where its limits are.

Next.js and Turbopack Guideaffaan-m/ECC · MIT Download the skill

Quick start

1Download the skill. Download the nextjs-turbopack ZIP from this page. It contains SKILL.md.
2Unzip into a skills folder. Unzip the folder into ~/.claude/skills/ for all projects, or into .claude/skills/ in one project.
3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the skill.
4Start a Next.js 16+ task. Open a Next.js project and describe the problem, such as slow dev startup or a question about proxy.ts.
5Check the answer against your version. Confirm the advice matches your Next.js version and read the official docs for any flag or config change before applying it.

What the skill makes the agent do

Agent skills are folders of instructions that an agent reads when a task matches them. This skill is a single SKILL.md file with guidance on Next.js 16+ and Turbopack. It shapes the agent's answers and suggestions; it does not run anything by itself.

The guidance covers four areas: Turbopack as the default for next dev, when to choose webpack instead, how the filesystem cache makes restarts faster, and the rule that middleware is named proxy.ts in Next.js 16 rather than middleware.ts.

Turbopack is the default bundler for local development in Next.js 16 and later.
Use webpack only if you hit a Turbopack bug or depend on a webpack-only development plugin.
Restarts reuse earlier work from a filesystem cache, typically stored in .next, with no extra setup for basic use.
In Next.js 16, middleware belongs in proxy.ts at the project root; renaming it to middleware.ts would break middleware execution.

Install the skill with a ZIP or the Claude apps

Download the skill ZIP from this page and unzip it. The skill folder contains SKILL.md. Place the folder in one of two locations: ~/.claude/skills/ to make it available across your projects, or .claude/skills/ inside a single project to limit it to that project.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

Personal install: unzip into ~/.claude/skills/
Project install: unzip into .claude/skills/ in the project root
Claude apps: Settings → Capabilities → Skills, then upload the skill

Trigger the skill with natural requests

You do not need a special command. Describe your problem in plain language that mentions Next.js, dev startup, hot reload, Turbopack, webpack, or proxy.ts, and the agent can match the request to this skill. Naming the Next.js version in your request helps, because the guidance applies to version 16 and later.

Good requests say what you see and what you want to decide.

"My next dev server takes a long time to start. What should I check?"
"Should we turn off Turbopack for this Next.js app, or keep it?"
"I have a proxy.ts file in a Next.js 16 project. Is that a mistake?"
"Hot reload got slow after a change. Could the cache be the cause?"

Examples of what you get back

For a slow start, the agent should confirm you are on Turbopack (the default) and that the cache is not being cleared unnecessarily. For a bundle-size question in production, it should point you to the official Next.js bundle analysis tools for your version, because the skill itself does not describe those tools in detail.

For a proxy.ts question in a Next.js 16 project, the agent should treat the file as correct and intentional rather than flag it as misnamed. It will also explain that the rename is tied to the Next.js version, not to the bundler you use.

next dev
next build
next start

What the skill needs and what it does not do

The skill needs a Next.js project. Its guidance applies to Next.js 16 and later, so for older projects the agent should check the version first, because file naming and defaults differ. The skill does not run scripts and does not use the network.

The source does not give the exact flag for disabling Turbopack in every version. It says to use --webpack, or --no-turbopack depending on your Next.js version, and to check the documentation for your version.

Requires: a Next.js project (version 16+ for the guidance to apply)
Runs scripts: no
Uses network: no

Tips for getting reliable answers

Tell the agent your exact Next.js version, since the advice changes between versions. Keep your project on a recent Next.js 16.x release for more stable Turbopack and cache behaviour, as the skill recommends. Before changing config or renaming files, ask the agent to confirm against the official docs for your version.

State your Next.js version in the first message.
Keep the project on a recent 16.x release.
Do not rename proxy.ts to middleware.ts in Next.js 16 projects.
Clearing the cache should be a deliberate step, not a routine one.

What people use it for

Diagnosing a slow next dev startup or sluggish hot reload in a large app.
Deciding whether a team project should keep Turbopack or fall back to webpack for development.
Reviewing a Next.js 16 project to confirm proxy.ts is intentional and not a naming error.
Getting a checklist for keeping the filesystem cache healthy during daily development.

Frequently asked questions

How do I install the nextjs-turbopack agent skill?

Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project. In the Claude apps, you can also upload it under Settings, then Capabilities, then Skills.

Is the nextjs-turbopack skill free?

The skill is published under the MIT licence, as stated on this page. Check the source repository for the full licence text before reusing it.

What do I need to use this skill?

You need a Next.js project. The guidance applies to Next.js 16 and later, so check your version first. The skill does not run scripts and does not use the network.

Why does the agent say proxy.ts is correct and not middleware.ts?

In Next.js 16, the middleware file is named proxy.ts at the project root, replacing the older middleware.ts. The name depends on the Next.js version, not on whether you use Turbopack or webpack, so renaming it would break middleware.

How do I turn off Turbopack and use webpack in development?

The skill says to use the --webpack flag, or --no-turbopack depending on your Next.js version. Check the Next.js documentation for your version to confirm which one applies.

Does this skill replace the official Next.js docs?

No. It is reference guidance that shapes the agent's answers. For version-specific flags, config and production build behaviour, the skill directs you to the official Next.js documentation.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you build or debug Next.js 16+ apps and want an agent that understands Turbopack, the filesystem cache and the proxy.ts naming rule. Pick something else if your project is on an older Next.js version without checking, or if you do not use Next.js at all, because the guidance is specific to that framework.

Download the skill