QUICK INFO
| Difficulty | Beginner |
| Time Required | 5-10 minutes |
| Prerequisites | Node.js installed, at least one AI coding agent (Cursor, Claude Code, Codex, or OpenCode) |
| Tools Needed | Terminal, npx (comes with Node.js) |
What You'll Learn:
- Install Vercel's react-best-practices skill to your coding agent
- Understand what the 40+ rules cover and how they're prioritized
- Trigger the skill during code review and refactoring sessions
This guide covers installing Vercel's react-best-practices repository as an "Agent Skill" for AI coding tools. The skill contains 40+ performance rules that your agent references when reviewing components, suggesting refactors, or generating new code. If you're using Cursor, Claude Code, Codex, or OpenCode, this is a single terminal command.
What's Actually in the Repository
Vercel released this in mid-January 2026. The rules compile into a single AGENTS.md file that AI agents can query. Not a style guide for humans to memorize. It's structured for machine parsing.
The repository organizes rules into eight categories, ordered by impact:
Critical priority: Eliminating async waterfalls and reducing bundle size. Vercel's position is that these two categories address the root causes behind most real-world performance problems. Their blog post makes the point bluntly: if a request waterfall adds 600ms of wait time, your useMemo optimizations are irrelevant.
High to medium priority: Server-side performance, client-side data fetching, re-render optimization, and rendering performance.
Lower priority: Advanced patterns and JavaScript micro-optimizations.
Each rule includes impact ratings (CRITICAL down to LOW), code examples showing what breaks, and the fix. The examples compare incorrect implementations against correct ones. When your agent reviews your code or suggests optimizations, it can reference these patterns directly.
Installation
Run this from any directory:
npx add-skill vercel-labs/agent-skills
The CLI detects which coding agents you have installed by checking their configuration directories. If you have Cursor, Claude Code, Codex, or OpenCode, it finds them automatically.
You'll see an interactive prompt asking which skills to install (react-best-practices is one of several in the repository) and where to install them. For most setups, accept the defaults.
Verifying Installation
After installation, skills live in agent-specific directories:
- Claude Code:
~/.claude/skills/ - Cursor:
.cursor/skills/in your project or~/.cursor/skills/globally - Codex/OpenCode: Similar patterns in their respective config folders
Check that a react-best-practices folder exists with a SKILL.md file inside.
Installation Options
The CLI accepts flags for non-interactive use:
# Install only react-best-practices, globally, to Claude Code
npx add-skill vercel-labs/agent-skills --skill react-best-practices -g -a claude-code -y
# List available skills without installing
npx add-skill vercel-labs/agent-skills --list
# Install to multiple agents
npx add-skill vercel-labs/agent-skills -a claude-code -a cursor
The -g flag installs globally (available across all projects). Without it, skills install to your current working directory, which you'd commit to share with your team.
Using the Skill
You don't invoke the skill explicitly. Once installed, your agent loads it when relevant tasks come up.
Trigger phrases that typically activate it: "Review this React component for performance issues," "Help me optimize this Next.js page," "Check this code for waterfalls."
The agent then has access to the full ruleset. If it spots cascading useEffect calls, sequential awaits that could parallelize, or heavy client-side imports, it can cite specific rules and suggest fixes.
What the Agent Sees
The skill definition includes trigger conditions. From the SKILL.md:
Use when: Writing new React components or Next.js pages, implementing data fetching (client or server-side), reviewing code for performance issues, optimizing bundle size or load times.
The agent decides whether to load the full AGENTS.md based on your query. If you're asking about a React component, it pulls in the rules. If you're asking about Python, it doesn't.
Example Rules
A few patterns from the repository, to give you a sense of what's covered:
Avoiding unnecessary awaits: If you have two database calls that don't depend on each other, running them sequentially wastes time. The rule shows the waterfall pattern and the Promise.all fix.
Conditional loading: Large modules that only run in certain branches still get bundled if you import them at the top level. The rule demonstrates dynamic imports gated by feature flags.
Re-render optimization: Using Maps instead of hooks for caches that need to work outside React components (in utilities, event handlers). The rule references Vercel's blog post about making their dashboard faster.
localStorage caching: Synchronous storage reads are expensive. If getTheme() calls localStorage.getItem ten times, that's ten storage reads. The rule shows memoizing the value.
I haven't tested every rule against my own codebases, so I can't vouch for all of them. But the patterns match what I've seen in production React apps.
Troubleshooting
Skill not loading: Restart your agent after installation. Some agents cache skill lists at startup. If it still doesn't work, verify the SKILL.md file exists in the expected location.
Agent doesn't detect the skill: The CLI auto-detects agents by checking for config directories. If your agent uses a non-standard path, you may need to install manually by copying the skill folder.
Network-dependent skills: The react-best-practices skill doesn't require network access. But if you install other skills from the repository (like vercel-deploy), you may need to allowlist domains. For Claude, that's at claude.ai/admin-settings/capabilities.
What's Next
The skill is installed. Ask your agent to review a React component or Next.js page and see what it catches. Vercel also published a web-design-guidelines skill in the same repository if you want UI/UX auditing rules.
PRO TIPS
The --list flag shows all skills in a repository before you install anything. Useful for browsing what's available.
Skills installed to your project directory (without -g) can be committed to version control. Your whole team gets the same rules.
If you maintain your own performance guidelines, you can fork the repository and add rules. The format is documented in the repo's AGENTS.md file.
FAQ
Q: Does this work with GitHub Copilot? A: The add-skill CLI supports Copilot, but skill loading behavior varies by agent. Copilot's support for external skills is less mature than Claude Code or Cursor. Test it yourself.
Q: Can I use this without an AI agent, just as documentation? A: Yes. The AGENTS.md file is readable by humans. It's not optimized for human scanning the way a traditional style guide would be, but the rules and examples are all there.
Q: How often does Vercel update the rules? A: Unknown. The repository is new. I'd expect updates as they encounter new patterns in production, but there's no stated cadence.
Q: What if a rule conflicts with my team's conventions? A: You can fork the repository and remove or modify rules. Or just ignore the agent's suggestion when it doesn't fit.
RESOURCES
- react-best-practices repository: The source rules and skill definition
- Vercel blog post: Background on why they built this
- add-skill CLI: Documentation for installation options
- Agent Skills specification: How to create your own skills
