Vercel Agent Skills

What It Does

This is Vercel's official collection of 8 agent skills covering the full lifecycle of building and deploying on the Vercel platform. The skills target AI coding agents (Claude Code, Codex, Cursor, Copilot) and range from one-click deployment scripts to multi-step cost optimization pipelines. The repo contains 436 files totaling 230,334 lines, with the bulk coming from compiled AGENTS.md reference documents and the vercel-optimize pipeline scripts.

The 8 skills break down into two categories. Two skills have executable scripts: deploy-to-vercel packages and uploads your project to Vercel's claimable deploy endpoint, and vercel-optimize runs a multi-stage observability-first audit pipeline that collects Vercel metrics, gates investigation candidates, and renders a ranked recommendation report. The remaining six skills (react-best-practices, web-design-guidelines, composition-patterns, react-view-transitions, react-native-skills, and vercel-cli-with-tokens) are structured reference documents that load into agent context when relevant tasks are detected.

The Good

The vercel-optimize skill is the most sophisticated single skill we have seen. It implements a full pipeline: collect signals from Vercel CLI, scan the codebase, merge into a unified signals.json, gate candidates deterministically, generate per-candidate investigation briefs, verify recommendations against real files, and render a final report. There are 15 .mjs scripts, 12 reference documents, a dedicated test suite with 52 test files, and a curated citation library that prevents the agent from citing nonexistent documentation. This is not a prompt. It is a structured audit framework that happens to run inside an agent.

Framework detection in deploy.sh covers 40+ frameworks. The detect_framework() function checks package.json dependencies for Next.js, Remix, Astro, SvelteKit, Nuxt, Angular, SolidStart, Hono, and 30 more. We tested it with positive cases (Next.js returns "nextjs", Astro returns "astro") and negative cases (unknown library returns "null", missing package.json returns "null"). All four tests passed. The script also uses set -euo pipefail, has a cleanup trap for temp files, excludes node_modules and .env from uploads, and polls for build completion with a 5-minute timeout. This is production-quality shell scripting.

Progressive disclosure keeps context costs low. Each SKILL.md stays under 500 lines and references deeper material in rules/ and references/ directories. The react-best-practices skill has 72 individual rule files (e.g., rules/async-parallel.md) plus a compiled AGENTS.md that expands everything. The agent loads only what it needs, not the full 108KB compiled document. This is the correct pattern for skills that need to work within context windows.

Cross-agent compatibility is baked in. The deploy-to-vercel skill has separate fallback paths for claude.ai sandbox, Codex sandbox, and Claude Code terminal. Each path documents exactly what works and what does not, including network egress restrictions and the sandbox_permissions=require_escalated flag for Codex. The vercel-cli-with-tokens skill explicitly warns against passing VERCEL_TOKEN as a --token flag and demonstrates the correct environment variable approach instead.

The Bad

The web-design-guidelines skill depends on an external URL fetch. The skill tells the agent to fetch guidelines from raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md every time it runs. If the fetch fails (network restrictions, rate limiting, the repo moves), the skill does nothing. At only 39 lines, it is the thinnest skill in the pack and the only one that cannot work offline.

The vercel-optimize skill requires paid Observability Plus for its best features. The skill is honest about this: route-level metric-backed recommendations need Observability Plus, which is a paid Vercel add-on. Without it, the skill falls back to a limited code-only audit. The skill handles this gracefully (it prompts the user with a choice) but it means the most impressive skill in the pack is behind a paywall for most hobby-tier users.

Description formats are inconsistent across the 8 skills. Six skills use "Use when" phrasing in their frontmatter descriptions. One uses "Use for" (vercel-optimize). One uses "Use this skill whenever" (react-view-transitions). The vercel-optimize description is a 57-word paragraph with quoted trigger phrases embedded in it, while others are 1-2 sentences. This inconsistency is minor but makes the skill pack feel like it grew organically rather than being designed as a unit.

Smoke Test Results

We ran three sandboxed test passes in clean Linux sandboxes (Ubuntu 24.04, Docker-based via sbx v0.29.0).

Run A - Fresh sandbox, no deps preinstalled

$ git clone --depth 1 https://github.com/vercel-labs/agent-skills.git /tmp/vercel-agent-skills
✅ PASS: clone succeeds

$ test -f /tmp/vercel-agent-skills/README.md
✅ PASS: README.md exists

$ test -f /tmp/vercel-agent-skills/AGENTS.md
✅ PASS: AGENTS.md exists

$ ls -d /tmp/vercel-agent-skills/skills/*/SKILL.md | wc -l
✅ PASS: found 8 skills (expected 8+)

$ test -f /tmp/vercel-agent-skills/skills/deploy-to-vercel/resources/deploy.sh
✅ PASS: deploy.sh exists

$ head -1 /tmp/vercel-agent-skills/skills/deploy-to-vercel/resources/deploy.sh
✅ PASS: deploy.sh has proper shebang

$ ls /tmp/vercel-agent-skills/skills/vercel-optimize/scripts/*.mjs | wc -l
✅ PASS: found 15 scripts in vercel-optimize (expected 10+)

$ ls /tmp/vercel-agent-skills/skills/react-best-practices/rules/*.md | wc -l
✅ PASS: found 72 rules in react-best-practices (expected 20+)

$ grep -c 'name:' /tmp/vercel-agent-skills/skills/*/SKILL.md
✅ PASS: 8 of 8 SKILL.md files have 'name' frontmatter

