vercel-optimize

Name: vercel-optimize
Author: vercel-labs

39kinstalls2.6kforks

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.

Summary

Use for Vercel cost and performance optimization on deployed projects, especially Next.js, SvelteKit, Nuxt, and limited Astro apps. Collect Vercel metrics, usage, project config, and code scan results first; investigate only metric-backed candidates; produce ranked recommendation

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,

People who liked this also viewed

6 picks

Type

vercel-optimize

39kinstalls2.6kforks

View on GitHub

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.

Summary

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,

People who liked this also viewed

6 picks

Type