name: nextjs-optimizer description: Audit and optimize Next.js sites (App Router or Pages Router, v14 through latest) for speed, Core Web Vitals, bundle size, caching, database latency, security headers/CSP, SEO and hosting, with real before/after measurement. Always produces a written findings report and a fix plan for approval before touching any code. Use this whenever the user mentions a slow Next.js site, Lighthouse/PageSpeed/LCP/INP/CLS scores, bundle size, next/image, next/font, next/script, caching/ISR/revalidate/use cache, Suspense/streaming, hydration, "optimize my Next.js app", pre-production checks, or an upgrade from Next 14/15 to 16 -- even if they don't say "audit" or "optimize".

Next.js Optimizer

Audit a Next.js codebase, report what is slow and why, agree a plan with the user, then fix it. The order matters: a report with evidence builds trust, and a plan the user approved means no surprise rewrites of their code. Caching changes in particular can silently serve stale or wrong-user data, so nothing gets edited before approval.

Workflow

1. Scope (quick)

• Find the project root (the folder with package.json containing next). If the user only gave a URL, say a code audit needs the repo; meanwhile get field data (below) and don't guess at causes.
• Run python <skill-dir>/scripts/audit.py <project-root> -- it detects version, router, config flags and checks ~45 known problems (performance, security, database, a11y, version leftovers) with file:line evidence. Use --json if you want to post-process.
• Version drives advice. Read references/versions.md once; behaviour differs a lot between 14, 15 and 16 (fetch caching defaults, use cache, proxy.ts, image defaults). Prefer version-matched docs in node_modules/next/dist/docs/ over memory.
• Field data first, when there's a live URL: python <skill-dir>/scripts/field_data.py <url> [--origin] [--psi] pulls real-user p75 LCP/INP/CLS from the CrUX API. It needs a free Google API key (CRUX_API_KEY); without one, or if the network is blocked, ask the user for Search Console > Core Web Vitals or a PageSpeed Insights link. Low-traffic pages have no record: try --origin.
• Running app (Next 16+): if mcp__next-devtools__* tools are connected, use them (errors, routes, compile checks); if not, offer the setup once. See references/devtools-mcp.md.

2. Audit

The script finds the cheap stuff; you find the rest by reading. Read next.config.*, the root layout, and the 3-5 most important routes (home, a listing, a detail page, anything with heavy data). Then work through the area references, loading only what applies:

Measure when you can. Lab numbers from next dev are meaningless; only production builds count. Prefer field data at p75 over a single Lighthouse run.

• python <skill-dir>/scripts/measure.py <project-root> --label before --routes / /some-route --runs 3 builds, runs next start, runs mobile Lighthouse (median of N) and saves .perf/before.json + .md. It needs node_modules installed and Chrome/Chromium; if something is missing it says so, and then you report that measurement wasn't possible instead of inventing numbers. Running it only writes to .perf/ (mention it so they can gitignore it).
• Bundle: next experimental-analyze on 16.1+, otherwise @next/bundle-analyzer. Installing the analyzer edits package.json, so propose it in the plan instead of installing during the audit.

Mark each finding Confirmed (you saw it in code/build output) or Suspected (needs measuring). Don't present guesses as facts.

3. Report

Fill in assets/report-template.md and save it as NEXTJS_OPTIMIZATION_REPORT.md in the project root (send it to the user too). Keep it scannable: a 5-line summary, a findings table sorted by impact/effort, then details per finding (evidence, why it hurts, fix, risk, version note). Group related findings rather than listing 40 near-duplicates.

3b. Experimental gate (ask before using)

PPR / Cache Components and other experimental or canary options (staleTimes, inlineCss, cssChunking, useLightningcss, turbopackRustReactCompiler, experimental.requestInsights for the MCP get_request_insights tool, experimental.sri for hash-based CSP, etc.) can be a big win but may change between releases, need migration work, or not be supported by the user's host. So they are never enabled by default:

1. In the report, put them in a separate Experimental candidates section (only ones that fit this project, with evidence, benefit, risk, stability badge, rollback). Read references/experimental.md and re-check the option's docs page for the user's version first.
2. Ask the user which ones, if any, they want, with AskUserQuestion (multi-select, include "None, skip experimental" as an option). In chat, a plain list with a yes/no is fine. If the user isn't there to answer (unattended run), don't enable any; leave them as recommendations.
3. Only the ones the user says yes to go into the plan, as their own step so they can be reverted alone. Declined ones stay out and aren't raised again.

4. Plan -- then stop for approval

Turn the report into a plan and get it approved through Claude's plan mode: call EnterPlanMode (load it with ToolSearch if deferred), write the plan, and present it with ExitPlanMode. If plan mode is unavailable, show the plan in chat and wait for an explicit "go". Plan structure:

