Use for Vercel cost and performance optimization on deployed projects, especially Next.js, SvelteKit, Nuxt, and limited Astro apps. Collect Vercel metrics, usage, project config, and code scan results first; investigate only metric-backed candidates; produce ranked recommendations grounded in verifi

Vercel Optimize Run an observability first Vercel optimization audit. Do not inspect source files until signals.json exists and a deterministic gate points to a route, file, or project setting. Core doctrine: read [references/doctrine.md](references/doctrine.md) if any rule is unclear. Metrics first. Recommendations start from Vercel production signals, not repo wide grep. Deterministic gates. scripts/gate investigations.mjs decides what deserves investigation. Candidate bound scope. Read only files named by a candidate or a route local import chain. Version aware citations. Use only references/docs library.json ; invalid or version mismatched citations are stripped. Customer copy. Read [references/voice.md](references/voice.md) before writing report text or chat output. Prerequisites Vercel CLI v53+ with vercel metrics , vercel usage , vercel contract , and vercel api . Authenticated CLI session: vercel login . Linked app directory: vercel link . VERCEL PROJECT ID can help resolve project config, but vercel metrics still requires directory linkage. The link or environment must include the intended project org/team/user scope so the collector can resolve a CLI safe scope and keep vercel metrics , vercel usage , and vercel contract on the same account. Node.js 20+. Observability Plus for route level metric backed recommendations. Never put auth tokens in shell commands. Do not type VERCEL TOKEN=... , token ... , or Authorization: Bearer ... into commands that may be echoed in chat. Framework Support The preflight reads package.json and sets expectations before metric fan out. Framework Status Notes Next.js App Router supported strongest route mapping, scanners, playbooks, citations Next.js Pages Router supported scoped to Pages Router idioms when detected SvelteKit supported route mapping for src/routes files and SvelteKit scanner Nuxt supported route mapping plus generic/platform checks; fewer framework specific recs Astro limited route mapping plus generic checks; fewer framework specific recs Hono / Remix / unknown blocked by default continue only if the user accepts a limited platform/code only audit If unsupported, stop and ask before scanning or gating: If the user continues, rerun collection with continue unsupported framework . Run Directory Use a fresh run directory for every audit. Do not reuse briefs, sub agent outputs, or reports across runs. Pipeline 1. Collect, scan, and merge signals Run from the linked app directory or pass cwd where a script supports it. Keep stdout JSON separate from stderr logs. Do not combine streams. Collection details, schemas, metric IDs, and degradation behavior live in [references/data collection.md](references/data collection.md). The metric registry is [lib/queries.mjs](lib/queries.mjs); keep all queries on the shared 14 day window. collect signals.mjs resolves the linked project owner to commandScope.cliScope and verifies that the resolved account can read the resolved project before it checks Observability Plus. Downstream scripts reuse that scope for every Vercel CLI command that accepts scope . Do not run vercel usage , vercel metrics , or vercel contract manually without the same scope; unscoped usage can report the user's personal organization while route metrics come from the team project. If project or scope resolution is ambiguous, stop and ask the user which Vercel project and team/personal scope they want audited. Do not infer the intended scope from the current vercel whoami team, and do not proceed with metrics, usage, or contract collection until the link, an exact project match in .vercel/repo.json , or VERCEL PROJECT ID + VERCEL ORG ID identifies the intended account. Use this prompt for PROJECT SCOPE UNRESOLVED , SCOPE UNRESOLVED , or PROJECT SCOPE MISMATCH : 1.1 Stop on blockers Check blockers before gating: Required actions: frameworkSupportBlocker === "unsupported framework" : use the unsupported framework prompt above. PROJECT SCOPE UNRESOLVED , SCOPE UNRESOLVED , or PROJECT SCOPE MISMATCH : stop and ask which Vercel project and team/personal scope the user wants audited. For team projects, rerun after vercel link yes project <project name or id team <team slug ; for personal projects, rerun after linking under the intended user account or after setting both VERCEL PROJECT ID and VERCEL ORG ID . observabilityPlusBlocker === null : continue. no traffic : tell the user route metrics are sparse; continue only if they accept limited output. payment required or no oplus probe : render [references/observability plus.md](references/observability plus.md) verbatim and ask. project disabled : tell the user to enable Observability Plus for the project or accept a limited audit. daily quota exceeded : stop and tell the user the Observability query quota is exhausted; retry after the next UTC midnight reset, or ask whether to continue with a limited code only audit. not linked : link the app directory, then rerun Step 1. If app path and project are known: forbidden or project not found : fix auth/team scope. Do not pitch Observability Plus. all failed other : show the raw error code and ask whether to continue in limited code only mode. Do not silently fall back to code only mode. If the user accepts a limited audit, rerun collection with: Then scan and merge again. 2. Gate candidates Output shape: toLaunch : code scope candidates to investigate. platform : project/account scope recommendations. gated : skipped, covered, or disqualified candidates that must still appear in the report. budget : candidate budget and selection mode. Default budget is 6 code scope candidates with a diversity guardrail. To expand: Generated candidate docs: [references/candidates.md](references/candidates.md). 2.1 Ask about audit scope when needed Before deep dive, run: If shouldAsk is false, continue. If shouldAsk is true: 1. Print exactChatMessage.body exactly as returned. Do not summarize, truncate, reorder, or rewrite it. 2. Then ask questionText using questionPayload when the host supports structured questions. 3. If the user chooses a different number, rerun the gate with max candidates <choice . Never put the long preview inside the question field. The preview and the question are separate surfaces. 2.2 Deep dive and reconcile cwd must be the linked project directory so deep dive.mjs can verify the same project link and reuse signals.json.commandScope.cliScope for any follow up vercel metrics calls. Reconciliation deterministically converts disproven candidates into observations before any source investigation: metric mismatch error storm deployment regression scanner only no metric 2.3 Generate briefs and investigate List the work: Generate one brief for every entry in briefs manifest.json.briefs . The group can be toLaunch or platform ; do not generate only toLaunch briefs. Use briefs manifest.json.briefs[].label for visible worker names, for example Low cache hit route on /docs/llm digest/[...slug] , not toLaunch 7 . Fan out rule: 1 2 briefs: investigate inline. 3+ briefs: spawn one sub agent per brief when the host supports it. Hosts without sub agents: run inline serially. Sub agent contract: The brief is the whole prompt. Read only files listed in the brief, plus route local imports when needed. Emit one JSON recommendation or one JSON no change finding using [references/recommendations.md](references/recommendations.md). Do not cite URLs outside the provided citation subset. Do not recommend framework features unavailable in the detected version. If a sub agent reaches for repo wide grep, the candidate is malformed; drop or abstain rather than widening scope. 2.4 Collect outputs Save each raw investigation result in $RUN DIR/sub agent outputs/ , then collect: The collector extracts JSON, prepends pre resolved records, enforces manifest order, and fails on missing, duplicate, unknown, or mismatched candidateRef values. 3. Verify recommendations This script extracts claims, verifies files/citations/version fit, grades quality, applies sanitizers, emits verifiedRecommendations , withheldRecommendations , renderableRecommendations , and creates regenPlan for failed or unsafe recommendations. Recommendation schema, writing rules, sanitizer order, and grading rules: [references/recommendations.md](references/recommendations.md). Verification rules: [references/verification.md](references/verification.md). For each regenPlan entry, rerun the same brief with a Previous attempt failed these checks section listing topFailures . Keep the regenerated output only if verification improves without gutting citations. 4. Render report and final message Use debug out "$RUN DIR/debug.json" only when developing the skill. Customer Markdown and chat output must not expose passRate , quality , sanitizer trails, raw sub agent names, or other implementation fields. After rendering, print final message.json.body verbatim and stop. Do not add highlights, debug notes, raw counts, sub agent summaries, or extra explanation. Render time dedupe, platform caps, and hard safety drops can change the customer visible count, so never summarize from raw verify.json . Report structure and impact framing: [references/scoring.md](references/scoring.md). Recommendation Rules Every recommendation must: Trace to a launched candidate, platform candidate, pre resolved observation, or verified traffic independent scanner finding. Include observed metric evidence from signals.json or evidence.deepDive . Cite verified files with line numbers when code is involved. Include at least one allowed citation that applies to the detected framework/version. Use precise observed performance numbers. Use cost magnitude phrases only; never customer facing $N savings. Do not recommend duration reductions for Vercel Workflow runtime endpoints ( /.well known/workflow/v1/ ). These are generated orchestration routes for durable step/flow execution and should be hard gated before investigation. Workflow recommendations must name the boundary being changed. Valid examples: enqueue durable work and return a run ID instead of awaiting completion, fix stream replay/closure/locks, or reduce verified excess Workflow Steps/Storage. Do not infer cost savings from Workflow endpoint wall clock duration. For streaming, SSE, resumable chat, or other intentionally long lived routes, do not frame wall clock function duration as a problem by itself. Require evidence of avoidable pre first byte work, high active CPU, duplicate invocations, or post response work that can move out of the user visible path. Name a specific cache policy when recommending caching. Keep unsafe responses dynamic unless evidence proves they are safe to cache: auth sensitive paths, errors, fallback responses, missing content, invalid requests, geolocation/device varying output, and unversioned dynamic URLs. Never recommend "verify X is on" for facts already present in signals.project , including Fluid compute status, memory tier, regions, in function concurrency, and timeout. Scanner Rules Scanner findings are supplementary. Drop findings annotated COLD PATH or NO ROUTE MAPPING unless the scanner declares metadata.trafficIndependent === true . Traffic independent examples: middleware matcher, source maps, React Compiler config, build settings. Route local cache or data fetch patterns need route level traffic evidence. Scanner docs: [references/scanner patterns.md](references/scanner patterns.md). Final Customer Terms Use: recommendations ready observations from investigation

vercel-optimize