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.

…