Agent Skills in Next.js: The Performance Revolution

How Vercel’s modular AI expertise packages are turning 10 years of React optimization knowledge into one-command performance upgrades — and what it means for the way you ship.

What Are Agent Skills?

Agent Skills are modular packages of instructions and scripts designed for AI coding agents like Claude Code, Cursor, and Codex. Think of them as npm packages — but instead of shipping JavaScript, they ship expertise.

A skill is a versioned folder that bundles:

• SKILL.md — the instruction set with YAML frontmatter
• scripts/ — executable helper scripts for audits and modifications
• references/ — extended checklists and style guides
• assets/ — diagrams and static files

The core problem they solve is the “blank slate” issue: AI models know React in general but lack your project’s specific constraints and the high-end heuristics that senior engineers carry in their heads. Skills close that gap, transforming a general assistant into a “React Performance Expert” the moment you load the relevant package.

Key Concept: Skills use “progressive disclosure” — the agent reads only the skill’s name and description first, then loads the full instructions only when a trigger phrase like “Review my React performance” is detected. This keeps context windows lean.

Installing the Skills CLI

Vercel ships a CLI called npx skills that acts as the package manager for this ecosystem. It discovers, installs, symlinks, and updates skills across every agent on your machine from a single source of truth.

# Install a skill globally
npx skills add vercel-labs/react-best-practices
# Search the skills registry
npx skills find "performance"
# Check installed skills across all agents
npx skills list
# Update all skills to latest
npx skills update

Skills are symlinked from .agents/skills to each agent's folder (e.g. ~/.claude/skills). One update, every agent gets it instantly — mirroring how pnpm handles shared packages.

How the Lock File Works

The CLI maintains ~/.agents/.skill-lock.json (currently v3). For each skill it stores a skillFolderHash. When you run skills update, it POSTs these hashes to the central API with forceRefresh: true, bypassing Redis cache to compare against the live GitHub state — ensuring real-time diff detection rather than stale data.

The react-best-practices Skill

This is the flagship: 57 rules, prioritized by impact on Core Web Vitals, targeting bottlenecks that are invisible to general-purpose AI. Here’s what it enforces.

Priority 1 — Eliminate Async Waterfalls

A waterfall is when you await things sequentially that could run in parallel. Each extra round trip adds raw latency. The skill targets three patterns:

Defer awaits past early exits — don’t fetch data you’ll never use:

// ❌ Fetches even when we'll skip
async function getProfile(skip: boolean) {
  const user = await fetchUser();
  if (skip) return null;
  return user;
}

// ✅ Await only when needed
async function getProfile(skip: boolean) {
  if (skip) return null;
  return await fetchUser();
}

Parallelise with better-all for complex dependency graphs:

// ❌ Sequential — slow
const user   = await getUser(id);
const posts  = await getPosts(user.id);
const config = await getConfig();

// ✅ Parallel with auto dependency resolution
import all from 'better-all';
const result = await all({
  user:   () => getUser(id),
  posts:  ({ user }) => getPosts(user.id), // waits only for user
  config: () => getConfig(),               // runs immediately
});

“Start early, await late” in API routes:

// ✅ Both requests fly simultaneously
export async function GET() {
  const sessionPromise = getSession();
  const configPromise  = getConfig();

const [session, config] = await Promise.all([sessionPromise, configPromise]);
  return Response.json({ session, config });
}

“Every sequential await in your API routes is a full network round-trip your users are silently paying for.” — React Best Practices Skill, Rule 1

Priority 2 — Crush Bundle Size

The skill’s most impactful rule targets barrel file imports. Importing a single icon from lucide-react via a barrel file forces the runtime to load 1,500+ modules, adding nearly 3 seconds to your dev boot time.

Import Style Modules Loaded Cold Start Impact import { Button } from '@mui/material' 1,000+ modules 200 – 800ms import Button from '@mui/material/Button' 1 module < 10ms Next.js optimizePackageImports Auto-transformed 15–70% improvement

Enable automatic optimization in next.config.ts:

const nextConfig = {
  experimental: {
    optimizePackageImports: ['lucide-react', '@mui/material', '@chakra-ui/react'],
  },
};

export default nextConfig;

Use next/dynamic for heavy components to defer loading until needed:

import dynamic from 'next/dynamic';
// Only loads the chart library when the component mounts
const Chart = dynamic(() => import('./HeavyChart'), {
  loading: () => <Skeleton />,
  ssr: false,
});

Priority 3 — Server Component Performance

With React Server Components, the server-to-client boundary is a performance vector. The skill enforces three patterns:

Deduplicate fetches with React.cache() — multiple RSCs needing the same user object? Only hit the DB once:

import { cache } from 'react';
export const getCurrentUser = cache(async () => {
  return db.user.findFirst({ where: { active: true } });
});
// Calling this in 10 different Server Components
// still results in exactly 1 database query per request.

Project data at RSC boundaries — only send to the client what it actually needs:

// ❌ Sends entire DB row (passwords, internal fields, etc.)
return <UserCard user={dbUser} />
// ✅ Only the fields the component needs
return <UserCard user={{
  name: dbUser.name,
  avatar: dbUser.avatarUrl,
}} />

Use after() for non-blocking side effects — don't make users wait for your analytics:

import { after } from 'next/server';
export async function POST(req: Request) {
  const data = await req.json();
  await db.saveOrder(data);
  // Runs AFTER the response is sent - zero user-facing latency
  after(async () => {
    await analytics.trackPurchase(data);
    await cache.revalidate('/orders');
  });
  return Response.json({ ok: true });
}

Priority 4 — Re-render Performance

Lazy state initialization — parsing localStorage on every render is wasteful:

// ❌ Runs JSON.parse on EVERY re-render
const [state, setState] = useState(JSON.parse(localStorage.getItem('data')));
// ✅ Runs only once on mount
const [state, setState] = useState(() => JSON.parse(localStorage.getItem('data')));

CSS content-visibility for long lists — skip rendering what's offscreen:

/* Apply to list items not in the initial viewport */
.list-item {
  content-visibility: auto;
  contain-intrinsic-size: auto 200px; /* estimate the item height */
}

Keep UI snappy with useTransition:

const [isPending, startTransition] = useTransition();
function handleSearch(query: string) {
  // Urgent: update the input immediately
  setInput(query);
  // Non-urgent: let React defer the expensive filter
  startTransition(() => setFilteredResults(filterData(query)));
}

Passive vs. Active Context: What the Evals Found

Vercel ran an evaluation comparing three configurations on Next.js 16 API tasks:

Configuration Pass Rate vs. Baseline No docs (baseline) 53% — Agent Skill (default) 53% +0pp Agent Skill + explicit instructions 79% +26pp AGENTS.md docs index 100% +47pp

The lesson: for rules that apply to every task, embed them in AGENTS.md so they're always in the system prompt. Reserve skills for occasional, action-oriented workflows like performance audits or version migrations.

Recommended Workflow:

• **AGENTS.md** → project-wide coding style, security guardrails, framework version constraints
• Agent Skills → “Upgrade Next.js”, “Audit performance”, “Migrate design system”

Quick Start — Add Skills to Your Next.js Project

# 1. Install the react-best-practices skill
npx skills add vercel-labs/react-best-practices
# 2. Add a web design auditor
npx skills add vercel-labs/web-design-guidelines
# 3. Add the deploy skill for zero-to-production workflows
npx skills add vercel-labs/vercel-deploy-claimable
# 4. Verify everything is linked correctly
npx skills list

Then in your coding agent, trigger with natural language: “Review my React performance” or “Audit my accessibility.”

The Bottom Line

Agent Skills aren’t magic — they’re versioned expertise. The real value of react-best-practices isn't any single rule; it's the prioritization. Waterfalls first, then bundle size, then serialization overhead, then re-render cost. That order maps directly to real-world impact on Core Web Vitals.

Set up your AGENTS.md for always-on architectural constraints. Use skills for the surgical, multi-step workflows. And start with async waterfalls — that's where your users are waiting right now.

Based on vercel-labs/agent-skills · February 2026