vercel-labs/agent-skills: Vercel's Official Coding Agent Skill Collection

What agent-skills Is and Who Uses It

AI coding agents need domain knowledge to make good decisions. Without explicit guidance, an agent writing a Next.js page may miss a Server Component opportunity, choose a client-side fetch where a server fetch would avoid a waterfall, or add an image tag without dimensions. agent-skills packages Vercel Engineering's own rules into skill files that an agent loads on demand.

The repository follows the open Agent Skills format documented at agentskills.io. A skill is a SKILL.md file plus optional supporting scripts. The agent host reads the skill when the user invokes it and applies its contents to the current task. The format is host-agnostic: the same skill file works in Claude Code, GitHub Copilot CLI, Cursor, Amp, and any other host that reads from the ~/.agents/skills/ directory.

The primary audience is developers using Vercel-hosted projects who want their AI coding agent to apply Vercel Engineering's own guidelines consistently, rather than depending on the model's general training data.

The Eight Available Skills

The repository ships eight skills at the time of the last push (2026-08-28):

vercel-optimize audits a deployed Vercel project for cost, performance, reliability, caching, function usage, and billing. It collects Vercel metrics first, then investigates only the routes and files those metrics identify as problems.

react-best-practices contains 40 or more rules across eight categories: eliminating waterfalls, bundle size optimization, server-side performance, client-side data fetching, re-render optimization, rendering performance, JavaScript micro-optimizations, and general patterns. Categories are prioritized by impact.

web-design-guidelines audits UI code for 100 or more rules covering accessibility, focus states, forms, animation, typography, images, performance, navigation, dark mode, touch handling, and internationalization.

writing-guidelines audits docs and prose against the Vercel writing handbook, with 80 or more rules covering voice, structure, code samples, typography, and AI workflow disclosure.

react-native-guidelines covers 16 rules across performance, layout, animation, images, state management, architecture, and platform-specific patterns for React Native and Expo.

react-view-transitions covers the React View Transition API: the ViewTransition component, addTransitionType, shared element transitions, and Next.js integration with the transitionTypes prop.

composition-patterns addresses React component design: extracting compound components, lifting state, and avoiding boolean prop proliferation.

vercel-deploy-claimable deploys projects directly from an AI conversation, auto-detects 40 or more frameworks from package.json, and returns both a preview URL and a claim URL for transferring ownership to a Vercel account.

Installing and Using agent-skills

Skills install through the skills.sh registry. The installation command from the README:

npx skills add vercel-labs/agent-skill

This places the skill into the user-level cross-agent skills directory, where supported agent hosts discover it automatically. The package.json in the repository is marked private, meaning the package is not published to npm directly; distribution goes through skills.sh.

The vercel-deploy-claimable skill shows how an agent-driven deploy works. When the agent invokes this skill, it: 1. Packages the project into a tarball 2. Auto-detects the framework from package.json (Next.js, Vite, Astro, and 37 others) 3. Uploads to Vercel's deployment service 4. Returns a preview URL and a claim URL

The claim URL lets the user transfer the deployed project to their own Vercel account. The README notes that static HTML projects are handled automatically without framework detection.

For Claude Code, the skill integrates through the ~/.claude/skills/ path that Claude Code reads. The agentskills.io format ensures the same skill file works across hosts.

How the Rule-Based Skills Work

react-best-practices categorizes rules by impact level: Critical (eliminating waterfalls, bundle size) takes priority over Medium and Low rules. This means an agent using the skill can resolve conflicts between competing advice by applying higher-priority rules first.

The writing-guidelines skill includes explicit AI workflow rules: accountability, enterprise model guidance, plan-first advice, and disclosure of AI use. The README excerpt lists these as a distinct category within the skill.

web-design-guidelines is the broadest skill by rule count, covering accessibility requirements (aria-labels, semantic HTML, keyboard handlers), focus state patterns, form validation approaches, animation with prefers-reduced-motion support, and internationalization with Intl.DateTimeFormat and Intl.NumberFormat. The 100-rule figure is described as approximate in the README.

These skills operate as read-time guidance, not as runtime validators. The agent applies them when writing or reviewing code, not as linters that run at commit time. Teams that want static analysis should combine the skill guidance with actual linters configured in their project.

Limitations: Scope, License, and Vercel Dependency

All eight skills are oriented toward Vercel's platform and Vercel Engineering's conventions. The vercel-optimize skill only applies to Vercel-deployed projects. The react-best-practices rules favor Next.js App Router patterns (Server Components, RSC data fetching) that do not apply to React applications running outside Next.js.

The writing-guidelines skill reflects the Vercel writing handbook specifically. Teams following a different documentation style will find the rules conflict with their conventions.

The repository's package.json sets "private": true, which means this collection is not distributed as an npm package. Installation goes through skills.sh. Teams that cannot use skills.sh in their environment, or that want to pin a specific version, must clone the repository manually and manage updates themselves.

The license field in the repository is unknown. There is no LICENSE file listed in the repository's top-level entries as of the last push. Teams using these skills in a commercial setting should confirm the terms with Vercel before distributing or embedding them.

How agent-skills Compares to Writing Custom Skills

The alternative to using agent-skills is writing your own SKILL.md files from scratch following the agentskills.io specification. A custom skill can cover any framework, any style guide, and any internal convention specific to your team.

The trade-off is the up-front investment. Writing a comprehensive React best-practices skill that covers waterfalls, bundle size, and rendering performance requires synthesizing knowledge across the React documentation, performance profiling tools, and your team's specific patterns. agent-skills does this work for a Vercel and React stack and backs it with Vercel Engineering's own experience.

For teams building outside Vercel, the skills in this repository are a useful reference for how to structure a rule-based skill file: the category system, the impact prioritization, and the use-when headings are patterns worth borrowing even if the specific rules need replacing. The agentskills.io format is the same regardless of content.

Editorial conclusion

agent-skills is a reliable starting point for teams using Vercel's infrastructure who want their AI coding agent to apply consistent React, Next.js, and Vercel-specific rules without writing the rule set from scratch. The eight included skills cover the most common decision points in a Vercel-deployed React project. The limitation is scope: skills are Vercel-opinionated by design, and teams running a different stack will find many rules inapplicable or misdirecting. The license is not specified in the repository, and the package.json marks it as private, so teams using the skills in a commercial or redistributed context should verify the terms directly with Vercel before proceeding. The last push was on 2026-08-28.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. vercel-labs/agent-skills on GitHub