Preface¶

After a project has been deployed to Vercel, the common troubles are often not “whether it can go live”, but that the Function Invocations, Build Minutes, and Fast Data Transfer in the bill suddenly rise, or some routes are significantly slower. At this time, if you ask the Agent to directly search for cache, revalidate, or force-dynamic in the repository, it is easy to get a bunch of suggestions unrelated to real traffic: the cold paths are modified, but the hot paths remain unchanged.

This is exactly what vercel-optimize aims to solve. It is an Agent Skill from the official Vercel Labs repository: it first pulls production metrics and usage via the Vercel CLI, then uses a deterministic script to decide which routes and files to inspect, and finally provides optimization suggestions with sources. After installation, you can trigger it by saying “optimize this Vercel project” to the Agent in the linked project directory.

What is this¶

vercel-optimize is included in vercel-labs/agent-skills under the directory skills/vercel-optimize/. The repository follows the Agent Skills general format (SKILL.md + optional scripts/, references/), so tools that support this format such as Cursor, Claude Code, and Codex CLI can all use it. The current metadata.version of SKILL.md is 1.2.0.

The official README positions it as: cost and performance optimization for projects already deployed on Vercel that are supported. Each suggestion must meet three requirements at the same time: corresponding signals can be found in the observation data, the source code can be checked within a limited scope, and the referenced documents must match the current framework version.

It targets projects that have already gone live and have traffic, rather than building a Next.js application from scratch. Trigger scenarios include: reducing Vercel bills, troubleshooting slow and expensive routes, finding issues with cache / ISR / Middleware / image optimization / build minutes, and generating a prioritized cost and performance report.

Core Capabilities¶

Based on the SKILL.md, README.md, and references/doctrine.md in the repository, the working mode of this Skill can be summarized into four hard rules.

1. Observe first, then read the code
   You are not allowed to browse the source code before signals.json is generated. It is recommended to start from Vercel production signals instead of grep-ing the entire repository. The metric window is uniformly set to the last 14 days.

2. Use a deterministic script to determine the investigation scope
   scripts/gate-investigations.mjs uses pure JavaScript thresholds, and does not rely on large models to judge “whether this route is worth checking”. By default, up to 6 code-side candidates are selected each time, with diversity constraints. The skipped candidates will still appear in the report’s “Not investigated in this run” section with the reason stated.

3. Investigation scope is tied to candidates
   After the gatekeeper gives files like src/app/api/products/route.ts, the Agent only reads this file and its import chain within the route, and is prohibited from expanding to a full repository scan. Static scanning (AST-grep) can be run in parallel, but discoveries marked COLD-PATH or NO-ROUTE-MAPPING are discarded by default; only items unrelated to traffic such as build configuration, middleware matcher, production source map, and React Compiler will be retained.

4. Suggestions must have document references matching the version
   Quotes can only come from the allowed list in references/docs-library.json. Unknown URLs and documents that do not match the framework version in the current package.json will be stripped. For example, features from Next.js 15 will not be recommended for Next.js 13 projects.

Framework coverage is determined by preflight reading package.json:

Signals marked Supported in the README include: Function invocation count, duration, TTFB, cold start, CPU/memory/GB-hours, request volume and cache hit rate, HTTP status and method distribution, Fast Data Transfer and bot traffic, ISR read/write, Routing Middleware, external API latency, Speed Insights Core Web Vitals, Image Optimization, Build Minutes, billing service usage spikes, Bot Protection / BotID, Fluid Compute, region fixation and inconsistent project configuration, Observability Events cost attribution, etc. Route-to-file mapping for Hono/Remix, and billing dimensions such as AI Gateway, Sandbox, Blob, Edge Config, Workflows, and Queues are still marked Planned in the README.

After a complete run, users will get: suggestions sorted by observation data, route and file locations when supported, before-and-after code snippets for implementable suggestions, document references from the allowed list, discoveries that are temporarily withheld due to insufficient evidence, a brief final explanation, and a complete Markdown report.