1. Quick wins (config, next/image sizes, next/font, next/script strategy, <a> -> <Link>) -- low risk, do first.
2. Structural (Suspense/streaming, parallel fetches, caching strategy, moving "use client" down the tree) -- needs care, name the behaviour change.
3. Heavy (dependency swaps, bundle refactors, version upgrade) -- opt-in, separately approved.
4. Experimental (only those the user said yes to in step 3b) -- last, each behind its own step with rollback. Each step lists files touched, the expected effect, how to verify, and how to roll back. Let the user drop or reorder items.

5. Fix

Only after approval, and only the approved items. Work in small groups, and after each run typecheck/lint/next build so a break is traced to one change. Don't mix an upgrade (14 -> 15 -> 16 via npx @next/codemod@canary upgrade latest) with optimization edits; do it as its own step. If something approved turns out riskier than planned (e.g. a cache would share per-user data), stop and ask.

6. Verify and wrap up

Re-run build and the same measurements you took before (measure.py ... --label after, then measure.py --compare .perf/before.json .perf/after.json); give a short before/after (route sizes, first-load JS, Lighthouse mobile). If you couldn't measure something, say so plainly rather than claiming gains. End with what's left (deferred items) and one suggested next step.

Optional follow-up to offer (don't add unasked): a CI guard so gains don't regress -- copy assets/ci/perf.yml, assets/ci/lighthouserc.json and assets/ci/check-bundle-budget.mjs (gzip client-JS budget + Lighthouse CI). The Lighthouse CI template uploads reports to public temporary storage by default; mention that and drop it for private sites.

SEO: hand off to claude-seo

This skill covers the Next.js side of SEO (Metadata API, sitemap.ts, robots.ts, canonical, OG images, JSON-LD, soft 404s, Core Web Vitals). Full SEO work -- site-wide crawl audits, content/E-E-A-T, schema validation, backlinks, local, hreflang, AI-search (GEO) -- is better done by the open-source claude-seo plugin (https://github.com/AgriciDaniel/claude-seo, MIT, 26 sub-skills driven by /seo ... commands such as /seo audit <url>, /seo page <url>, /seo technical, /seo schema, /seo sitemap, /seo images, /seo geo).

• User asks for SEO (audit, rankings, schema, sitemap, "why am I not on Google", etc.): check whether claude-seo is installed (its /seo commands or skills show up in the available skills; ListSkills can confirm). If it is, use it for the SEO part and keep this skill for the Next.js code changes it implies. Feed its findings into the same report and plan so the user gets one approval step, not two.
• Not installed: mention it once, in one or two lines, with the install steps, and carry on with the Next.js-side SEO checks. Don't install it yourself; it adds a persistent plugin and a headless browser, so the user decides. Install (inside Claude Code): /plugin marketplace add AgriciDaniel/claude-seo, then /plugin install claude-seo@agricidaniel-claude-seo, then /seo setup. Needs Python 3.11+. No API keys required; Google APIs are optional via /seo google setup.
• User didn't ask about SEO but the audit shows clear SEO gaps (no metadata, sitemap, robots): suggest it as an optional follow-up in the report, not in the middle of the work.
• Note that full claude-seo audits use more of the user's Claude plan than a quick page check; say so if suggesting a whole-site run.

Principles

• Measure, then fix. The biggest wins are usually: too much client JS, uncached/waterfalled data fetching, unsized or priority-less LCP image, and slow origin (DB/API/region). Rank by evidence, not by checklist order.
• Server by default. "use client" belongs at the leaves. Each unnecessary boundary ships JS and serializes props.
• Caching is a correctness feature first. Anything per-user must never land in a shared cache. State the freshness trade-off (how stale, how invalidated) for every caching change.
• Don't over-optimize. Skip memoization sprinkling, micro-splitting and exotic config unless a measurement says it matters. React Compiler (16) makes manual memo mostly unnecessary.
• Docs move. When unsure of an API or default for the user's version, fetch it (https://nextjs.org/docs/llms.txt, or /docs/14/..., /docs/15/...) instead of relying on memory.
• Security counts, but never silently trade it for speed. Check auth inside each Server Action and that only safe NEXT_PUBLIC_ values reach the client. A nonce CSP forces dynamic rendering: surface that conflict, don't "fix" it quietly (references/security-a11y.md).
• Where it runs matters. Detect the host (references/platforms.md) before recommending features it may not support; a database in another region or an exhausted connection pool beats any front-end tweak (references/database.md).
• Migrations are their own plan item (references/migrations.md): never bundled with quick wins.