What is the documentation issue?
Two of the official agent skills shipped in this repo (skills/) contain instructions that fail silently on non-default project setups:
1. next-cache-components-adoption hardcodes the app/ root. Its commands, globs and completion checks assume app/ at the repository root, even though its
own requirements section acknowledges src/app support. On a src/app project the codemod matches zero routes and the completion checks pass vacuously — the
agent reports a successful Cache Components migration having touched nothing.
2. next-dev-loop probes /_next/mcp on port 3000 before applying the custom-port instruction. The preflight runs tools/list / get_compilation_issues
against the default port; the instruction to set NEXT_MCP_URL for non-3000 projects appears only later in the document. On a project whose dev script binds
another port (ours: 3010), a literal top-to-bottom run queries the wrong port and refuses verification even though next dev is running.
Is there any context that might help us understand?
Found while running the skills (installed via npx skills add vercel/next.js) in a production repo using src/app and next dev --turbo -p 3010.
Both are silent failure modes — false progress and false refusal — rather than visible errors, which is the worst case for agent-executed instructions: nothing
surfaces for a human to catch.
Suggested fixes:
next-cache-components-adoption: resolve the App Router root once (app vs src/app) at the start and reuse that variable in every command, glob and
completion check.next-dev-loop: move the port/NEXT_MCP_URL resolution into the preflight, before the first MCP probe.
Happy to send a PR for either if that's preferred.
Does the docs page already exist? Please link to it.
https://github.com/vercel/next.js/blob/canary/skills/next-cache-components-adoption/SKILL.md, https://github.com/vercel/next.js/blob/canary/skills/next-dev-loop/SKILL.md
What is the documentation issue?
Two of the official agent skills shipped in this repo (
skills/) contain instructions that fail silently on non-default project setups:1.
next-cache-components-adoptionhardcodes theapp/root. Its commands, globs and completion checks assumeapp/at the repository root, even though itsown requirements section acknowledges
src/appsupport. On asrc/appproject the codemod matches zero routes and the completion checks pass vacuously — theagent reports a successful Cache Components migration having touched nothing.
2.
next-dev-loopprobes/_next/mcpon port 3000 before applying the custom-port instruction. The preflight runstools/list/get_compilation_issuesagainst the default port; the instruction to set
NEXT_MCP_URLfor non-3000 projects appears only later in the document. On a project whose dev script bindsanother port (ours: 3010), a literal top-to-bottom run queries the wrong port and refuses verification even though
next devis running.Is there any context that might help us understand?
Found while running the skills (installed via
npx skills add vercel/next.js) in a production repo usingsrc/appandnext dev --turbo -p 3010.Both are silent failure modes — false progress and false refusal — rather than visible errors, which is the worst case for agent-executed instructions: nothing
surfaces for a human to catch.
Suggested fixes:
next-cache-components-adoption: resolve the App Router root once (appvssrc/app) at the start and reuse that variable in every command, glob andcompletion check.
next-dev-loop: move the port/NEXT_MCP_URLresolution into the preflight, before the first MCP probe.Happy to send a PR for either if that's preferred.
Does the docs page already exist? Please link to it.
https://github.com/vercel/next.js/blob/canary/skills/next-cache-components-adoption/SKILL.md, https://github.com/vercel/next.js/blob/canary/skills/next-dev-loop/SKILL.md