next-dev-loop
Skill901 starsChanged 19 days agoMITView on GitHub
Verify Next.js runtime behavior after editing app code. Use this skill to confirm a change actually works in a running app — not just that it compiles or type-checks. Combines /_next/mcp (Next.js's view) with agent-browser (the browser's view). Requires a running `next dev`.
- Installs packages
18 other projects use a version of this, 18 of them edited.
Adopted by
Most recently taken up by
- toy-crane/claude-code-playbook-templateedited, first seen Nov 10, 2026
- kovrichard/catalystedited, first seen Nov 8, 2026
- schornai/schornaiedited, first seen Nov 8, 2026
- wotschofsky/domain-diggeredited, first seen Nov 1, 2026
- omarx11/omar11.saedited, first seen Nov 1, 2026
- ManatoYamashita/skillsedited, first seen Nov 1, 2026
Used with
Projects with it also use create-vercel-ai-issue, dev-auth-bypass and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
FranciscoMorettiSkillcreate-vercel-ai-issue
Create a well-formed GitHub issue in vercel/ai using the gh CLI. Use when reporting an AI SDK bug or preparing an issue body that contains logs, code blocks, versions, reproduction steps, and shell-sensitive text.
Also in 3 projects that use this
FranciscoMorettiSkilldev-auth-bypass
Authenticate a browser against a local ChatJS app without OAuth. Use for development login, local auth bypass, authenticated browser or Playwright testing, and the /api/dev-login route.
Also in 3 projects that use this
- +10 more from FranciscoMoretti
Other versions18 projects use a version of this.
Word for word · 0
None found.
Edited · 18
- vercel/next.js★ 144k95% same
- wotschofsky/domain-digger★ 1.5k100% same
- FranciscoMoretti/chat-js★ 1.2k92% same
- FranciscoMoretti/chatjs★ 1.2k92% same
- FranciscoMoretti/sparka★ 1.2k92% same
- sanity-io/next-sanity★ 95692% same
- BingZi-233/check-cx★ 63690% same
- kovrichard/catalyst★ 470100% same
- udecode/better-convex★ 45290% same
- aurorascharff/next16-commerce★ 26690% same
8 more not listed
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- next-cache-components-adoptionSkill
- next-partial-prefetching-adoptionSkill
- ultraciteSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 1 is distinctive, and 3 are very specific to this project.
0
Common
Most of the 18 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 66
Ask the running app, not the codebase.
- Very specific: line 92
All tools below are present once preflight passes.
- Very specific: line 116
Only participate in agent feedback when managed Next.js feedback instructions are already loaded for the project.
- Distinctive: line 118
When enabled, add qualifying feedback candidates found during verification to the feedback candidate queue for the current user request, …
“Common” is measured: kept by at least 6 in 10 of the 18 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
next-dev-loop
The edit/verify rhythm during next dev — make a change, then confirm it actually works at runtime, not only that the types or the build are happy.
You verify through two views of the same running app:
/_next/mcp— an HTTP endpoint Next.js exposes about itself. Knows framework-specific things: routes, segments, RSC, server actions, server logs, and errors as Next.js saw them. Calltools/listfor the current surface.agent-browser— a CLI that drives a real Chrome. Knows framework-agnostic browser things: DOM, console, network, React fiber, vitals. Before driving it, runagent-browser skills get coreonce for the version-matched usage guide — don't guess subcommands from memory.
The two views cross-check each other.
requires
- Next.js 16.3+ with Turbopack —
/_next/mcpplus the proactive compile check viaget_compilation_issues. agent-browser>= 0.31.1 — React introspection, worktree-scopedsession id, idempotent--restore, and launch flag reconciliation.
These are hard floors, not soft preferences. If anything is missing, tell the user how to upgrade and stop. Don't fall back to grepping source or to a weaker probe — this skill assumes both views are live at the versions above.
- Upgrade Next.js:
pnpm next upgrade(ornpx next upgrade). Docs: https://nextjs.org/docs/app/getting-started/upgrading (version-16 guide: https://nextjs.org/docs/app/guides/upgrading/version-16) - Install or upgrade
agent-browser:npm i -g agent-browser@latest. If the CLI isn't onPATH, install it before continuing — preflight expects to invoke it directly.
preflight
Once per session, confirm both views are live.
Open
agent-browserat the target URL, restoring saved login state when present. First derive one stable session id for this checkout and use it for everyagent-browsercommand:SESSION="$(agent-browser session id --scope worktree --prefix next-dev-loop)" export AGENT_BROWSER_SESSION="$SESSION" export AGENT_BROWSER_RESTORE="$SESSION"Then open the target URL:
agent-browser --session "$SESSION" --restore --enable react-devtools open <url>--scope worktreekeeps parallel worktrees and copied checkouts from colliding. Bare--restoreuses the session id as the persistence key, loads saved cookies/localStorage before navigation when present, and auto-saves state on close. Always pass the desired launch flags onopen; agent-browser will reuse, relaunch, or restart its scoped background state as needed.Keep routine verification headless. If the user asks to see the UI, open the current URL in the coding harness's inline browser. It is a separate browser context, so do not assume state carries over. When login or existing
agent-browserstate must carry over, reopen that session headed instead:agent-browser --session "$SESSION" --restore --headed --enable react-devtools open <url>Pause while the user drives login, then continue with the same session and keep it headed for the rest of the loop.
- Probe
/_next/mcp(tools/list) — confirm it's reachable and listsget_compilation_issues. First read the port off thenext devbanner; if it isn't 3000, setNEXT_MCP_URL=http://localhost:<port>/_next/mcpbefore probing:- Unreachable → either
next devisn't running, or Next.js is below 16.3. Checkpackage.jsonto disambiguate, then refuse. get_compilation_issuesnot in the list → Next.js below 16.3. Refuse and tell the user to upgrade.
- Unreachable → either
get_compilation_issuesdoubles as a Turbopack probe. An error response of"Turbopack project is not available..."means the user is on webpack. Refuse — Turbopack is required.get_routes→ your route map for the rest of the session.
loop
before the edit — narrow the scope
Ask the running app, not the codebase. /_next/mcp knows which files rendered the current route; use those as your search scope. Runtime introspection stays cheap as the codebase grows; agentic search doesn't.
after the edit — verify
Four failure modes. Check each:
- Compiles —
get_compilation_issues. - Runs without errors —
/_next/mcp(server and bubbled-up browser errors both surface here). - Behaves as intended —
agent-browserdrives the page; assert what the user actually sees. - React-level behavior —
agent-browserwith react-devtools enabled exposes the component tree, props, state, and render counts. Anchor framework-level checks here (extra renders, server/client boundary shifts, suspense fallbacks) — DOM asserts alone miss them.
Pick the specific tool from tools/list or the agent-browser manual rather than from memory.
gotchas
- Preserve
.nextwhile the development server is running. Moving or deleting it disconnects the server from its generated state and discards incremental caches. Moving it to a backup is still a reset. If a production build needs isolated output, configure a separatedistDir. - Every
agent-browsercommand must know your session and restore key, or it may use an empty default browser or fail to save login state. Easiest: export bothAGENT_BROWSER_SESSION="$SESSION"andAGENT_BROWSER_RESTORE="$SESSION"at the top of each shell you run agent-browser in. If you do not export them, pass--session "$SESSION" --restoreon every command. - When the two views disagree, suspect the tooling first. If
agent-browsersays a route is broken but/_next/mcpand the server say it rendered cleanly, a stale or misdirected browser session is the likelier cause than a real bug — reconcile the views before debugging the app. - Confirming a click or navigation: the page settles a beat later, so wait with
wait --load networkidle(no path to get wrong), then snapshot/read to confirm the page. Avoidwait --urlunless you pass the link's exact href — a guessed or placeholder path won't match the real URL and times out after 25s. - A blank read, empty snapshot,
about:blank, or a "no browser session" error — right afteropenor after a click (even ifopenreported the page) — is the browser dropping the page (a stale session), not a broken route. Reopen your session at the URL with the same launch flags as the active loop, then re-snapshot. If still blank, runagent-browser --session "$SESSION" --restore close, then reopen with those same flags. Don't fall back tocurl; it bypasses the browser you're testing. - React introspection output is stale after navigation. Re-run.
/_next/mcpreplies are SSE — read the JSON off thedata:line withsed -n 's/^data: //p'(a plainsed 's/^data: //'leaves theevent:line and the parse fails).get_errorsandget_page_metadataneed at least one navigation to populate.
reference
All tools below are present once preflight passes. If tools/list is missing any of them, preflight should have refused — re-check.
# /_next/mcp notes
get_project_metadata projectPath, devServerUrl, bundler
get_routes fs-scan; no browser session needed
get_errors runtime + build; needs a browser session;
includes browser-side errors caught by the
dev server
get_page_metadata segment trie + routerType; needs a browser
session; use as a discovery shortcut for
which files power a route
get_logs returns logFilePath
get_server_action_by_id hashed id → file + functionName
get_compilation_issues Turbopack only; errors on webpack
("Turbopack project is not available")teardown
Close the session with the same session and restore context: agent-browser --session "$SESSION" --restore close. close saves that session's cookies and storage so the next loop's --restore open keeps the user logged in. Leave next dev up for the next loop.
Report Next.js friction
Only participate in agent feedback when managed Next.js feedback instructions are already loaded for the project. Their presence means the feature is enabled; their absence means it is disabled.
When enabled, add qualifying feedback candidates found during verification to the feedback candidate queue for the current user request, then continue verification. Do not run the feedback command or open review forms during the loop or at this Skill's teardown.
The managed instructions own the single reporting pass immediately before the final response. If they are absent, do not queue or report feedback.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

