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 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 before writing report text or chat output.

When to Use

• Use this skill when the task matches this description: Audit deployed Vercel apps for cost and performance issues using metrics, project config, code scans, and version-aware recommendations.

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.

If unsupported, stop and ask before scanning or gating:

This project uses <framework>. Vercel Optimize supports metric-backed code recommendations for Next.js, SvelteKit, and Nuxt. Astro support is limited. For <framework>, I can still run a limited platform/scanner audit, but route-level Vercel metrics may not map back to source files.

Do you want me to continue with the limited audit, or stop here?

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.

RUN_DIR="$(mktemp -d -t vercel-optimize-XXXXXX)"

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.

node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "$RUN_DIR/vercel-signals.json"

node scripts/scan-codebase.mjs <repo-root> > "$RUN_DIR/codebase.json"
node scripts/merge-signals.mjs "$RUN_DIR/vercel-signals.json" "$RUN_DIR/codebase.json" --out "$RUN_DIR/signals.json"

Collection details, schemas, metric IDs, and degradation behavior live in references/data-collection.md. The metric registry is 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