---
name: vercel-agents
description: Create AI agent instructions (AGENTS.md) using Vercel's research-backed methodology. Proven to achieve 100% pass rate vs 53% baseline in evals. Use when creating agents.md, agent instructions, AI agent context, coding agent documentation, project documentation for AI, or optimizing how AI agents interact with a codebase. Triggers on agents.md, vercel agent, agent instructions, agent context, AI documentation, codebase documentation for agents.
---

# Vercel Agent — Research-Backed AGENTS.md Creator

## Purpose

Create high-performance `AGENTS.md` files using Vercel's empirically-validated methodology. Their research proved that passive context via `AGENTS.md` achieves **100% pass rate** vs 53% baseline — outperforming skills (79%) and even explicit skill instructions. This skill applies those findings to any project.

## When to Use This Skill

- User asks to create or improve `AGENTS.md`
- User wants to optimize how AI agents work with their codebase
- User mentions "agent instructions", "agent context", "coding agent docs"
- User wants to document a project for AI consumption
- User invokes `/vercel-agent`
- New project setup where AI agents will be primary developers

---

## Quick Start

```bash
# 1. Analyze the project
# 2. Generate compressed docs index
# 3. Write AGENTS.md with retrieval-led context
# 4. Test with eval scenarios
```

---

## The Research (Why This Works)

### Vercel's Eval Results

| Approach | Pass Rate | Delta |
|----------|-----------|-------|
| Baseline (no docs) | 53% | — |
| Skill (default) | 53% | +0pp |
| Skill (explicit instructions) | 79% | +26pp |
| **AGENTS.md (compressed index)** | **100%** | **+47pp** |

### Three Reasons Passive Context Wins

1. **No decision point** — Agent doesn't need to decide whether to look up docs
2. **Consistent availability** — Present every turn, not loaded asynchronously
3. **No ordering issues** — Eliminates "read docs first vs explore first" sequencing bugs

### The Critical Insight

> "Prefer retrieval-led reasoning over pre-training-led reasoning"

Agents default to training data (often outdated). AGENTS.md redirects them to project-specific truth. This is THE core principle.

---

## Workflow

### Step 1: Audit the Project

Before writing anything, understand what the agent needs to know:

```
1. Stack & versions (exact semver matters — training data may know v15, project uses v16)
2. Architecture decisions (monorepo? API routes? serverless?)
3. File conventions (where do components go? naming patterns?)
4. APIs that differ from training data (new/changed/deprecated)
5. Build/test/deploy commands
6. Environment & secrets structure
7. Common pitfalls specific to this project
```

**Key question:** What would an agent get WRONG using only its training data?

### Step 2: Structure the AGENTS.md

Follow this exact hierarchy — order matters for context window efficiency:

```markdown
# AGENTS.md

## Project Overview
[1-3 sentences. Stack, purpose, key constraint.]

## Critical Rules
[Things the agent MUST NOT get wrong. Version-specific APIs. Breaking patterns.]

## Architecture
[File structure, data flow, key abstractions.]

## Commands
[Build, test, lint, deploy — exact commands, not descriptions.]

## Conventions
[Naming, file placement, import patterns, style rules.]

## Docs Index
[Compressed pointer to retrievable documentation.]
```

### Step 3: Compress Aggressively

Vercel reduced 40KB → 8KB (80% reduction) with **zero accuracy loss**.

**Compression techniques:**
- Use pipe-delimited indexes pointing to files, not inline content
- Remove prose — use structured key:value pairs
- Abbreviate obvious patterns
- Group related items on single lines
- Omit anything the model's training data already knows correctly

**Format:**
```markdown
[Docs Index]|root: ./docs
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
|api/routes:{auth.md,users.md,products.md}
|components:{Button.md,Form.md,Layout.md}
|config:{env.md,deploy.md}
```

### Step 4: Write Version-Specific Corrections

This is the highest-value section. Identify APIs where training data diverges from project reality:

```markdown
## Version-Specific (v16.1 — NOT in training data)

### CORRECT patterns:
- `'use cache'` directive (NOT `export const revalidate`)
- `connection()` for dynamic rendering (NOT `cookies()` hack)
- `forbidden()` returns 403 (NEW in v16)
- `cookies()` is NOW async (was sync in v14)

### WRONG patterns (model may suggest these):
- ❌ `getServerSideProps` — removed in App Router
- ❌ `revalidate: 60` export — use `cacheLife()` instead
- ❌ Sync `cookies()` — must await in v16
```

