AGENTS.md

This file provides context for AI coding assistants (Cursor, GitHub Copilot, Claude Code, etc.) working with the Vercel AI SDK repository.

Project Overview

The AI SDK by Vercel is a TypeScript/JavaScript SDK for building AI-powered applications with Large Language Models (LLMs). It provides a unified interface for multiple AI providers and framework integrations.

• Repository: https://github.com/vercel/ai
• Documentation: https://ai-sdk.dev/docs
• License: Apache-2.0

Repository Structure

This is a monorepo using pnpm workspaces and Turborepo.

Key Directories

Directory	Description
packages/ai	Main SDK package (ai on npm)
packages/provider	Provider interface specifications (@ai-sdk/provider)
packages/provider-utils	Shared utilities for providers and core (@ai-sdk/provider-utils)
packages/<provider>	AI provider implementations (openai, anthropic, google, azure, amazon-bedrock, etc.)
packages/<framework>	UI framework integrations (react, vue, svelte, angular, rsc)
packages/codemod	Automated migrations for major releases
examples/	Example applications (ai-functions, next-openai, etc.)
content/	Documentation source files (MDX)
contributing/	Contributor guides and documentation
tools/	Internal tooling (tsconfig)

Core Package Dependencies

ai ─────────────────┬──▶ @ai-sdk/provider-utils ──▶ @ai-sdk/provider
                    │
@ai-sdk/<provider> ─┴──▶ @ai-sdk/provider-utils ──▶ @ai-sdk/provider

Development Setup

Requirements

• Node.js: v22, v24, or v26 (v22 recommended for development)
• pnpm: v10+ (npm install -g pnpm@10)

Initial Setup

pnpm install        # Install all dependencies
pnpm build          # Build all packages

Development Commands

Root-Level Commands

Command	Description
pnpm install	Install dependencies
pnpm build	Build all packages
pnpm test	Run all tests (excludes examples)
pnpm check	Run linting (oxlint) and formatting (oxfmt) checks
pnpm fix	Fix linting and formatting issues
pnpm type-check:full	TypeScript type checking (includes examples)
pnpm changeset	Add a changeset for your PR
pnpm update-references	Update tsconfig.json references after adding package dependencies

Package-Level Commands

Run these from within a package directory (e.g., packages/ai):

Command	Description
pnpm build	Build the package
pnpm build:watch	Build with watch mode
pnpm test	Run all tests (node + edge)
pnpm test:node	Run Node.js tests only
pnpm test:edge	Run Edge runtime tests only
pnpm test:watch	Run tests in watch mode

Running Examples

cd examples/ai-functions
pnpm tsx src/stream-text/openai/basic.ts    # Run a specific example

AI Functions Example Layout

• Place examples under examples/ai-functions/src/<function>/<provider>/
• Use basic.ts for the provider entry example file
• Place all other examples in the same provider folder using descriptive kebab-case file names
• Do not create flat top-level provider files like src/stream-text/openai.ts

Core APIs

Function	Purpose	Package
generateText	Generate text completion	ai
streamText	Stream text completion	ai
generateObject	Generate structured output	ai
streamObject	Stream structured output	ai
embed / embedMany	Generate embeddings	ai
generateImage	Generate images	ai
tool	Define a tool	ai
jsonSchema / zodSchema	Define schemas	ai

Import Patterns

What	Import From
Core functions (generateText, streamText)	ai
Tool/schema utilities (tool, jsonSchema)	ai
Provider implementations	@ai-sdk/<provider> (e.g., @ai-sdk/openai)
Error classes	ai (re-exports from @ai-sdk/provider)
Provider type interfaces (LanguageModelV4)	@ai-sdk/provider
Provider implementation utilities	@ai-sdk/provider-utils

Coding Standards

Formatting

• Formatter: oxfmt (via pnpm fix or ultracite fix)
• Linter: oxlint (via pnpm check or ultracite check)
• Config: .oxfmtrc.jsonc (formatter) and .oxlintrc.json (linter)
• Pre-commit hook: Runs pnpm install if package.json changes are staged

Testing

• Framework: Vitest
• Test files: *.test.ts alongside source files
• Type tests: *.test-d.ts for type-level tests
• Fixtures: Store in __fixtures__ subfolders
• Snapshots: Store in __snapshots__ subfolders

Zod Usage

The SDK supports both Zod 3 and Zod 4. Use correct imports:

// For Zod 3 (compatibility code only)
import * as z3 from 'zod/v3';

// For Zod 4
import * as z4 from 'zod/v4';
// Use z4.core.$ZodType for type references

JSON parsing