Installation and Activation¶

This Skill is not just an instruction document, but also includes scripts/, lib/, and references/. You must copy the entire skills/vercel-optimize directory during installation; running it with only a SKILL.md will not work.

Install with the skills CLI¶

Vercel released the open-source skills CLI in the January 20, 2026 changelog, which is used to install Skill packages for various Agents. Install only this one:

npx skills add vercel-labs/agent-skills --skill vercel-optimize

You can also install the entire official repository:

npx skills add vercel-labs/agent-skills

Add -a when specifying the tool. For example, install it only for Claude Code in the current project:

npx skills add vercel-labs/agent-skills --skill vercel-optimize -a claude-code

Cursor corresponds to -a cursor, and Codex CLI corresponds to -a codex. Add -g to install to the user’s global directory. The CLI will write to different paths according to the tool, and the official comparison is as follows:

The Cursor documentation will also additionally scan .cursor/skills/ and ~/.agents/skills/, and is compatible with .claude/skills/ and .codex/skills/. After installation, you can explicitly call it by entering /vercel-optimize in the Agent conversation; the Agent will also automatically select it when the description matches.

Manual Installation¶

The manual method from the official README is: copy skills/vercel-optimize to .agents/skills/vercel-optimize, and reference SKILL.md in the project’s AGENTS.md. The directory structure should be similar to:

.agents/skills/vercel-optimize/
├── SKILL.md
├── scripts/
├── references/
└── lib/

Pre-installation Environment Requirements¶

The Skill clearly states these prerequisites, and it will stop during the collection phase if any one is missing:

• Node.js 20+
• Vercel CLI v53+, and supports vercel metrics, vercel usage, vercel contract, vercel api (run npm i -g vercel@latest to update)
• Logged in: vercel login
• The current application directory has been linked with vercel link. VERCEL_PROJECT_ID can only assist in parsing project configuration, and cannot replace directory linking; vercel metrics still requires linking. The project, team/personal scope must be consistent, otherwise usage and route metrics may be associated with different accounts
• To generate “route-sorted, metric-backed” suggestions, you need Observability Plus

According to Vercel documentation: all tiers have basic Observability; Observability Plus is available for paid Pro and Enterprise plans, providing more detailed data such as path-split latency, cache, and ISR metrics. The Skill treats this as a data dependency rather than a promotion for an upgrade: without route-level metrics, it will stop and let you choose “restart after enabling” or “accept limited scanner-only audits”, and will not secretly degrade to a full repository code scan.

In addition, the Skill clearly requires: do not write authentication tokens into commands that may be echoed in chat history, and do not manually type VERCEL_TOKEN=..., --token ..., or Authorization: Bearer ....

Typical Usage¶

The following steps are from the official README and SKILL.md, and can be reproduced in this order.

1. Confirm the project is already linked¶

In the application root directory:

vercel login
vercel link

If you already know the project name and directory, you can also use:

vercel link --yes --project <project-name-or-id> --cwd <app-dir>
# Add --team <team-id-or-slug> for team projects

If the scope of the team project and personal project does not match, the Skill will stop and ask which one you want to audit, rather than guessing with the current vercel whoami team.

2. Send an optimization request to the Agent¶

Enter the linked Vercel project directory, and say to the coding Agent:

optimize this Vercel project

The official acceptance criteria are straightforward: the Agent should first collect metrics. If it reads the source code directly, or only guesses problems based on vercel.json, it means the Skill was not loaded correctly.

You can also say “help me reduce my Vercel bill”, “check the slow and expensive routes”, or “see if there are any caching opportunities”, all of which are included in the description trigger conditions in SKILL.md.

3. The actual pipeline the Agent will run¶

Users generally do not need to run these commands themselves; understanding the pipeline helps judge whether the Agent is executing according to the Skill. Each audit uses an independent run directory, and does not reuse previous briefings, subtask outputs, or reports:

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

node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
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"

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

The default budget is 6 code-side candidates. To expand the scope, you can use:

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"