### Step 5: Add Retrieval Pointers

Instead of embedding full documentation, point to retrievable files:

```markdown
## Documentation

When you need framework docs, read from `.docs/` directory:
|routing: .docs/routing/{pages,layouts,loading,error}.md
|data: .docs/data/{fetching,caching,revalidation}.md
|api: .docs/api/{route-handlers,middleware,auth}.md

IMPORTANT: Read the relevant .docs/ file BEFORE writing code.
Do NOT rely on training data for API signatures.
```

### Step 6: Validate with Eval Scenarios

Test your AGENTS.md against scenarios targeting training-data gaps:

```markdown
## Self-Test Scenarios

An agent reading this AGENTS.md should correctly handle:
1. [ ] Create a cached page using `'use cache'` (not revalidate export)
2. [ ] Add authentication middleware using project's auth pattern
3. [ ] Run tests with the correct command (`npm test`, not `jest`)
4. [ ] Place new components in the correct directory
5. [ ] Use the project's API client, not raw fetch
```

---

## Anti-Patterns (From Vercel's Research)

### 1. Don't Rely on Agents Invoking Tools

> "In 56% of eval cases, the skill was never invoked despite availability."

**Fix:** Embed critical context directly. Don't make the agent choose to look things up.

### 2. Don't Over-Specify Ordering

Subtle wording differences cause dramatically different outcomes:
- ❌ "You MUST read docs first" → Agent reads docs, anchors on patterns, misses project context
- ✅ "Explore project first, then reference docs for API specifics" → Better mental model

**Fix:** Let the agent explore naturally. AGENTS.md provides ambient context.

### 3. Don't Embed Full Documentation

40KB of docs = wasted context window. Agents don't need full API references inline.

**Fix:** Compressed index (8KB) pointing to retrievable files. Same 100% pass rate.

### 4. Don't Assume Training Data is Current

The whole point of AGENTS.md is correcting training-data assumptions.

**Fix:** Explicitly list what's changed. "X is NOW Y" format.

### 5. Don't Write Prose

Agents process structured data better than paragraphs.

**Fix:** Use tables, key:value pairs, bullet lists, pipe-delimited indexes.

---

## Templates

### Template: Full-Stack Next.js Project

See [templates/nextjs.md](templates/nextjs.md) for a complete AGENTS.md template for Next.js projects.

### Template: Generic Project

See [templates/generic.md](templates/generic.md) for a framework-agnostic template.

---

## Compression Reference

### Before (verbose):
```markdown
## Routing

The application uses file-based routing with the App Router.
Pages are defined in the `app/` directory. Each folder represents
a route segment. The `page.tsx` file in each folder defines the
UI for that route. Layout files (`layout.tsx`) wrap child routes.
Loading states are handled by `loading.tsx` files.
```

### After (compressed):
```markdown
## Routing
|app-router, file-based
|app/[segment]/page.tsx = route UI
|app/[segment]/layout.tsx = wrapper
|app/[segment]/loading.tsx = loading state
```

**Result:** 80% smaller, same information density, agent performs identically.

---

## Navigation Guide

| Need to... | Read this |
|------------|-----------|
| Full Next.js AGENTS.md template | [templates/nextjs.md](templates/nextjs.md) |
| Generic project template | [templates/generic.md](templates/generic.md) |
| Compression techniques | [compression.md](compression.md) |
| Eval scenario design | [evals.md](evals.md) |

---

**Skill Status**: COMPLETE
**Core Principle**: Passive context > Active retrieval. Compress aggressively. Correct training data explicitly.

# Compression Reference

Vercel reduced 40KB → 8KB (80% reduction) with zero accuracy loss. These techniques achieve that.

## Core Principle

Agents process structured data better than prose. Every byte in AGENTS.md competes for context window space. Compress ruthlessly — if it doesn't change agent behavior, remove it.

## Technique 1: Pipe-Delimited Indexes

Replace inline documentation with pointers to retrievable files.

### Before (680 bytes):
```markdown
## Routing Documentation

The application uses the App Router for file-based routing. Pages are defined
in the `app/` directory where each folder represents a URL segment. The
`page.tsx` file renders the route, `layout.tsx` wraps child routes, and
`loading.tsx` provides loading states. Error boundaries use `error.tsx`.
For more details, see the routing documentation in our docs folder.
```

### After (180 bytes):
```markdown
## Routing
|app-router, file-based
|app/[segment]/page.tsx = route UI
|app/[segment]/layout.tsx = wrapper
|app/[segment]/loading.tsx = loading state
|docs: .docs/routing/{pages,layouts,loading,error}.md
```

