Vercel Optimize
Audit a live Vercel deployment for cost and latency using CLI metrics, gated scripts, and a verified optimization report—not guesswork from source alone.
Overview
vercel-optimize is an agent skill most often used in Operate (also Ship) that produces a Vercel cost and performance report from CLI observability, gated scripts, and verified route-level recommendations.
Install
npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-optimizeWhat is this skill?
- Observability-first doctrine: collect Vercel CLI signals before diving into application source
- Deterministic gate scripts to launch only candidate routes/issues, then investigate named files only
- Targets high bills, slow routes, cache misses, and excess function invocations on Vercel
- Requires Vercel CLI v53+ with metrics, usage, contract, and api commands plus linked project directory
- Observability Plus needed for per-route metric analysis per skill requirements
- Node.js 20+ required
- Vercel CLI v53+ compatibility floor
- Five-step procedure: read SKILL.md, collect CLI signals, run gates, investigate named files, verify before report
Adoption & trust: 11.9k installs on skills.sh; 27.7k GitHub stars.
What problem does it solve?
Your Vercel bill or cold routes are hurting margin, but you cannot tell whether the fix is caching, function churn, or mis-scoped config without platform metrics.
Who is it for?
Solo builders with production Vercel traffic who want a disciplined, metrics-led pass over cost and performance—not a blanket lint of the repo.
Skip if: Projects not on Vercel, apps with no traffic yet, or general code-quality reviews unrelated to hosting spend and route behavior.
When should I use this skill?
User asks to optimize a Vercel project, reduce a Vercel bill, investigate slow or expensive routes, find caching opportunities, reduce function invocations, or produce a Vercel cost/performance report.
What do I get? / Deliverables
You get a mechanically verified optimization report tied to real Vercel usage and route signals, with investigations limited to files named by deterministic candidates.
- Verified Vercel cost and performance report
- Candidate-bound investigation notes for named routes and files
- Actionable caching and invocation reduction recommendations backed by CLI checks
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Operate → infra is the canonical shelf because the skill assumes traffic, billing, and production route metrics on an already-linked Vercel project. Infra covers spend, invocation volume, caching, and platform configuration—the same levers this skill reads via vercel usage, metrics, and contract APIs.
Where it fits
After release, triage which routes drive p95 latency using vercel metrics before changing code.
Correlate vercel usage and contract signals when monthly spend jumps without a clear product change.
Repeat the gated workflow after deploying cache header fixes to confirm invocation counts dropped.
Connect expensive API routes to traffic patterns once Observability Plus per-route data is available.
How it compares
Use instead of ad-hoc “read the Next.js code and suggest caching”—this skill mandates Vercel CLI observability and deterministic gates before source edits.
Common Questions / FAQ
Who is vercel-optimize for?
Indie developers and small teams running SaaS or APIs on Vercel who need structured help reducing cost and improving route performance.
When should I use vercel-optimize?
Use it in Operate when monitoring bills and infra, and in Ship under perf when investigating slow or expensive routes after launch—especially when the user asks for a Vercel cost or performance report.
Is vercel-optimize safe to install?
Check the Security Audits panel on this Prism page; the skill expects authenticated Vercel CLI access, shell execution, and reading project configuration tied to your deployment account.
SKILL.md
READMESKILL.md - Vercel Optimize
# vercel-optimize Cross-agent entry point for the Vercel Optimize skill. The full procedure is in [SKILL.md](./SKILL.md). Use this skill when the user asks to optimize a Vercel project, reduce a Vercel bill, investigate slow or expensive routes, find caching opportunities, reduce function invocations, or produce a Vercel cost/performance report. Do not use it for projects that are not deployed on Vercel, greenfield projects with no traffic, or general code review. ## Requirements - Node.js 20+ - Vercel CLI with `vercel metrics`, `vercel usage`, `vercel contract`, and `vercel api` support; v53+ is this skill's compatibility floor - Authenticated Vercel CLI session - Linked Vercel project directory (`vercel link`) for route metrics. `VERCEL_PROJECT_ID` can help resolve project config, but it does not replace directory linkage for `vercel metrics`. The project must resolve to a CLI-safe team or personal scope so `vercel metrics`, `vercel usage`, and `vercel contract` all run against the same account. - Observability Plus for per-route metric analysis ## Procedure 1. Read [SKILL.md](./SKILL.md). 2. Collect Vercel signals before reading source files. 3. Gate candidates with deterministic scripts. 4. Investigate only files named by launched candidates. 5. Verify recommendations mechanically before rendering the report. The hard rules are in [references/doctrine.md](./references/doctrine.md): observability first, deterministic gates, candidate-bound scope, and version-aware citations. ## Install Preferred: ```bash npx skills add vercel-labs/agent-skills --skill vercel-optimize ``` Manual project install: ```bash mkdir -p .agents/skills cp -R <agent-skills-repo>/skills/vercel-optimize .agents/skills/ ``` Then add this to the project `AGENTS.md`: ```md When optimizing Vercel cost or performance, follow `.agents/skills/vercel-optimize/SKILL.md` before proposing changes. Collect Vercel metrics before reading source files. ``` # Contributing to `vercel-optimize` Keep changes small, metric-grounded, and fixture-tested. Runtime code lives in `skills/vercel-optimize`; tests and fixtures live in `packages/vercel-optimize-tests` so installed skills stay small. ## Common changes | Change | Edit | Test | |---|---|---| | Gate | `lib/gates/<id>.mjs`, `lib/gates/index.mjs` | `node --test packages/vercel-optimize-tests/test/*gate*.test.mjs` | | Scanner | `lib/scanners/<id>.mjs`, `lib/scanners/index.mjs` | Scanner-specific test in `packages/vercel-optimize-tests/test/` | | Citation | `references/docs-library.json` | `node skills/vercel-optimize/scripts/check-citations.mjs` | | Support topic | `references/support-topics/<id>.md` | `node --test packages/vercel-optimize-tests/test/support-topics.test.mjs` | | Playbook | `references/playbooks/<profile>.md` and selection matrix in `references/scoring.md` | `node --test packages/vercel-optimize-tests/test/support-topics.test.mjs packages/vercel-optimize-tests/test/investigation-brief.test.mjs` | | Renderer or verifier | `lib/render-report.mjs`, `lib/verify-claim.mjs`, or related module | Focused test plus full test suite | Generated docs: ```bash node skills/vercel-optimize/scripts/build-docs.mjs node skills/vercel-optimize/scripts/check-docs-fresh.mjs ``` Full test loop: ```bash node --test packages/vercel-optimize-tests/test/*.test.mjs node skills/vercel-optimize/scripts/check-docs-fresh.mjs node skills/vercel-optimize/scripts/check-citations.mjs ``` ## Rules - No runtime dependencies. Scripts use Node.js 20+ built-ins and the Vercel CLI. - No recommendation without a Vercel metric signal, code evidence when code changes are proposed, and an allow-listed citation. - No invented URLs, exact savings projections, or version-mismatched framework APIs. - No internal repo paths, service names, customer names, or captured private output in fixtures. - Keep generated report copy customer-facing. Put debug details behind `--debug-out`. ## Output contracts Every JSON-emitting script mus