Unlocking Performance: Vercel's React Best Practices Skill for Claude Code

In the fast-paced world of web development, optimizing React and Next.js applications for performance is crucial. Enter Vercel's React Best Practices Skill, a powerful tool designed to elevate your code reviews and refactoring processes. This skill packages over 40 performance-focused rules into a Claude Code-compatible format, enabling AI agents to systematically identify and fix issues related to performance, bundle size, and rendering.

Authored by Vercel Engineering, it shifts the focus from generic styling advice to targeted optimizations that can significantly improve app efficiency. This is the power of Agent Skills in action.

What Is the Vercel React Best Practices Skill?

At its core, this skill is a specialized ruleset tailored for React and Next.js, emphasizing performance over aesthetics. Unlike broad linting tools, it hones in on real-world bottlenecks that affect user experience and scalability.

Organized as a Claude Skill folder named react-best-practices, it includes:

• SKILL.md: Core instructions and comprehensive rule list
• References Directory: In-depth documentation pulled in as needed

The skill uses "progressive context loading," starting with a quick reference, then diving into specific category or rule docs. This approach minimizes token usage and keeps the agent's reasoning sharp and focused. For more on skill structure, see our Claude Skills Concepts Guide.

Installing the Skill with Skilz CLI

The skill lives in Vercel's agent-skills repository, which contains multiple skills. The Skilz CLI clones the entire repository and prompts you to select the desired skill.

Important: Direct subpaths like vercel-labs/agent-skills/react-best-practices won't work. Use the repository root instead:

# Install Skilz CLI first
pip install skilz

# Install from Vercel's agent-skills repository
skilz install -g vercel-labs/agent-skills/

You'll see an interactive prompt:

Found 3 skills in repository:

  [1] vercel-deploy  (skills/claude.ai/vercel-deploy-claimable)
  [2] vercel-react-best-practices  (skills/react-best-practices)
  [3] web-design-guidelines  (skills/web-design-guidelines)
  [A] Install all
  [Q] Cancel

Select skill(s) [1-3, A, Q]: 2

Enter 2 to install the React Best Practices skill.

Agent-Specific Installation

The skill works across all 21+ supported agents. Here are the commands for popular agents:

Claude Code:

# User-level (available in all projects)
skilz install -g vercel-labs/agent-skills/ --agent claude

# Project-level only
skilz install vercel-labs/agent-skills/ --project --agent claude

OpenCode:

# User-level
skilz install -g vercel-labs/agent-skills/ --agent opencode

# Project-level
skilz install vercel-labs/agent-skills/ --project --agent opencode

Gemini CLI (project-level only):

skilz install vercel-labs/agent-skills/ --project --agent gemini

OpenAI Codex:

skilz install -g vercel-labs/agent-skills/ --agent codex

Other Agents (Windsurf, Qwen Code, Aider, etc.):

skilz install -g vercel-labs/agent-skills/ --agent <name>

The https://github.com/ prefix is optional in the latest Skilz CLI version. For complete documentation, see the Skilz CLI docs.

Rule Structure and Categories

The 40+ rules are grouped into eight categories, each assigned an impact level (LOW to CRITICAL) and a short prefix for quick reference:

CRITICAL Impact Rules

Eliminating Waterfalls (async-*)

These rules prevent cascading delays:

• Defer awaits and parallelize with Promise.all
• Avoid sequential API routes
• Use Suspense boundaries for streaming

// Bad: Sequential waterfalls
const user = await getUser();
const posts = await getPosts(user.id);
const comments = await getComments(posts[0].id);

// Good: Parallel fetching
const [user, posts] = await Promise.all([
  getUser(),
  getPosts(userId)
]);

Bundle Size Optimization (bundle-*)

Guidance for smaller bundles:

• Avoid barrel imports
• Use dynamic imports for heavy components
• Defer third-party libraries
• Conditional loading based on user intent

// Bad: Barrel import pulls entire library
import { Button, Icon } from 'ui-library';

// Good: Direct path imports
import Button from 'ui-library/Button';
import Icon from 'ui-library/Icon';

HIGH Impact Rules

Server-Side Performance (server-*)

Server efficiency patterns:

• Cross-request LRU caching
• Minimize RSC boundary serialization
• Parallel data fetching
• Use React.cache() for per-request deduplication

MEDIUM to MEDIUM-HIGH Impact Rules

Client-Side Data Fetching (client-*)

• Best patterns for fetching and caching
• Request deduplication on the client

Re-render Optimization (rerender-*)

• Defer state reads
• Memoize components
• Narrow effect dependencies
• Use derived subscriptions
• Functional setState
• Lazy state initialization
• Transitions for smoother updates

Rendering Performance (rendering-*)

• Animate wrappers instead of raw SVGs
• Apply content-visibility
• Hoist static JSX
• Reduce SVG precision
• Avoid hydration flicker
• Use explicit conditionals

LOW to MEDIUM Impact Rules

JavaScript Performance (js-*)

• Batch DOM/CSS updates
• Use Maps for repeated lookups
• Cache property accesses or function results

Advanced Patterns (advanced-*)

• Incremental optimizations
• Edge cases for sophisticated scenarios

What It Optimizes

The skill targets key web performance metrics:

Practical Usage Examples

As a Code Reviewer

Use the react-best-practices skill to review this PR 
for waterfalls and bundle size issues.

The agent classifies the task and applies relevant CRITICAL and HIGH rules first.

As a Refactor Guide

Use the react-best-practices skill. Here's a slow component.
Focus only on CRITICAL and HIGH impact rules.

This prevents over-optimizing minor areas while addressing real bottlenecks.

In CI/CD Pipelines

Integrate automated performance reviews:

# Run performance review on React/Next.js files
skilz run react-best-practices --files "src/**/*.tsx"

Common Patterns Fixed

Waterfalls:

• Replace serial awaits with Promise.all
• Initiate promises early, await late
• Add Suspense for streaming

Bundle Size:

• Swap barrel imports for direct paths
• Use next/dynamic for heavy components
• Defer analytics and non-essential scripts

Re-renders:

• Isolate expensive subtrees in memoized components
• Refine useEffect dependencies to primitives
• Use transitions for non-urgent updates

Micro-Optimizations:

• Apply content-visibility to large lists
• Animate wrappers around SVGs
• Batch DOM operations
• Prebuild lookup Maps

Why This Matters

Vercel's React Best Practices Skill transforms how developers approach optimization. Instead of relying on general knowledge or manual code reviews, you get:

1. Systematic Coverage: 40+ rules ensure nothing is missed
2. Prioritized Impact: CRITICAL rules first, micro-optimizations later
3. Real Code Examples: Each rule includes incorrect vs. correct snippets
4. Token Efficiency: Progressive loading keeps context lean

Whether you're battling bundle bloat or re-render woes, this skill equips your AI agents to deliver faster, leaner apps. Performance isn't an afterthought; it's a built-in superpower.

Learn More

SkillzWave Resources:

• SkillzWave Documentation
• Agent Configuration Guide
• All Guides
• Supported Platforms
• Claude Skills Part 1
• Claude Skills Part 2
• Claude Skills Concepts

External Resources:

• Vercel Agent Skills Repository
• Skilz CLI
• SpillwaveSolutions GitHub
• Agent Skills Standard
• Spillwave

Related Posts

• Context7: Turning Documentation into Intelligent AI Skills
• Context7 TUI: The Skill Foundry
• Agent Skills Beyond Coding
• Building Your First Claude Code Skill
• Mastering Agent Skills: The Complete Guide
• MCP: The USB-C of AI