vercel-optimize – Security skill for AI agents

Vercel Optimize

Run an observability-first Vercel optimization audit. Collect platform signals before source investigation. The deterministic scanner reads repository text to build signals.json; manual source investigation then stays within a selected candidate.

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.

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.

| 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:

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](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:

I can't safely identify the Vercel project and account for this audit yet.

Please confirm the Vercel project name or ID and the team slug/name, or tell me it's under your personal account. Once confirmed, I'll relink or rerun collection against that exact scope before checking metrics.

1.1 Stop on blockers

Check blockers before gating:

jq '{frameworkSupportBlocker, observabilityPlus, observabilityPlusUsable, observabilityPlusBlocker, observabilityPlusBlockerDetail}' "$RUN_DIR/signals.json"

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:

vercel link --yes --project <project-name-or-id> --cwd <app-dir>
# add --team <team-id-or-slug> when 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:

node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"

Then scan and merge again.

2. Gate candidates

node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"

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:

node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates 12 > "$RUN_DIR/gate.json"
node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates all > "$RUN_DIR/gate.json"

Generated candidate docs: [references/candidates.md](references/candidates.md).

2.1 Ask about audit scope when needed

Before deep-dive, run:

node scripts/budget-summary.mjs "$RUN_DIR/gate.json" --format json > "$RUN_DIR/budget-summary.json"

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

node scripts/deep-dive.mjs "$RUN_DIR/signals.json" "$RUN_DIR/gate.json" --cwd <project-dir> > "$RUN_DIR/investigation-ev

… (full content is in the download package)