**Result:** 74% smaller, same information, adds retrievable doc pointer.

## Technique 2: Key:Value Pairs Over Sentences

### Before:
```markdown
Components should be named using PascalCase and placed in the components
directory. Each component should use named exports rather than default
exports. Styling should use Tailwind utility classes.
```

### After:
```markdown
|components: PascalCase files, named exports, components/ dir
|styling: Tailwind utility classes, no CSS modules
```

## Technique 3: Table Format for Related Data

### Before:
```markdown
To build the project, run `npm run build`. For development, use `npm run dev`
but note that the user typically runs this themselves. Run tests with
`npm test`. Linting is done via `npm run lint`.
```

### After:
```markdown
|build: `npm run build`
|dev: `npm run dev` (DO NOT run — user runs this)
|test: `npm test`
|lint: `npm run lint`
```

## Technique 4: Omit Training-Data Defaults

Don't document things the model already knows correctly. Only document:
- Things that DIFFER from training data
- Project-SPECIFIC conventions
- Version-SPECIFIC API changes

### Remove:
- Generic language features (how async/await works)
- Framework basics the model knows (React component lifecycle)
- Standard library usage (Array.map, Object.keys)

### Keep:
- Your project's specific patterns
- Version-specific API differences
- Non-obvious architectural decisions

## Technique 5: Compressed Docs Index

### Before (listing all docs):
```markdown
## Documentation

- Authentication: See docs/auth/overview.md for auth patterns, docs/auth/jwt.md
  for JWT handling, docs/auth/middleware.md for route protection
- Database: See docs/db/schema.md for schema, docs/db/migrations.md for
  migration patterns, docs/db/queries.md for query helpers
```

### After (compressed index):
```markdown
## Docs Index
|root: ./docs
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
|auth:{overview,jwt,middleware}.md
|db:{schema,migrations,queries}.md
```

## Technique 6: Group Related Items on Single Lines

### Before:
```markdown
- Use `@/` as the import alias for the project root
- Use `@/components` for component imports
- Use `@/lib` for utility imports
- Use `@/types` for type imports
```

### After:
```markdown
|imports: `@/` alias — components/, lib/, types/
```

## Size Targets

| Project Size | AGENTS.md Target | Notes |
|-------------|-----------------|-------|
| Small (< 10 files) | 2-4 KB | May not need Docs Index |
| Medium (10-100 files) | 4-8 KB | Include Docs Index |
| Large (100+ files) | 6-10 KB | Aggressive compression needed |
| Monorepo | 8-12 KB | Per-package AGENTS.md may be better |

## Validation

After compressing, verify:
1. No information was lost — every fact is still present or retrievable
2. An agent can still pass all Self-Test scenarios
3. Version corrections are still explicit and unambiguous
4. File size is under 10KB

# Eval Scenario Design

Design eval scenarios that test whether your AGENTS.md successfully corrects training-data gaps and communicates project conventions.

## Eval Design Principle

Every eval should target a **known divergence** between training data and project reality. If the model would get it right without AGENTS.md, the eval has no value.

## Scenario Categories

### Category 1: Version-Specific API Changes

Test whether the agent uses the CORRECT (current) API, not the training-data version.

```markdown
## Eval: Use correct caching API
Task: "Add caching to the /products page with 60-second revalidation"
Expected: Uses `'use cache'` + `cacheLife('seconds', 60)` (v16 pattern)
Failure: Uses `export const revalidate = 60` (v14 pattern)
```

```markdown
## Eval: Async cookies
Task: "Read the auth token from cookies in a server component"
Expected: `const cookieStore = await cookies(); cookieStore.get('token')`
Failure: `const cookieStore = cookies(); cookieStore.get('token')` (sync — v14)
```

### Category 2: Project Architecture Compliance

Test whether the agent follows project-specific patterns.

```markdown
## Eval: Service layer usage
Task: "Fetch the user's profile data and display it"
Expected: Uses `lib/services.ts` client functions
Failure: Uses raw `fetch()` directly in the component
```

```markdown
## Eval: File placement
Task: "Create a new DatePicker component"
Expected: Creates in `components/ui/date-picker.tsx` (project convention)
Failure: Creates in `app/components/DatePicker.tsx` or `src/components/`
```

### Category 3: Command Knowledge

Test whether the agent uses the correct project commands.