After that, it will perform deep-dive checks, verify candidates, generate a briefing, validate suggestions, and finally render the report:

node scripts/render-report.mjs "$RUN_DIR/verify.json" "$RUN_DIR/gate.json" "$RUN_DIR/signals.json" \
  --project <name> \
  --out "$RUN_DIR/report.md" \
  --message-out "$RUN_DIR/final-message.json"

After rendering is complete, the Agent should output the final-message.json.body as-is, followed by the complete Markdown report. Do not expose implementation details such as passRate, quality scores, sanitizer traces, or sub-Agent names in user-facing copy.

4. What the suggestions look like¶

The qualified format specified in doctrine.md is: about 5–15 suggestions per run; each corresponds to a specific route or file, and specific metrics; when code is involved, before-and-after examples are provided, and at least one document reference matching the current framework version is included.

Performance numbers must come from observations, for example, reducing the 95th percentile latency of /api/products from 850ms to a range close to similar cached routes. Costs can only use magnitude wording (mapped from vercel usage to statements like “based on current traffic, it is approximately hundreds of dollars per month”), and exact savings such as $340/mo are prohibited. A sanitizer during the output phase will strip $N literals from user-facing fields.

Applicable Scenarios and Notes¶

It is suitable for these situations:
- The project has been deployed on Vercel and has had considerable traffic in the last 14 days
- The tech stack is Next.js, SvelteKit, or can accept Nuxt / limited Astro coverage
- The local machine is logged in to the Vercel CLI, and the directory has been linked with vercel link, and you need to prioritize fixes based on real usage
- You want to get a complete report of “suggestions + evidence + items not investigated for now”, rather than a list of anti-patterns

Before using it, you need to note:
1. Without Observability Plus, there will be no complete route-sorted audit. Basic Observability is not enough to support gates such as slow_route, uncached_route, cold_start, and isr_overrevalidation. The Skill will stop and let you choose to restart after enabling, or accept a limited audit that can only catch traffic-independent code issues.
2. When there is almost no traffic in the last 14 days, route metrics will be sparse. The official failure copy will state that: you can still check traffic-independent scanning items and project settings, but you cannot sort route fixes.
3. Hono, Remix, and unknown frameworks will not continue by default. Limited platform/code audits can only be performed after user confirmation, and route-level metrics may not map back to source files.
4. Do not treat wall clock time as the only problem. For Vercel Workflow runtime endpoints (/.well-known/workflow/v1/*), and routes with intentional long connections such as SSE, streaming, and recoverable chats, the Skill prohibits suggesting “shorten the duration” solely because of high duration; there must be avoidable pre-first-byte work, high CPU, repeated calls, or post-response work that can be moved out of the user path.
5. Authentication, error pages, geographically varying responses, etc., are kept dynamic by default. No suggestions will be made to add caching to these paths without evidence that they can be safely cached.
6. Facts already in the project configuration will not be suggested again for “confirm whether it is enabled”. For example, when Fluid Compute has already been enabled, the validator will block suggestions such as “please enable Fluid Compute”.
7. Things explicitly out of scope: Pure production bundle size (unless it manifests as cold start, Fast Data Transfer, or LCP/INP), build slowdowns that do not hit Build Minutes billing, security vulnerabilities and credential rotation, contract discounts and seat reconciliation. Security settings will only be included if they are also cost levers (such as BotID and edge costs from bot traffic).

Summary¶

vercel-optimize turns “check Vercel bills and Observability, then decide which routes to modify” into a reusable Skill in tools such as Cursor, Claude Code, and Codex CLI. What it really restricts is the investigation order: metrics → deterministic gatekeeping → limited file scope → version-matched document references, preventing the Agent from making changes based on an anti-pattern list across the repository.

When the project has been deployed, has traffic, and the CLI is linked, just say “optimize this Vercel project” in the application directory. The official repository and Skill directory:

https://github.com/vercel-labs/agent-skills/tree/main/skills/vercel-optimize