agent-skills Documentation

File: README.md Copy Chapter

Agent Skills

A collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities.

Skills follow the Agent Skills format.

Available Skills Copy Chapter

vercel-optimize Copy Section

Audits a Vercel project for cost, performance, reliability, caching, function usage, and billing opportunities. It collects Vercel metrics first, then investigates only the routes and files those metrics point to.

Use when:

• Optimizing a deployed Vercel project
• Reducing Vercel costs or function usage
• Investigating slow or expensive routes
• Finding caching, ISR, middleware, image, or build-minute issues
• Producing a ranked cost and performance report

react-best-practices Copy Section

React and Next.js performance optimization guidelines from Vercel Engineering. Contains 40+ rules across 8 categories, prioritized by impact.

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

Categories covered:

• Eliminating waterfalls (Critical)
• Bundle size optimization (Critical)
• Server-side performance (High)
• Client-side data fetching (Medium-High)
• Re-render optimization (Medium)
• Rendering performance (Medium)
• JavaScript micro-optimizations (Low-Medium)

web-design-guidelines Copy Section

Review UI code for compliance with web interface best practices. Audits your code for 100+ rules covering accessibility, performance, and UX.

Use when:

• "Review my UI"
• "Check accessibility"
• "Audit design"
• "Review UX"
• "Check my site against best practices"

Categories covered:

• Accessibility (aria-labels, semantic HTML, keyboard handlers)
• Focus States (visible focus, focus-visible patterns)
• Forms (autocomplete, validation, error handling)
• Animation (prefers-reduced-motion, compositor-friendly transforms)
• Typography (curly quotes, ellipsis, tabular-nums)
• Images (dimensions, lazy loading, alt text)
• Performance (virtualization, layout thrashing, preconnect)
• Navigation & State (URL reflects state, deep-linking)
• Dark Mode & Theming (color-scheme, theme-color meta)
• Touch & Interaction (touch-action, tap-highlight)
• Locale & i18n (Intl.DateTimeFormat, Intl.NumberFormat)

writing-guidelines Copy Section

Review docs and prose for compliance with the Vercel writing handbook. Audits your pages for 80+ rules covering voice, structure, content types, code samples, typography, and AI workflow.

Use when:

• "Review my docs"
• "Check writing style"
• "Audit prose"
• "Review docs voice and tone"
• "Check this page against the writing handbook"

Categories covered:

• Planning (content plan, content type, user-shaped titles)
• Voice & tone (active voice, direct address, banned words like easy/simple/quick)
• Tone by content type (tutorial, how-to, reference, conceptual, troubleshooting)
• Headings & structure (sentence case, descriptive subheadings, TL;DR opens)
• Lists (when to use, bold/description format)
• Code (language tags, TypeScript first, <Steps/>, 80-col / 25-line limits)
• Placeholders, units, & numbers (snake_case text, count-up numbers, 64 KB/200 ms)
• Typography (no em dashes as punctuation, curly quotes, ellipsis character, non-breaking spaces)
• Source formatting (no hard-wrap, no --- rules, blank line discipline)
• Pricing & money pages (tables, uncompromising detail)
• AI workflow (accountability, enterprise models, plan first, disclose AI use)
• Review (PR description discipline, author accountability)

react-native-guidelines Copy Section

React Native best practices optimized for AI agents. Contains 16 rules across 7 sections covering performance, architecture, and platform-specific patterns.

Use when:

• Building React Native or Expo apps
• Optimizing mobile performance
• Implementing animations or gestures
• Working with native modules or platform APIs

Categories covered:

• Performance (Critical) - FlashList, memoization, heavy computation
• Layout (High) - flex patterns, safe areas, keyboard handling
• Animation (High) - Reanimated, gesture handling
• Images (Medium) - expo-image, caching, lazy loading
• State Management (Medium) - Zustand patterns, React Compiler
• Architecture (Medium) - monorepo structure, imports
• Platform (Medium) - iOS/Android specific patterns

react-view-transitions Copy Section

Implement smooth, native-feeling animations using React's View Transition API. Covers the <ViewTransition> component, addTransitionType, transition types, and Next.js integration including the transitionTypes prop on next/link.

Use when:

• Adding page transitions or route animations
• Animating enter/exit of components
• Creating shared element transitions (list-to-detail morphing)
• Implementing directional (forward/back) navigation animations
• Integrating view transitions in Next.js App Router
• Animating list reorder or Suspense fallback reveals

Topics covered:

• <ViewTransition> component (enter, exit, update, share triggers)
• addTransitionType for directional/context-specific animations
• View Transition Classes and CSS pseudo-elements
• Shared element transitions with the name prop
• JavaScript animations via Web Animations API
• Next.js transitionTypes prop on next/link
• Ready-to-use CSS animation recipes (fade, slide, scale, flip)
• Accessibility (prefers-reduced-motion)

composition-patterns Copy Section

React composition patterns that scale. Helps avoid boolean prop proliferation through compound components, state lifting, and internal composition.

Use when:

• Refactoring components with many boolean props
• Building reusable component libraries
• Designing flexible APIs
• Reviewing component architecture

Patterns covered:

• Extracting compound components
• Lifting state to reduce props
• Composing internals for flexibility
• Avoiding prop drilling

vercel-deploy-claimable Copy Section

Deploy applications and websites to Vercel instantly. Designed for use with claude.ai and Claude Desktop to enable deployments directly from conversations. Deployments are "claimable" - users can transfer ownership to their own Vercel account.

Use when:

• "Deploy my app"
• "Deploy this to production"
• "Push this live"
• "Deploy and give me the link"

Features:

• Auto-detects 40+ frameworks from package.json
• Returns preview URL (live site) and claim URL (transfer ownership)
• Handles static HTML projects automatically
• Excludes node_modules and .git from uploads

How it works:

1. Packages your project into a tarball
2. Detects framework (Next.js, Vite, Astro, etc.)
3. Uploads to deployment service
4. Returns preview URL and claim URL

Output:

Deployment successful!

Preview URL: https://skill-deploy-abc123.vercel.app
Claim URL:   https://vercel.com/claim-deployment?code=...

Installation Copy Chapter

npx skills add vercel-labs/agent-skills

Usage Copy Chapter

Skills are automatically available once installed. The agent will use them when relevant tasks are detected.

Examples:

Deploy my app

Review this React component for performance issues

Help me optimize this Next.js page

Skill Structure Copy Chapter

Each skill contains:

• SKILL.md - Instructions for the agent
• scripts/ - Helper scripts for automation (optional)
• references/ - Supporting documentation (optional)

License Copy Chapter

MIT

File: skills/react-native-skills/README.md Copy Chapter

React Native Guidelines

A structured repository for creating and maintaining React Native Best Practices
optimized for agents and LLMs.

Structure Copy Chapter

• rules/ - Individual rule files (one per rule)
  • _sections.md - Section metadata (titles, impacts, descriptions)
  • _template.md - Template for creating new rules
  • area-description.md - Individual rule files
• metadata.json - Document metadata (version, organization, abstract)
• AGENTS.md - Compiled output (generated)

Rules Copy Chapter

Core Rendering (CRITICAL) Copy Section

• rendering-text-in-text-component.md - Wrap strings in Text components
• rendering-no-falsy-and.md - Avoid falsy && operator in JSX

List Performance (HIGH) Copy Section

• list-performance-virtualize.md - Use virtualized lists (LegendList,
  FlashList)
• list-performance-function-references.md - Keep stable object references
• list-performance-callbacks.md - Hoist callbacks to list root
• list-performance-inline-objects.md - Avoid inline objects in renderItem
• list-performance-item-memo.md - Pass primitives for memoization
• list-performance-item-expensive.md - Keep list items lightweight
• list-performance-images.md - Use compressed images in lists
• list-performance-item-types.md - Use item types for heterogeneous lists

Animation (HIGH) Copy Section

• animation-gpu-properties.md - Animate transform/opacity instead of layout
• animation-gesture-detector-press.md - Use GestureDetector for press
  animations
• animation-derived-value.md - Prefer useDerivedValue over useAnimatedReaction

Scroll Performance (HIGH) Copy Section

• scroll-position-no-state.md - Never track scroll in useState

Navigation (HIGH) Copy Section

• navigation-native-navigators.md - Use native stack and native tabs

React State (MEDIUM) Copy Section