```markdown
## Eval: Correct test command
Task: "Run the tests for the auth module"
Expected: Uses `npm test -- --filter auth` (project's actual command)
Failure: Uses `jest auth` or `vitest auth` (generic guesses)
```

### Category 4: Convention Adherence

Test whether the agent follows naming, import, and style conventions.

```markdown
## Eval: Import aliases
Task: "Import the Button component in a new page"
Expected: `import { Button } from '@/components/ui/button'`
Failure: `import Button from '../../../components/ui/Button'` (relative path)
```

### Category 5: Data Flow Understanding

Test whether the agent understands how data moves through the system.

```markdown
## Eval: Auth pattern
Task: "Add a protected API route that requires authentication"
Expected: Uses project's middleware pattern + JWT validation
Failure: Uses generic Next.js middleware or custom auth check
```

## Writing Good Evals

### Template
```markdown
## Eval: [Descriptive name]
Task: "[Natural language instruction a user would give]"
Expected: [Specific correct behavior, referencing AGENTS.md guidance]
Failure: [What the model would do WITHOUT AGENTS.md — the training-data default]
Why: [Which AGENTS.md section should prevent the failure]
```

### Rules
1. **One concept per eval** — don't combine version API + file placement in one scenario
2. **Natural language tasks** — write them as a real user would ask
3. **Binary pass/fail** — the expected behavior should be unambiguous
4. **Document the failure mode** — knowing WHY it fails without AGENTS.md validates the value
5. **Cover every Critical Rule** — each rule in your AGENTS.md should have at least one eval

## Running Evals

### Manual Verification
1. Start a fresh agent session (no prior context)
2. Ensure AGENTS.md is loaded in the context
3. Give the agent the eval task verbatim
4. Check output against Expected behavior
5. Record pass/fail

### Automated Verification (if supported)
```bash
# Example eval runner structure
for eval in evals/*.md; do
  result=$(run_agent --context AGENTS.md --task "$(cat $eval)")
  check_output "$result" "$eval"
done
```

## Coverage Checklist

Your eval suite should cover:
- [ ] Every item in "Version Corrections" section
- [ ] Every item in "Critical Rules" section
- [ ] File placement conventions
- [ ] Import patterns
- [ ] Build/test command usage
- [ ] Data flow / service layer usage
- [ ] Auth pattern compliance
- [ ] At least one "Known Pitfall" scenario

## Interpreting Results

| Pass Rate | Action |
|-----------|--------|
| 100% | AGENTS.md is well-calibrated |
| 80-99% | Review failing evals — likely missing or ambiguous guidance |
| 50-79% | Major gaps — rewrite Version Corrections and Critical Rules |
| < 50% | AGENTS.md may not be loaded, or is too large / poorly structured |

# AGENTS.md Template — Generic Project

Copy this template and fill in project-specific values.

```markdown
# AGENTS.md

## Project Overview
[App name] — [purpose]. [Primary language/framework], [key dependencies].
Deploy: [platform]. Runtime: [version].

## Critical Rules
- NEVER [action that breaks the project — e.g., commit without tests]
- NEVER [outdated pattern the model might suggest]
- ALWAYS [required workflow step — e.g., run build before marking complete]
- ALWAYS [tool/package preference — e.g., use pnpm not npm]

## Version Corrections ([version] — differs from training data)
|[API/pattern 1]: [correct usage] (NOT [wrong usage from training data])
|[API/pattern 2]: [correct usage] (NOT [old way])
|[New feature]: [description] (NEW in [version])
|[Deprecated feature]: removed, use [replacement] instead

## Architecture
```
[root]/
  [dir1]/          # [purpose]
  [dir2]/          # [purpose]
    [subdir]/      # [purpose]
  [dir3]/          # [purpose]
  [config files]   # [purpose]