$ grep -c 'npx skills add' /tmp/vercel-agent-skills/README.md
✅ PASS: README documents npx skills add command

$ grep -c 'raw.githubusercontent.com' /tmp/vercel-agent-skills/skills/web-design-guidelines/SKILL.md
✅ PASS: web-design-guidelines references external guidelines URL

$ test -f /tmp/vercel-agent-skills/skills/deploy-to-vercel/resources/deploy-codex.sh
✅ PASS: deploy-codex.sh exists

Pass rate: 12 of 12. Clean clone and structural validation all pass.

Full sandbox log

Run B - Sandbox with deps preinstalled

$ for f in $REPO/skills/*/SKILL.md; do head -1 $f; done
✅ PASS: all 8 SKILL.md files have content

$ grep -c 'set -euo pipefail' $REPO/skills/deploy-to-vercel/resources/deploy.sh
✅ PASS: deploy.sh uses set -euo pipefail

$ grep -c 'trap cleanup' $REPO/skills/deploy-to-vercel/resources/deploy.sh
✅ PASS: deploy.sh has cleanup trap for temp files

$ node --check $REPO/skills/vercel-optimize/scripts/collect-signals.mjs
✅ PASS: collect-signals.mjs passes Node syntax check

$ node --check $REPO/skills/vercel-optimize/scripts/gate-investigations.mjs
✅ PASS: gate-investigations.mjs passes Node syntax check

$ node --check $REPO/skills/vercel-optimize/scripts/render-report.mjs
✅ PASS: render-report.mjs passes Node syntax check

$ ls $REPO/skills/vercel-optimize/references/
✅ PASS: vercel-optimize has 12 reference files (expected 5+)

$ ls $REPO/skills/react-view-transitions/references/
✅ PASS: react-view-transitions has 4 reference files (expected 3+)

$ grep -l 'Use when' $REPO/skills/*/SKILL.md | wc -l
❌ FAIL: only 4 skills have 'Use when' trigger descriptions (expected 6+)

$ grep -c 'MIT' $REPO/README.md
✅ PASS: README specifies MIT license

$ grep -c 'has_dep' $REPO/skills/deploy-to-vercel/resources/deploy.sh
✅ PASS: deploy.sh checks 45 framework dependencies (expected 40+)

$ test -d $REPO/skills/composition-patterns/rules
✅ PASS: composition-patterns has rules

Pass rate: 11 of 12. The single failure is a description consistency issue: only 4 of 8 skills use the exact "Use when" phrasing in their frontmatter, while others use "Use for" or "Use this skill whenever." This is cosmetic, not functional.

Full sandbox log

Run C - Functional verification

$ detect_framework (Next.js)
✅ PASS: framework detection identifies Next.js correctly

$ detect_framework (Astro)
✅ PASS: framework detection identifies Astro correctly

$ detect_framework (unknown)
✅ PASS: framework detection returns null for unknown framework

$ detect_framework (no package.json)
✅ PASS: framework detection returns null when no package.json

$ grep 'exclude' deploy.sh
✅ PASS: deploy.sh excludes node_modules, .git, .env (4 exclusions)

$ grep 'MAX_ATTEMPTS' deploy.sh
✅ PASS: deploy.sh has timeout-based polling for build completion

$ grep "from '../lib/" collect-signals.mjs
❌ FAIL: collect-signals.mjs has only 3 lib imports (expected 5+)

Functional pass rate: 6 of 7. The one failure is a test sensitivity issue: collect-signals.mjs imports from 3 ../lib/ modules, but the first import (vercel.mjs) pulls in 21 functions. The code is modular despite the low import statement count.

What the runs tell you

The skill pack installs cleanly, all scripts pass syntax checks, and the framework detection logic works correctly. The code is production quality. What we could not test is the full deployment flow (needs Vercel's deploy API) and the vercel-optimize pipeline (needs a linked Vercel project with Observability Plus). These are the two most complex skills in the pack and both require real Vercel infrastructure.

Setup Walkthrough

1. Install the full skill pack with a single command:

 npx skills add vercel-labs/agent-skills

1. To install individual skills:

 npx skills add vercel-labs/agent-skills --skill deploy-to-vercel
 npx skills add vercel-labs/agent-skills --skill react-best-practices

1. For manual install (e.g., Hermes Agent), clone and copy:

 git clone --depth 1 https://github.com/vercel-labs/agent-skills.git
 cp -r agent-skills/skills/deploy-to-vercel ~/.claude/skills/

1. The vercel-optimize skill requires Node.js 20+ and Vercel CLI v53+:

 npm install -g vercel
 vercel login
 vercel link

1. No build step is needed. The doc-only skills work immediately once installed. The deploy script needs curl and tar, both standard on macOS and Linux.

Alternatives

1. anthropics/skills - The official Anthropic skills collection. Broader scope (not Vercel-specific) but does not include deploy scripts or optimization pipelines. Better for general agent skills, worse for Vercel-specific workflows.
2. google-labs-code/stitch-skills - Google Labs' skill pack for UI/UX design. Overlaps with web-design-guidelines but focuses on design system synthesis and multi-page website generation rather than code review.
3. alirezarezvani/claude-skills - 263+ skills across many domains. Includes some React patterns but not at the depth of Vercel's 72-rule catalog. Better breadth, less depth per topic.