Vercel Packages a Decade of React Best Practices into an Open‑Source AI Skill

Vercel recently released an open‑source project called react-best-practices, explicitly positioned not just as documentation but as an AI Agent "Skill" that can be consumed by tools like Cursor or Claude.

In a blog post, Vercel’s chief software engineer Andrew Qu notes that most performance‑optimisation attempts fail because they target the wrong direction. He points out that a 600 ms waterfall network request or an extra 300 KB of unused JavaScript cannot be fixed merely by adding useMemo or micro‑optimising loops.

The Skill organizes the rules into eight categories and ranks them by impact, from CRITICAL to LOW:

Eliminate waterfall flow (CRITICAL)

Reduce bundle size (CRITICAL)

Server‑side performance (HIGH)

Client data fetching (MEDIUM‑HIGH)

Re‑render optimisation (MEDIUM)

Render performance (MEDIUM)

JavaScript performance (LOW‑MEDIUM)

Advanced patterns (LOW)

The list reveals that the often‑discussed "re‑render optimisation" is only the fifth priority.

The Skill is delivered as a specially‑formatted Agent Skill file. Once installed, an AI assistant will automatically consult these rules when reviewing or generating code.

Typical mistake – async waterfall:

async function handleRequest(userId: string, skipProcessing: boolean) {
  // Awaited before knowing if the data is needed
  const userData = await fetchUserData(userId);

  if (skipProcessing) {
    // The earlier await was wasted
    return { skipped: true };
  }

  return processUserData(userData);
}

Corrected version following the Skill:

async function handleRequest(userId: string, skipProcessing: boolean) {
  // Decide early
  if (skipProcessing) {
    return { skipped: true };
  }

  const userData = await fetchUserData(userId);
  return processUserData(userData);
}

Additional hard‑core recommendations include:

Bundle size: avoid barrel files ( index.ts) to improve tree‑shaking; prefer direct imports or next/dynamic / React.lazy for large components.

Server performance: in Next.js Server Components, use React.cache() to deduplicate request‑level data and prevent repeated database queries.

Re‑render: don’t use hooks merely for their own sake; if a state is only needed inside a callback, keep it out of useEffect and use a ref or immediate read instead.

The Skill can be installed with npx add-skill vercel-labs/agent-skills in a supported Agent environment, and the source lives at

https://github.com/vercel-labs/agent-skills/blob/main/skills/react-best-practices/SKILL.md

.