Never use JSON.parse directly in production code to prevent security risks. Instead use parseJSON or safeParseJSON from @ai-sdk/provider-utils.

Type Checking

Always run type checking after making code changes:

pnpm type-check:full    # Run from workspace root

This ensures your changes don't introduce type errors across the codebase, including examples.

File Naming Conventions

• Source files: kebab-case.ts
• Test files: kebab-case.test.ts
• Type test files: kebab-case.test-d.ts
• React/UI components: kebab-case.tsx

Error Pattern

Errors extend AISDKError from @ai-sdk/provider and use a marker pattern for instanceof checks:

import { AISDKError } from '@ai-sdk/provider';

const name = 'AI_MyError';
const marker = `vercel.ai.error.${name}`;
const symbol = Symbol.for(marker);

export class MyError extends AISDKError {
  private readonly [symbol] = true; // used in isInstance

  constructor({ message, cause }: { message: string; cause?: unknown }) {
    super({ name, message, cause });
  }

  static isInstance(error: unknown): error is MyError {
    return AISDKError.hasMarker(error, marker);
  }
}

Architecture Decision Records (ADRs)

This repo uses ADRs in contributing/decisions/ to capture important architecture decisions. Before making changes that touch architecture (new dependencies, new patterns, API design, infrastructure), check existing ADRs:

1. Read contributing/decisions/README.md for the index of decisions.
2. Read any accepted ADRs relevant to your area of work. Follow the decisions and implementation patterns they specify.
3. If you encounter a pattern in the code and wonder "why is it done this way?", check whether an ADR explains it.
4. If your work would contradict an existing accepted ADR, stop and discuss with the human before proceeding.

To propose or create a new ADR, use the ADR skill.

Project Philosophies

For an overview of the project's key philosophies that guide decision making, see contributing/project-philosophies.md.

Architecture

Provider Pattern

The SDK uses a layered provider architecture following the adapter pattern:

1. Specifications (@ai-sdk/provider): Defines interfaces like LanguageModelV4
2. Utilities (@ai-sdk/provider-utils): Shared code for implementing providers
3. Providers (@ai-sdk/<provider>): Concrete implementations for each AI service
4. Core (ai): High-level functions like generateText, streamText, generateObject

For a focused conceptual walkthrough of AI functions, model specifications, and provider implementations, see architecture/provider-abstraction.md.

Provider Development

Provider Options Schemas (user-facing):

• Use .optional() unless null is meaningful
• Be as restrictive as possible for future flexibility

Response Schemas (API responses):

• Use .nullish() instead of .optional()
• Keep minimal - only include properties you need
• Allow flexibility for provider API changes

Adding New Packages

1. Create folder under packages/<name>
2. Add to root tsconfig.json references
3. Run pnpm update-references if adding dependencies between packages

Contributing Guides

Task	Guide
Add new provider	contributing/add-new-provider.md
Add new model	contributing/add-new-model.md
Testing & fixtures	contributing/testing.md
Provider architecture	contributing/provider-architecture.md
Building new features	contributing/building-new-features.md
Codemods	contributing/codemods.md

Changesets

• Required: Every PR modifying production code needs a changeset
• Default: Use patch (non-breaking changes)
• Command: pnpm changeset in workspace root
• Note: Don't select example packages - they're not published

Task Completion Guidelines

These guidelines outline typical artifacts for different task types. Use judgment to adapt based on scope and context.

Bug Fixes

A complete bug fix typically includes:

1. Reproduction example: Create/update an example in examples/ that demonstrates the bug before fixing
2. Unit tests: Add tests that would fail without the fix (regression tests)
3. Implementation: Fix the bug
4. Manual verification: Run the reproduction example to confirm the fix
5. Changeset: Describe what was broken and how it's fixed

New Features

A complete feature typically includes:

1. Implementation: Build the feature
2. Examples: Add usage examples in examples/ demonstrating the feature
3. Unit tests: Comprehensive test coverage for new functionality
4. Documentation: Update relevant docs in content/ for public APIs
5. Changeset: Describe the feature for release notes

Refactoring / Internal Changes

• Unit tests for any changed behavior
• No documentation needed for internal-only changes
• Changeset only if it affects published packages

When to Deviate

These are guidelines, not rigid rules. Adjust based on:

• Scope: Trivial fixes (typos, comments) may not need examples
• Visibility: Internal changes may not need documentation
• Context: Some changes span multiple categories

When uncertain about expected artifacts, ask for clarification.

Do Not

• Add minor/major changesets
• Change public APIs without updating documentation
• Use require() for imports
• Add new dependencies without running pnpm update-references
• Modify content/docs/08-migration-guides or packages/codemod as part of broader codebase changes