• react-state-dispatcher.md - Use functional setState updates
• react-state-fallback.md - State should represent user intent only
• react-state-minimize.md - Minimize state variables, derive values

State Architecture (MEDIUM) Copy Section

• state-ground-truth.md - State must represent ground truth

React Compiler (MEDIUM) Copy Section

• react-compiler-destructure-functions.md - Destructure functions early
• react-compiler-reanimated-shared-values.md - Use .get()/.set() for shared
  values

User Interface (MEDIUM) Copy Section

• ui-expo-image.md - Use expo-image for optimized images
• ui-image-gallery.md - Use Galeria for lightbox/galleries
• ui-menus.md - Native dropdown and context menus with Zeego
• ui-native-modals.md - Use native Modal with formSheet
• ui-pressable.md - Use Pressable instead of TouchableOpacity
• ui-measure-views.md - Measuring view dimensions
• ui-safe-area-scroll.md - Use contentInsetAdjustmentBehavior
• ui-scrollview-content-inset.md - Use contentInset for dynamic spacing
• ui-styling.md - Modern styling patterns (gap, boxShadow, gradients)

Design System (MEDIUM) Copy Section

• design-system-compound-components.md - Use compound components

Monorepo (LOW) Copy Section

• monorepo-native-deps-in-app.md - Install native deps in app directory
• monorepo-single-dependency-versions.md - Single dependency versions

Third-Party Dependencies (LOW) Copy Section

• imports-design-system-folder.md - Import from design system folder

JavaScript (LOW) Copy Section

• js-hoist-intl.md - Hoist Intl formatter creation

Fonts (LOW) Copy Section

• fonts-config-plugin.md - Load fonts natively at build time

Creating a New Rule Copy Chapter

1. Copy rules/_template.md to rules/area-description.md
2. Choose the appropriate area prefix:
   • rendering- for Core Rendering
   • list-performance- for List Performance
   • animation- for Animation
   • scroll- for Scroll Performance
   • navigation- for Navigation
   • react-state- for React State
   • state- for State Architecture
   • react-compiler- for React Compiler
   • ui- for User Interface
   • design-system- for Design System
   • monorepo- for Monorepo
   • imports- for Third-Party Dependencies
   • js- for JavaScript
   • fonts- for Fonts
3. Fill in the frontmatter and content
4. Ensure you have clear examples with explanations

Rule File Structure Copy Chapter

Each rule file should follow this structure:

---
title: Rule Title Here
impact: MEDIUM
impactDescription: Optional description
tags: tag1, tag2, tag3
---

## Rule Title Here

Brief explanation of the rule and why it matters.

