vercel-optimize

Name: vercel-optimize
Author: vercel-labs

byvercel-labs· 154 skills

Installs

42k

Stars

29k

Forks

2.6k

How to install vercel-optimize?

vercel-labs/agent-skills/vercel-optimize

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

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/vercel-labs/agent-skills" --skill "vercel-labs/agent-skills/vercel-optimize"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/vercel-labs/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/vercel-labs/agent-skills"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# Vercel Optimize
2
3	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.
4
5	Core doctrine: read [references/doctrine.md](references/doctrine.md) if any rule is unclear.
6
7	- Metrics first. Recommendations start from Vercel production signals, not repo-wide grep.
8	- Deterministic gates. `scripts/gate-investigations.mjs` decides what deserves investigation.
9	- Candidate-bound scope. Read only files named by a candidate or a route-local import chain.
10	- Version-aware citations. Use only `references/docs-library.json`; invalid or version-mismatched citations are stripped.
11	- Customer copy. Read [references/voice.md](references/voice.md) before writing report text or chat output.
12
13	## Prerequisites
14
15	- Vercel CLI v53+ with `vercel metrics`, `vercel usage`, `vercel contract`, and `vercel api`.
16	- Authenticated CLI session: `vercel login`.
17	- 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.
18	- Node.js 20+.
19	- Observability Plus for route-level metric-backed recommendations.
20
21	Never put auth tokens in shell commands. Do not type `VERCEL_TOKEN=...`, `--token ...`, or `Authorization: Bearer ...` into commands that may be echoed in chat.
22
23	## Framework Support
24
25	The preflight reads `package.json` and sets expectations before metric fan-out.
26
27	\| Framework \| Status \| Notes \|
28	\|---\|---\|---\|
29	\| Next.js App Router \| supported \| strongest route mapping, scanners, playbooks, citations \|
30	\| Next.js Pages Router \| supported \| scoped to Pages Router idioms when detected \|
31	\| SvelteKit \| supported \| route mapping for `src/routes` files and SvelteKit scanner \|
32	\| Nuxt \| supported \| route mapping plus generic/platform checks; fewer framework-specific recs \|
33	\| Astro \| limited \| route mapping plus generic checks; fewer framework-specific recs \|
34	\| Hono / Remix / unknown \| blocked by default \| continue only if the user accepts a limited platform/code-only audit \|
35
36	If unsupported, stop and ask before scanning or gating:
37
38	```text
39	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.
40
41	Do you want me to continue with the limited audit, or stop here?
42	```
43
44	If the user continues, rerun collection with `--continue-unsupported-framework`.
45
46	## Run Directory
47
48	Use a fresh run directory for every audit. Do not reuse briefs, sub-agent outputs, or reports across runs.
49
50	```bash
51	RUN_DIR="$(mktemp -d -t vercel-optimize-XXXXXX)"
52	```
53
54	## Pipeline
55
56	### 1. Collect, scan, and merge signals
57
58	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.
59
60	```bash
61	node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
62	node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "$RUN_DIR/vercel-signals.json"
63
64	node scripts/scan-codebase.mjs <repo-root> > "$RUN_DIR/codebase.json"
65	node scripts/merge-signals.mjs "$RUN_DIR/vercel-signals.json" "$RUN_DIR/codebase.json" --out "$RUN_DIR/signals.json"
66	```
67
68	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.
69
70	`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.
71
72	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.
73
74	Use this prompt for `PROJECT_SCOPE_UNRESOLVED`, `SCOPE_UNRESOLVED`, or `PROJECT_SCOPE_MISMATCH`:
75
76	```text
77	I can't safely identify the Vercel project and account for this audit yet.
78
79	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.
80	```
81
82	### 1.1 Stop on blockers
83
84	Check blockers before gating:
85
86	```bash
87	jq '{frameworkSupportBlocker, observabilityPlus, observabilityPlusUsable, observabilityPlusBlocker, observabilityPlusBlockerDetail}' "$RUN_DIR/signals.json"
88	```
89
90	Required actions:
91
92	- `frameworkSupportBlocker === "unsupported_framework"`: use the unsupported-framework prompt above.
93	- `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`.
94	- `observabilityPlusBlocker === null`: continue.
95	- `no_traffic`: tell the user route metrics are sparse; continue only if they accept limited output.
96	- `payment_required` or `no_oplus_probe`: render [references/observability-plus.md](references/observability-plus.md) verbatim and ask.
97	- `project_disabled`: tell the user to enable Observability Plus for the project or accept a limited audit.
98	- `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.
99	- `not_linked`: link the app directory, then rerun Step 1. If app path and project are known:
100
101	```bash
102	vercel link --yes --project <project-name-or-id> --cwd <app-dir>
103	# add --team <team-id-or-slug> when known
104	```
105
106	- `forbidden` or `project_not_found`: fix auth/team scope. Do not pitch Observability Plus.
107	- `all_failed_other`: show the raw error code and ask whether to continue in limited code-only mode.
108
109	Do not silently fall back to code-only mode. If the user accepts a limited audit, rerun collection with:
110
111	```bash
112	node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
113	```
114
115	Then scan and merge again.
116
117	### 2. Gate candidates
118
119	```bash
120	node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"
121	```
122
123	Output shape:
124
125	- `toLaunch`: code-scope candidates to investigate.
126	- `platform`: project/account-scope recommendations.
127	- `gated`: skipped, covered, or disqualified candidates that must still appear in the report.
128	- `budget`: candidate budget and selection mode.
129
130	Default budget is 6 code-scope candidates with a diversity guardrail. To expand:
131
132	```bash
133	node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates 12 > "$RUN_DIR/gate.json"
134	node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates all > "$RUN_DIR/gate.json"
135	```
136
137	Generated candidate docs: [references/candidates.md](references/candidates.md).
138
139	### 2.1 Ask about audit scope when needed
140
141	Before deep-dive, run:
142
143	```bash
144	node scripts/budget-summary.mjs "$RUN_DIR/gate.json" --format json > "$RUN_DIR/budget-summary.json"
145	```
146
147	If `shouldAsk` is false, continue.
148
149	If `shouldAsk` is true:
150
151	1. Print `exactChatMessage.body` exactly as returned. Do not summarize, truncate, reorder, or rewrite it.
152	2. Then ask `questionText` using `questionPayload` when the host supports structured questions.
153	3. If the user chooses a different number, rerun the gate with `--max-candidates <choice>`.
154
155	Never put the long preview inside the question field. The preview and the question are separate surfaces.
156
157	### 2.2 Deep-dive and reconcile
158
159	```bash
160	node scripts/deep-dive.mjs "$RUN_DIR/signals.json" "$RUN_DIR/gate.json" --cwd <project-dir> > "$RUN_DIR/investigation-evidence.json"
161
162	node scripts/reconcile-candidates.mjs "$RUN_DIR/investigation-evidence.json" \
163	--gate "$RUN_DIR/gate.json" \
164	--out "$RUN_DIR/reconciled-investigation.json"
165	```
166
167	`--cwd` must be the linked project directory so `deep-dive.mjs` can verify the same project link and reuse `signals.json.commandScope.cliScope` for any follow-up `vercel metrics` calls.
168
169	Reconciliation deterministically converts disproven candidates into observations before any source investigation:
170
171	- `metric_mismatch`
172	- `error_storm`
173	- `deployment_regression`
174	- `scanner_only_no_metric`
175
176	### 2.3 Generate briefs and investigate
177
178	List the work:
179
180	```bash
181	node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" --list > "$RUN_DIR/briefs-manifest.json"
182	```
183
184	Generate one brief for every entry in `briefs-manifest.json.briefs`. The `group` can be `toLaunch` or `platform`; do not generate only `toLaunch` briefs.
185
186	```bash
187	mkdir -p "$RUN_DIR/briefs" "$RUN_DIR/sub-agent-outputs"
188	node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" \
189	--group <brief.group> --index <brief.index> --out "$RUN_DIR/briefs/<brief.group>-<brief.index>.md"
190	```
191
192	Use `briefs-manifest.json.briefs[].label` for visible worker names, for example `Low cache-hit route on /docs/llm-digest/[...slug]`, not `toLaunch-7`.
193
194	Fan-out rule:
195
196	- 1-2 briefs: investigate inline.
197	- 3+ briefs: spawn one sub-agent per brief when the host supports it.
198	- Hosts without sub-agents: run inline serially.
199
200	Sub-agent contract:
201
202	- The brief is the whole prompt.
203	- Read only files listed in the brief, plus route-local imports when needed.
204	- Emit one JSON recommendation or one JSON no-change finding using [references/recommendations.md](references/recommendations.md).
205	- Do not cite URLs outside the provided citation subset.
206	- Do not recommend framework features unavailable in the detected version.
207
208	If a sub-agent reaches for repo-wide grep, the candidate is malformed; drop or abstain rather than widening scope.
209
210	### 2.4 Collect outputs
211
212	Save each raw investigation result in `$RUN_DIR/sub-agent-outputs/`, then collect:
213
214	```bash
215	node scripts/collect-sub-agent-outputs.mjs \
216	--manifest "$RUN_DIR/briefs-manifest.json" \
217	--out "$RUN_DIR/recommendations.json" \
218	"$RUN_DIR/sub-agent-outputs/"
219	```
220
221	The collector extracts JSON, prepends pre-resolved records, enforces manifest order, and fails on missing, duplicate, unknown, or mismatched `candidateRef` values.
222
223	### 3. Verify recommendations
224
225	```bash
226	node scripts/verify-and-regen.mjs "$RUN_DIR/recommendations.json" \
227	--signals "$RUN_DIR/signals.json" \
228	--repo-root <project-dir> \
229	--out "$RUN_DIR/verify.json"
230	```
231
232	This script extracts claims, verifies files/citations/version fit, grades quality, applies sanitizers, emits `verifiedRecommendations`, `withheldRecommendations`, `renderableRecommendations`, and creates `regenPlan` for failed or unsafe recommendations.
233
234	Recommendation schema, writing rules, sanitizer order, and grading rules: [references/recommendations.md](references/recommendations.md). Verification rules: [references/verification.md](references/verification.md).
235
236	For each `regenPlan` entry, rerun the same brief with a `Previous attempt failed these checks` section listing `topFailures`. Keep the regenerated output only if verification improves without gutting citations.
237
238	### 4. Render report and final message
239
240	```bash
241	node scripts/render-report.mjs "$RUN_DIR/verify.json" "$RUN_DIR/gate.json" "$RUN_DIR/signals.json" \
242	--project <name> \
243	--out "$RUN_DIR/report.md" \
244	--message-out "$RUN_DIR/final-message.json"
245	```
246
247	Use `--debug-out "$RUN_DIR/debug.json"` only when developing the skill. Customer Markdown and chat output must not expose `passRate`, `quality`, sanitizer trails, raw sub-agent names, or other implementation fields.
248
249	After rendering, print `final-message.json.body` verbatim and stop. Do not add highlights, debug notes, raw counts, sub-agent summaries, or extra explanation. Render-time dedupe, platform caps, and hard-safety drops can change the customer-visible count, so never summarize from raw `verify.json`.
250
251	Report structure and impact framing: [references/scoring.md](references/scoring.md).
252
253	## Recommendation Rules
254
255	Every recommendation must:
256
257	- Trace to a launched candidate, platform candidate, pre-resolved observation, or verified traffic-independent scanner finding.
258	- Include observed metric evidence from `signals.json` or `evidence.deepDive`.
259	- Cite verified files with line numbers when code is involved.
260	- Include at least one allowed citation that applies to the detected framework/version.
261	- Use precise observed performance numbers.
262	- Use cost magnitude phrases only; never customer-facing `$N` savings.
263	- Do not recommend duration reductions for Vercel Workflow runtime endpoints (`/.well-known/workflow/v1/*`). These are generated orchestration routes for durable step/flow execution and should be hard-gated before investigation.
264	- Workflow recommendations must name the boundary being changed. Valid examples: enqueue durable work and return a run ID instead of awaiting completion, fix stream replay/closure/locks, or reduce verified excess Workflow Steps/Storage. Do not infer cost savings from Workflow endpoint wall-clock duration.
265	- For streaming, SSE, resumable chat, or other intentionally long-lived routes, do not frame wall-clock function duration as a problem by itself. Require evidence of avoidable pre-first-byte work, high active CPU, duplicate invocations, or post-response work that can move out of the user-visible path.
266	- Name a specific cache policy when recommending caching.
267	- Keep unsafe responses dynamic unless evidence proves they are safe to cache: auth-sensitive paths, errors, fallback responses, missing content, invalid requests, geolocation/device-varying output, and unversioned dynamic URLs.
268
269	Never recommend "verify X is on" for facts already present in `signals.project`, including Fluid compute status, memory tier, regions, in-function concurrency, and timeout.
270
271	## Scanner Rules
272
273	Scanner findings are supplementary. Drop findings annotated `COLD-PATH` or `NO-ROUTE-MAPPING` unless the scanner declares `metadata.trafficIndependent === true`.
274
275	Traffic-independent examples: middleware matcher, source maps, React Compiler config, build settings. Route-local cache or data-fetch patterns need route-level traffic evidence.
276
277	Scanner docs: [references/scanner-patterns.md](references/scanner-patterns.md).
278
279	## Final Customer Terms
280
281	Use:
282
283	- `recommendations ready`
284	- `observations from investigation`
285	- `investigated, no change recommended`
286	- `not investigated in this run`
287
288	Avoid:
289
290	- `sub-agent`
291	- `abstention`
292	- `passRate`
293	- `quality score`
294	- `gate`
295	- `LLM`
296
297	## Failure Copy
298
299	Use these messages without adding sales copy or process detail.
300
301	No traffic in the last 14 days:
302
303	> This project has no meaningful traffic in the last 14 days, so route-level metrics are sparse. I can still check traffic-independent scanner findings and project settings, but I cannot rank route fixes until traffic accumulates.
304
305	Route-level metrics unavailable:
306
307	> Use the verbatim choice template in [references/observability-plus.md](references/observability-plus.md). Do not silently fall back to code-only mode; present the two-path choice: enable Observability Plus and rerun the metric-backed audit, or accept a limited code-only run.
308
309	Project is not linked:
310
311	> This worktree is not linked to a Vercel project. Run `vercel link --yes --project <project-name-or-id> --cwd <app-dir>` and rerun the audit. If the team is known, add `--team <team-id-or-slug>`.
312
313	Most route-to-file mappings failed:
314
315	> The route inventory matched fewer than half of the routes we saw in observability. This is common in monorepos with custom routing. I've surfaced what I can match; the rest appear in the "Not investigated in this run" section.

6 picks

Type

Run `npx skills use "https://github.com/vercel-labs/agent-skills" --skill "vercel-labs/agent-skills/vercel-optimize"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/vercel-labs/agent-skills" that are relevant to the current task. Run `npx skills add "https://github.com/vercel-labs/agent-skills"` and select the relevant skills, then follow their instructions.

vercel-optimize

How to install vercel-optimize?

Related

vercel-optimize

How to install vercel-optimize?

Related