Awesome Agent Conventions

A curated field guide to the convention files AI agents read, write, and act on.

22 conventions across 11 categories. From common project instruction files to newer agent-web discovery and trust formats.

Agent tools increasingly rely on plain files in a repository or website root: instructions, memory, rules, tool connections, prompt assets, discovery metadata, and protocol hints. The names are easy to mix up, and the adoption levels vary a lot.

This repo keeps the map practical:

• Know what a file is for. Each entry names the convention, usual filename, primary readers, and spec or source.
• Study real examples. Examples are fetched from public repositories by script, with provenance kept at the top of each file.
• Separate practice from proposal. Maturity labels show what is widely used, what is early, and what is still only proposed.

Contents

• Instruction & context · category page
  • 🟢 AGENTS.md
  • 🟢 CLAUDE.md
  • 🟢 Tool-specific instruction files
  • 🟠 OKF (Open Knowledge Format)
• Memory & state · category page
  • 🟢 MEMORY.md
  • 🟢 Memory Bank
• Spec-driven development · category page
  • 🟢 Spec Kit
  • 🟢 Kiro steering files
• Skills & prompt assets · category page
  • 🟢 SKILL.md
  • 🟢 Prompt asset files
  • 🟢 Claude Code commands
  • 🟢 Copilot prompt & instruction files
• Tooling & connections · category page
  • 🟢 MCP server config
• Rules & ignore files · category page
  • 🟢 Rules files
  • 🟢 AI ignore files
• Design · category page
  • 🟢 DESIGN.md
• Web & discoverability · category page
  • 🟢 llms.txt
  • 🟢 pricing.md
• Agent-web trust · category page
  • 🟠 auth.md
  • 🔵 ai.txt
• Identity & protocols · category page
  • 🟠 Agent Cards (A2A)
• Proposed namespace · category page
  • 🔵 The protocols.md namespace

What counts

This list is intentionally narrow. A file belongs here when it is a convention for agent behavior or agent-readable metadata: instructions, memory, skills, rules, tool config, prompt assets, or web-discovery hints.

Any file type can qualify - .md, .txt, .prompty, .json, dotfiles, or a directory pattern. Human-first project docs such as README.md, CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md stay out unless the file has become an agent convention in its own right.

Maturity tiers

The badge is a claim about adoption, not quality. It keeps a proven convention from being presented the same way as a new idea.

Badge	Tier	Meaning
🟢	Adopted	Used in production by multiple tools, projects, or teams.
🟠	Emerging	Published by a real organization, but still early or limited in adoption.
🔵	Proposed	Publicly described, but without clear adoption beyond the proposal.

Instruction & context

Standalone page: categories/instruction-context.md

	Convention	Files	Read by	Spec
🟢	AGENTS.md	AGENTS.md	Most coding agents - OpenAI Codex, Cursor, Jules, Aider, Gemini CLI, Zed, and others	spec ↗
🟢	CLAUDE.md	CLAUDE.md	Claude Code, and tools that read the Claude memory convention	spec ↗
🟢	Tool-specific instruction files	GEMINI.md AGENT.md QWEN.md WARP.md CONVENTIONS.md copilot-instructions.md	Each file is read by its namesake tool - Gemini CLI, Amp, Qwen Code, Warp, Aider, GitHub Copilot - often alongside or as a bridge to AGENTS.md	spec ↗
🟠	OKF (Open Knowledge Format)	.md	Agents over MCP (okfy, openknowledge, superops okf CLIs); Google's knowledge-catalog ingests bundles	spec ↗

• AGENTS.md - A plain-Markdown "README for agents" - build/test commands, conventions, and gotchas an agent needs before touching the code. The most widely adopted cross-tool instruction file.
• CLAUDE.md - Anthropic's memory file for Claude Code - loaded automatically at session start to carry project commands, style rules, and standing instructions across turns.
• Tool-specific instruction files - Per-tool instruction files that predate or coexist with AGENTS.md. Some tools now default to AGENTS.md while keeping legacy filenames alive, so these variants still matter when auditing real repositories.
• OKF (Open Knowledge Format) - A machine-first organizational knowledge base: a version-controlled folder of typed Markdown files (one concept per file) that any agent reads as ground-truth context. Open-sourced by Google Cloud in 2026 as the content layer to MCP's transport.

Memory & state

Standalone page: categories/memory-state.md

	Convention	Files	Read by	Spec
🟢	MEMORY.md	MEMORY.md	Claude Code's auto-memory - the per-project MEMORY.md index it writes and re-reads each session	spec ↗
🟢	Memory Bank	projectbrief.md productContext.md activeContext.md systemPatterns.md techContext.md progress.md	Cline, Roo Code, and Cursor (via the Memory Bank custom-instructions pattern)	spec ↗