**Incorrect (description of what's wrong):**

```tsx
// Bad code example
```

Correct (description of what's right):

// Good code example

Reference: Link

## File Naming Convention

- Files starting with `_` are special (excluded from build)
- Rule files: `area-description.md` (e.g., `animation-gpu-properties.md`)
- Section is automatically inferred from filename prefix
- Rules are sorted alphabetically by title within each section

## Impact Levels

- `CRITICAL` - Highest priority, causes crashes or broken UI
- `HIGH` - Significant performance improvements
- `MEDIUM` - Moderate performance improvements
- `LOW` - Incremental improvements

File: skills/react-best-practices/README.md Copy Chapter

React Best Practices

A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.

Structure Copy Chapter

• rules/ - Individual rule files (one per rule)
  • _sections.md - Section metadata (titles, impacts, descriptions)
  • _template.md - Template for creating new rules
  • area-description.md - Individual rule files
• src/ - Build scripts and utilities
• metadata.json - Document metadata (version, organization, abstract)
• AGENTS.md - Compiled output (generated)
• test-cases.json - Test cases for LLM evaluation (generated)

Getting Started Copy Chapter

1. Install dependencies:

   bash Copy

   pnpm install

2. Build AGENTS.md from rules:

   bash Copy

   pnpm build

3. Validate rule files:

   bash Copy

   pnpm validate

4. Extract test cases:

   bash Copy

   pnpm extract-tests

Creating a New Rule Copy Chapter

1. Copy rules/_template.md to rules/area-description.md
2. Choose the appropriate area prefix:
   • async- for Eliminating Waterfalls (Section 1)
   • bundle- for Bundle Size Optimization (Section 2)
   • server- for Server-Side Performance (Section 3)
   • client- for Client-Side Data Fetching (Section 4)
   • rerender- for Re-render Optimization (Section 5)
   • rendering- for Rendering Performance (Section 6)
   • js- for JavaScript Performance (Section 7)
   • advanced- for Advanced Patterns (Section 8)
3. Fill in the frontmatter and content
4. Ensure you have clear examples with explanations
5. Run pnpm build to regenerate AGENTS.md and test-cases.json

Rule File Structure Copy Chapter

Each rule file should follow this structure:

---
title: Rule Title Here
impact: MEDIUM
impactDescription: Optional description
tags: tag1, tag2, tag3
---

## Rule Title Here

Brief explanation of the rule and why it matters.

**Incorrect (description of what's wrong):**

```typescript
// Bad code example

Correct (description of what's right):

// Good code example

Optional explanatory text after examples.

Reference: Link

File Naming Convention Copy Chapter

• Files starting with _ are special (excluded from build)
• Rule files: area-description.md (e.g., async-parallel.md)
• Section is automatically inferred from filename prefix
• Rules are sorted alphabetically by title within each section
• IDs (e.g., 1.1, 1.2) are auto-generated during build

Impact Levels Copy Chapter

• CRITICAL - Highest priority, major performance gains
• HIGH - Significant performance improvements
• MEDIUM-HIGH - Moderate-high gains
• MEDIUM - Moderate performance improvements
• LOW-MEDIUM - Low-medium gains
• LOW - Incremental improvements

Scripts Copy Chapter

• pnpm build - Compile rules into AGENTS.md
• pnpm validate - Validate all rule files
• pnpm extract-tests - Extract test cases for LLM evaluation
• pnpm dev - Build and validate

Contributing Copy Chapter

When adding or modifying rules:

1. Use the correct filename prefix for your section
2. Follow the _template.md structure
3. Include clear bad/good examples with explanations
4. Add appropriate tags
5. Run pnpm build to regenerate AGENTS.md and test-cases.json
6. Rules are automatically sorted by title - no need to manage numbers!

Acknowledgments Copy Chapter

Originally created by @shuding at Vercel.

File: skills/composition-patterns/README.md Copy Chapter

React Composition Patterns

A structured repository for React composition patterns that scale. These
patterns help avoid boolean prop proliferation by using compound components,
lifting state, and composing internals.

Structure Copy Chapter

• rules/ - Individual rule files (one per rule)
  • _sections.md - Section metadata (titles, impacts, descriptions)
  • _template.md - Template for creating new rules
  • area-description.md - Individual rule files
• metadata.json - Document metadata (version, organization, abstract)
• AGENTS.md - Compiled output (generated)

Rules Copy Chapter

Component Architecture (CRITICAL) Copy Section

• architecture-avoid-boolean-props.md - Don't add boolean props to customize
  behavior
• architecture-compound-components.md - Structure as compound components with
  shared context

State Management (HIGH) Copy Section

• state-lift-state.md - Lift state into provider components
• state-context-interface.md - Define clear context interfaces
  (state/actions/meta)
• state-decouple-implementation.md - Decouple state management from UI

Implementation Patterns (MEDIUM) Copy Section

• patterns-children-over-render-props.md - Prefer children over renderX props
• patterns-explicit-variants.md - Create explicit component variants

Core Principles Copy Chapter

1. Composition over configuration — Instead of adding props, let consumers
   compose
2. Lift your state — State in providers, not trapped in components
3. Compose your internals — Subcomponents access context, not props
4. Explicit variants — Create ThreadComposer, EditComposer, not Composer
   with isThread

Creating a New Rule Copy Chapter

1. Copy rules/_template.md to rules/area-description.md
2. Choose the appropriate area prefix:
   • architecture- for Component Architecture
   • state- for State Management
   • patterns- for Implementation Patterns
3. Fill in the frontmatter and content
4. Ensure you have clear examples with explanations

Impact Levels Copy Chapter

• CRITICAL - Foundational patterns, prevents unmaintainable code
• HIGH - Significant maintainability improvements
• MEDIUM - Good practices for cleaner code