```

## Commands
|build: `[exact build command]`
|dev: `[exact dev command]` (DO NOT run — user runs this)
|test: `[exact test command]`
|lint: `[exact lint command]`
|typecheck: `[exact typecheck command]`
|deploy: `[exact deploy command]`

## Conventions
|files: [naming convention — e.g., kebab-case, PascalCase]
|components: [component file pattern]
|tests: [test file placement — e.g., co-located, __tests__/]
|imports: [import alias — e.g., @/ for root, ~/]
|styling: [CSS approach — e.g., Tailwind, CSS modules, styled-components]
|state: [state management approach]
|errors: [error handling pattern]

## Data Flow
|[Layer 1] → [Layer 2] → [Layer 3] → [Response]
|Types in [types file] match [data source] shapes exactly
|[Pagination/caching/auth strategy]

## Environment
|[ENV_VAR_1]: [purpose] (required)
|[ENV_VAR_2]: [purpose] (optional, default: [value])
|Secrets: NEVER commit [file pattern — e.g., .env*, credentials.*]

## Docs Index
|root: ./[docs-directory]
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
|Read relevant doc file BEFORE writing code that uses framework APIs
|[category1]:{file1.md,file2.md}
|[category2]:{file3.md,file4.md}

## Known Pitfalls
|[Pitfall 1: description and correct approach]
|[Pitfall 2: description and correct approach]
|[Pitfall 3: description and correct approach]

## Self-Test
An agent reading this should correctly:
1. [ ] [Task that tests version-specific knowledge]
2. [ ] [Task that tests architecture understanding]
3. [ ] [Task that tests command knowledge]
4. [ ] [Task that tests convention adherence]
5. [ ] [Task that tests data flow understanding]
```

## Customization Notes

- Replace all `[bracketed values]` with project specifics
- "Version Corrections" is the HIGHEST value section — spend time identifying training-data gaps
- "Known Pitfalls" should come from real bugs, not hypothetical ones
- Keep total size under 10KB — compress further if needed
- Only add Docs Index if you have a docs directory with framework/API reference files
- Omit sections that don't apply (e.g., no Docs Index if no local docs)

# AGENTS.md Template — Next.js Full-Stack

Copy this template and fill in project-specific values.

```markdown
# AGENTS.md

## Project Overview
[App name] — [purpose]. Next.js [version], React [version], [CSS framework], [backend].
Deploy: [platform]. Node [version].

## Critical Rules
- NEVER use `getServerSideProps` or `getStaticProps` — App Router only
- NEVER use sync `cookies()` or `headers()` — they are async in v16+
- NEVER create files unless necessary — prefer editing existing
- ALWAYS run `[build command]` before marking work complete
- ALWAYS use `[package manager]` (not npm/yarn/pnpm alternatives)

## Version Corrections (v[X] — differs from training data)
|`'use cache'` directive replaces `revalidate` export
|`connection()` for dynamic rendering — NOT `cookies()` hack
|`forbidden()` returns 403, `unauthorized()` returns 401 (NEW)
|`cacheLife()` and `cacheTag()` replace revalidate options
|Async: cookies(), headers(), params, searchParams

## Architecture
```
app/              # Routes (App Router)
  (groups)/       # Route groups (no URL segment)
  api/            # API routes
components/       # Shared React components
  ui/             # Primitives (button, input, etc.)
lib/              # Utilities, services, types
  services.ts     # API client functions
  types.ts        # TypeScript interfaces
  utils.ts        # Shared helpers
public/           # Static assets
```

## Commands
|build: `npm run build`
|dev: `npm run dev` (DO NOT run — user runs this)
|test: `npm test`
|lint: `npm run lint`
|typecheck: `npm run typecheck`
|deploy: `npm run deploy`

## Conventions
|components: PascalCase files, named exports
|routes: lowercase folders, `page.tsx` per route
|API calls: use `lib/services.ts`, not raw fetch
|styling: Tailwind utility classes, no CSS modules
|state: React hooks, no external state lib
|imports: `@/` alias for project root

## Auth Pattern
|JWT in [localStorage|cookies|header]
|Auth check: `lib/auth-context.tsx` → `useAuth()` hook
|Protected routes: middleware.ts or layout-level check

## Data Flow
|Client → lib/services.ts → [Backend URL] → JSON response
|Types in lib/types.ts match API response shapes exactly
|No pagination from API — client-side pagination

## Docs Index
|root: ./[docs-directory]
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
|Read relevant doc file BEFORE writing code that uses framework APIs
|[category]:{file1.md,file2.md,...}

## Known Pitfalls
|[Pitfall 1: description and correct approach]
|[Pitfall 2: description and correct approach]
|[Pitfall 3: description and correct approach]

## Self-Test
An agent reading this should correctly:
1. [ ] Create a new route with correct file placement
2. [ ] Use async cookies()/headers() (not sync)
3. [ ] Run the correct build command
4. [ ] Use the project's service layer for API calls
5. [ ] Follow the established component pattern
```

## Customization Notes

- Replace `[bracketed values]` with project specifics
- The "Version Corrections" section is the HIGHEST value — spend time here
- Add project-specific pitfalls from real bugs you've encountered
- Keep total size under 10KB — compress further if needed
- Add docs index only if you have a `.docs/` directory with framework docs