• MEMORY.md - A persistent, agent-maintained index of durable facts - written and re-read across sessions so an agent accumulates project memory instead of relearning each time.
• Memory Bank - Cline's structured memory system - a set of Markdown files an agent reads at the start of every task to reconstruct full project context after its session memory resets. The six files shown are Cline's set; tools like Roo Code use an overlapping but different variant.

Spec-driven development

Standalone page: categories/spec-driven-development.md

	Convention	Files	Read by	Spec
🟢	Spec Kit	constitution.md spec.md plan.md tasks.md	GitHub Spec Kit's slash-command agents (Copilot, Claude, Gemini, Cursor, and more)	spec ↗
🟢	Kiro steering files	product.md structure.md tech.md	AWS Kiro (steering files are largely Kiro-specific)	spec ↗

• Spec Kit - GitHub's spec-driven workflow - a constitution plus per-feature spec → plan → tasks files that drive an agent through structured, reviewable implementation.
• Kiro steering files - Kiro's always-on steering docs - product, structure, and tech files that give the agent persistent project context outside of any single spec.

Skills & prompt assets

Standalone page: categories/skills-prompt-assets.md

	Convention	Files	Read by	Spec
🟢	SKILL.md	SKILL.md	Claude Agent Skills, Claude Code, Amp, Agent Skills-compatible tools	spec ↗
🟢	Prompt asset files	.prompty .prompt system_prompt.txt	Prompty tooling, Azure AI / Semantic Kernel, and apps that load externalized prompts	spec ↗
🟢	Claude Code commands	.md	Claude Code - project .claude/commands/ and user ~/.claude/commands/	spec ↗
🟢	Copilot prompt & instruction files	.prompt.md .instructions.md	GitHub Copilot in VS Code / Copilot CLI	spec ↗

• SKILL.md - A self-contained, model-invoked capability file that tells an agent when to load a reusable procedure and how to execute it.
• Prompt asset files - Externalized prompt files - Prompty's YAML-front-mattered .prompty, plain .prompt templates, and system_prompt.txt - that pull the prompt out of source code so it can be versioned and edited on its own. Only .prompty has a formal spec (prompty.ai); .prompt and system_prompt.txt are ad-hoc externalized-prompt filenames.
• Claude Code commands - A Markdown file Claude Code exposes as a /slash-command - a reusable, version-controlled prompt workflow, with optional frontmatter (allowed-tools, model, argument-hint) and $ARGUMENTS and shell placeholders (@file references are a general Claude Code prompt feature, not command-specific). Now converging with Agent Skills, but still widely committed in its own right.
• Copilot prompt & instruction files - Modular, path-scoped Copilot context: *.instructions.md auto-attach to matching files via an applyTo glob, while *.prompt.md are reusable prompts you invoke by name - the granular cousins of a single .github/copilot-instructions.md.

Tooling & connections

Standalone page: categories/tooling-connections.md

	Convention	Files	Read by	Spec
🟢	MCP server config	.mcp.json	Claude Code, Cursor, VS Code / Copilot, and Claude Desktop - every MCP host reads the same mcpServers schema, though the filename and path differ per tool	spec ↗

• MCP server config - A JSON file that tells an agent which Model Context Protocol servers to launch and how (command, args, env) - making a project's tool and data integrations portable, shareable, and version-controlled across every MCP-capable client.

Rules & ignore files

Standalone page: categories/rules-ignore-files.md

	Convention	Files	Read by	Spec
🟢	Rules files	.cursorrules .mdc .clinerules .clinerules/ (pattern) .windsurfrules	Cursor (.cursorrules / .mdc), Cline (.clinerules/ and legacy .clinerules), Windsurf (.windsurfrules)	spec ↗
🟢	AI ignore files	.aiignore .cursorignore .codeiumignore .aiexclude	JetBrains Junie (.aiignore), Cursor (.cursorignore), Codeium/Windsurf (.codeiumignore)	spec ↗

• Rules files - Per-tool rule files that scope agent behavior - older single-file forms (.cursorrules, .clinerules, .windsurfrules) and newer directory-based, glob-scoped forms (.cursor/rules/.mdc, .clinerules/, .windsurf/rules/.md).
• AI ignore files - gitignore-syntax files that fence an AI agent out of paths - secrets, vendored code, generated output - so they're never sent to the model as context.

Design

Standalone page: categories/design.md

	Convention	Files	Read by	Spec
🟢	DESIGN.md	DESIGN.md	Google Stitch natively; and coding agents (e.g. Claude Code) when pointed at it as design context	spec ↗

• DESIGN.md - A structured, machine-readable design specification - tokens, components, and layout intent - that an agent reads to generate or keep UI consistent with an established system. Open-sourced by Google Labs in 2026 as a cross-tool draft spec.

Web & discoverability

Standalone page: categories/web-discoverability.md

	Convention	Files	Read by	Spec
🟢	llms.txt	llms.txt llms-full.txt (pattern)	Docs sites publish it for LLM tools and crawlers - though no major provider has confirmed reading it	spec ↗
🟢	pricing.md	pricing.md	Agents and LLM browsers fetching a clean, parse-able pricing page	spec ↗

• llms.txt - A proposed-turned-widely-published standard: a root-level Markdown file giving LLMs a curated, link-rich map of a site's docs. Published across hundreds of developer-docs sites - though whether the major LLM providers actually read it remains unproven.
• pricing.md - The Markdown twin of a pricing page - same URL with a .md suffix - so an agent gets structured plans and numbers instead of scraping marketing HTML. A concrete, shipping instance of the page.md pattern.

Agent-web trust

Standalone page: categories/agent-web-trust.md

	Convention	Files	Read by	Spec
🟠	auth.md	auth.md	Agents discovering how to authenticate to a service (early adopters)	spec ↗
🔵	ai.txt	ai.txt	AI training/data-mining crawlers that voluntarily honor AI usage preferences; crawler support is not yet reliable	spec ↗

• auth.md - A Markdown file that tells an agent how to authenticate with a service - discovery of auth endpoints and flows. Shipped by WorkOS as a real, working convention, but adoption beyond it is still early.
• ai.txt - A text file declaring machine-readable consent, licensing, or policy preferences for AI training and data-mining. Spawning popularized the deployed root-file pattern, and a 2026 Internet-Draft now proposes a well-known URI; adoption and crawler obedience are still thin, so it stays 🔵.

Identity & protocols

Standalone page: categories/identity-protocols.md

	Convention	Files	Read by	Spec
🟠	Agent Cards (A2A)	agent-card.json agent.json (pattern)	A2A-compatible agents discovering another agent's capabilities	spec ↗

• Agent Cards (A2A) - The Agent2Agent (A2A) capability card - a JSON document at a well-known path advertising an agent's skills, endpoints, and auth so other agents can discover and call it. Now a Linux Foundation project at v1.0; adoption is growing but early.

Proposed namespace

Standalone page: categories/proposed-namespace.md

	Convention	Files	Read by	Spec
🔵	The protocols.md namespace	proof.md	- (no demonstrated readers; aspirational)	spec ↗

• The protocols.md namespace - A single maintainer's pre-registered namespace of ~74 aspirational .md "protocols" (proof.md, signature.md, reputation.md, …) staked as Schelling points for a future agent web. Published concept, no demonstrated adoption - see the page for the audited, honest caveats.

Maintaining examples

Example files are fetched, not invented. The extractor pulls them from public sources, stores them under conventions/<slug>/examples/<source>/<filename>, and adds a line-1 provenance comment. The examples remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md before reusing them.

To refresh everything:

pip install -r scripts/requirements.txt
python scripts/extract.py          # fetch real files + rebuild each convention's README
python scripts/build_readme.py     # rebuild this README from scripts/targets.json

Re-running is idempotent. A missing target prints a miss and is skipped. Examples are representative samples: any file over 256 KB (for example, a multi-MB llms-full.txt) is truncated with a marker pointing back to the full source. scripts/targets.json remains the source of truth for conventions that have not been migrated yet; the skill-md pilot uses local convention metadata instead. Edit the relevant source and re-run both scripts.

Shortcut targets are available in the Makefile:

make verify          # schema + generated files + example provenance + links
make extract         # refetch public examples and rebuild generated docs
make license-report  # summarize upstream licenses for vendored examples

CI keeps the generated files and links honest. The verify workflow checks that generated docs match catalog metadata and migrated local metadata, and that every spec, example, and instance URL still resolves on each pull request and weekly. Run the same link check locally with python scripts/check_links.py.

Contributing

Read CONTRIBUTING.md. In short: an entry must pass the filter above and carry evidence for its maturity tier. Add sources to scripts/targets.json for non-migrated conventions, run the scripts, and open a PR. The skill-md pilot uses local convention metadata instead. Do not hand-write example files.

Before proposing adjacent standards, check WATCHLIST.md. Project direction lives in ROADMAP.md.

License

The curation, scripts, and original prose in this repository are MIT. Vendored example files remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md.