AGENTS.md Spec (2026): Recommended Sections, the 30+ Tools That Read It, and AGENTS.md vs CLAUDE.md vs .cursorrules

What AGENTS.md Does

Every AI coding agent starts a task by scanning your repository. It reads file trees, package manifests, READMEs. But READMEs are written for humans. They explain what a project does, not how an agent should work on it.

AGENTS.md fills that gap. It is a markdown file, placed at the root of your repository, that contains the context coding agents need to work effectively: build commands with exact flags, test procedures, code style rules that differ from defaults, architectural constraints, and boundaries (files the agent should never touch).

The format is plain markdown. No required fields. No YAML frontmatter. No special syntax. Write headings and bullet points. The agent parses the text and adjusts its behavior accordingly.

AGENTS.md exists to solve one problem: developers were maintaining a separate instruction file for each tool (.cursorrules, CLAUDE.md, .github/copilot-instructions.md). AGENTS.md is the cross-tool standard. One file, every agent.

Recommended Sections: What to Include in AGENTS.md

AGENTS.md has no required fields. The spec describes it as a README for agents. The common sections, in the order most repositories use them:

1. Project overview: what the project is, primary language and framework with versions.
2. Build and test commands: exact commands with flags, not vague tool names.
3. Code style guidelines: only rules that differ from language defaults.
4. Testing instructions: how to run the suite, a single test, and what to mock.
5. Security considerations: secrets handling, files to never read or commit.
6. Commit and PR guidelines: branch naming, commit format, merge strategy.

An analysis of 2,500+ repositories by GitHub's engineering team found that effective files prioritize copy-pasteable commands over vague tool names, real code snippets over descriptive prose, and explicit boundaries over implicit assumptions. The six categories below map to those sections.

# Invoice API

FastAPI, Python 3.12, PostgreSQL, SQLAlchemy 2.0, Alembic.

## Commands

- `uv run dev`: Dev server (port 8000)
- `uv run pytest tests/ -v`: Full test suite
- `uv run pytest tests/unit/test_handlers.py -v`: Single test file
- `uv run ruff check --fix .`: Lint and auto-fix
- `alembic upgrade head`: Run migrations

## Architecture

- /app/api/v1/       Route handlers (thin, delegate to services)
- /app/services/     Business logic
- /app/models/       SQLAlchemy models
- /app/schemas/      Pydantic v2 request/response schemas
- /app/repositories/ Data access layer (no raw SQL)

## Code Style

- Type hints on all function signatures
- Async handlers by default
- Pydantic v2 models for all request/response shapes
- Named exports from __init__.py, no star imports

## Rules

- Handlers must not contain business logic. Delegate to services.
- All endpoints return { data, error, meta } shape.
- Redis is for caching only, not primary storage.
- Never modify /app/legacy/. It uses sync code intentionally.

## Testing

- pytest-asyncio for async tests
- Factory Boy for test data, never fixtures
- No mocking the database. Use test database.

Start with 20 to 30 lines covering the information agents most often get wrong. Add sections based on real agent mistakes, not hypothetical ones.

The Research: 28.6% Faster, 16.6% Fewer Tokens

A study from Princeton researchers measured the impact of AGENTS.md on real-world coding tasks. They ran OpenAI Codex (gpt-5.2-codex) across 10 repositories and 124 merged pull requests, executing each task twice in isolated Docker environments: once with the repository's AGENTS.md file present, once without.

The mechanism is straightforward. Without AGENTS.md, the agent spends time exploring: reading directory structures, inferring build systems, guessing test commands. With AGENTS.md, that context is provided upfront. The agent skips exploratory steps and works directly toward the solution.

What NOT to Include

The follow-up research found that auto-generated AGENTS.md files that duplicated existing README content actually reduced task success. Redundancy is the enemy. Every line should contain information the agent cannot get from reading your code, package manifests, or existing documentation.

Codex enforces a 32 KiB default size limit on AGENTS.md. Content beyond that limit is silently truncated. Even within the limit, shorter files perform better because every line competes for the agent's attention budget.

AGENTS.md vs CLAUDE.md vs .cursorrules vs copilot-instructions.md

Four tools, four configuration files. They serve the same purpose (giving agents project context) but differ in scope, loading behavior, and features.

If you use only one tool, use its native format. If you use multiple tools, put shared instructions in AGENTS.md and tool-specific configuration in the native file. One caveat the docs are explicit about: Claude Code reads CLAUDE.md, not AGENTS.md. To make Claude Code use a shared AGENTS.md, create a CLAUDE.md whose first line is @AGENTS.md (an import), or run /init in a repo that already has AGENTS.md and Claude Code will read and incorporate it (along with .cursorrules and .windsurfrules).

Which Tools Support Which Files

AGENTS.md has the broadest compatibility: 30+ agents read it, including OpenAI Codex, Claude Code (via import), GitHub Copilot, Cursor, Gemini CLI, Google Jules, Factory, Aider, Zed, VS Code, Windsurf, and Devin. If you maintain one instruction file, make it AGENTS.md. Add CLAUDE.md or .cursorrules only when you need features specific to those tools.

What is SKILL.md

AGENTS.md tells agents about your project. SKILL.md tells agents about a specific capability. A skill is a portable directory containing a SKILL.md file plus optional scripts, references, and assets. Skills work across Claude Code, OpenAI Codex, GitHub Copilot, and other compatible agents.

The standard uses progressive disclosure. When a session starts, the agent reads only skill names and descriptions (the YAML frontmatter). When a task matches a skill's domain, the agent loads the full SKILL.md body. Supplementary files (scripts, reference docs) load only when the agent needs them. This keeps context lean until the moment detail is required.

---
name: deploy
description: Deploy the application to production or staging environments
---

# Deploy

## Steps

1. Run the test suite: `bun run test`
2. Build for production: `bun run build`
3. Check for TypeScript errors: `bun run typecheck`
4. If all checks pass, deploy:
   - Staging: `vercel deploy --env preview`
   - Production: `vercel deploy --prod`
5. Verify health: `curl -s https://myapp.com/health | jq .status`

## Rules

- Never deploy to production without passing tests
- Always deploy to staging first for new features
- Production deploys require the main branch

SKILL.md vs AGENTS.md

Skill Directory Structure

my-skill/
├── SKILL.md            # Required: instructions + frontmatter
├── scripts/            # Optional: executable scripts
│   └── validate.sh
├── references/         # Optional: reference documentation
│   └── api-spec.yaml
└── assets/             # Optional: images, templates
    └── logo.svg

Where Skills Live

Skills can be stored in multiple locations depending on the tool:

• Project skills: .github/skills/, .claude/skills/, or .agents/skills/
• Personal skills: ~/.copilot/skills/, ~/.claude/skills/, or ~/.agents/skills/
• Installable skills: npx skills add https://docs-url (Vercel's skills CLI)

SKILL.md Frontmatter Schema

SKILL.md frontmatter sits between --- markers at the top of the file. Only description is meaningfully required (without it, the first paragraph of the body is used). The combined description text is truncated at 1,536 characters in the skill listing to keep context usage low.

---
name: deploy
description: >
  Deploy the app to staging or production. Use when the user
  asks to ship, release, or deploy. NOT for local dev runs.
disable-model-invocation: true
allowed-tools: Bash(git status *) Bash(vercel deploy *)
---

# Deploy

1. Run tests: `bun run test`
2. Staging: `vercel deploy --env preview`
3. Production: `vercel deploy --prod`

AGENTS.md Templates

Copy the template closest to your stack. Delete lines that do not apply. A shorter, accurate file outperforms a comprehensive, generic one.

Next.js / React / TypeScript

# Project Name

Next.js 15 App Router, React 19, TypeScript, Tailwind CSS, Drizzle ORM, Bun.

## Commands

- `bun run dev`: Dev server (port 3000)
- `bun run build`: Production build
- `bun run test`: Vitest suite
- `bunx vitest run src/path/to/test.ts`: Single test file
- `bun run db:push`: Push Drizzle schema changes
- `bun run lint`: ESLint

## Architecture

- /src/app/          App Router pages and layouts
- /src/components/   React components (named exports only)
- /src/lib/          Utilities, DB client, helpers
- /src/lib/db/       Drizzle schema and migrations
- /src/actions/      Server actions (all mutations go here)

## Code Style

- Server Components by default. Client components only for interactivity.
- ES modules (import/export). No CommonJS.
- No default exports except page.tsx and layout.tsx.
- Tailwind for styling. No CSS modules.

## Rules

- Mutations through server actions, not API routes.
- All DB access through Drizzle ORM in server components/actions.
- Run typecheck before committing: bun run typecheck.
- Never commit .env files.

Python / FastAPI

# Project Name

FastAPI, Python 3.12, PostgreSQL, SQLAlchemy 2.0, Alembic, uv.

## Commands

- `uv run dev`: Dev server (port 8000)
- `uv run pytest tests/ -v`: Full test suite
- `uv run pytest tests/unit/test_handlers.py::test_create -v`: Single test
- `uv run ruff check --fix .`: Lint
- `alembic upgrade head`: Migrations

## Architecture

- /app/api/v1/       Route handlers (thin, delegate to services)
- /app/services/     Business logic
- /app/models/       SQLAlchemy models
- /app/schemas/      Pydantic v2 schemas
- /app/repositories/ Data access (repository pattern)

## Rules

- Type hints on all functions. Async handlers by default.
- Handlers delegate to services. No business logic in routes.
- All DB access through repositories. No raw SQL.
- Return { data, error } shape from all endpoints.
- Use dependency injection for DB sessions.
- Never modify /app/legacy/. Sync code, intentionally.

Monorepo

# Monorepo Name

Turborepo, pnpm workspaces. Frontend (Next.js) + API (Express) + shared packages.

## Commands

- `pnpm dev`: Start all services
- `pnpm build`: Build all packages
- `pnpm test`: Run all tests
- `turbo run test --filter=@app/api`: Test single package

## Structure

- /apps/web/       Next.js frontend (see apps/web/AGENTS.md)
- /apps/api/       Express API (see apps/api/AGENTS.md)
- /packages/ui/    Shared React components
- /packages/db/    Drizzle schema, shared across apps
- /packages/types/ Shared TypeScript types

## Rules

- Shared types in @app/types. Never duplicate type definitions.
- Import shared packages by name: import { Button } from '@app/ui'
- Never use relative paths across package boundaries.
- Each package has its own AGENTS.md for package-specific rules.
- DB schema changes require migrations in both dev and test databases.

SKILL.md Template

---
name: my-skill
description: >
  When to use: [specific trigger condition].
  When NOT to use: [explicit exclusion].
user-invocable: true
disable-model-invocation: false
---

# Skill Name

## Prerequisites

- [Required tools, access, or state]

## Steps

1. [First action with exact command]
2. [Second action]
3. [Verification step]

## Rules

- [Constraint 1]
- [Constraint 2]

## Examples

[One real example showing input and expected output]

FAQ

Should I use AGENTS.md or CLAUDE.md?

If you use multiple coding agents, use AGENTS.md for shared instructions and CLAUDE.md for Claude-specific features (@imports, skills, hooks). If you only use Claude Code, CLAUDE.md alone is enough since it has more features. Claude Code reads CLAUDE.md, not AGENTS.md, by default. To share one file, point CLAUDE.md at it with a first-line @AGENTS.md import, or run /init in a repo that has AGENTS.md. See our CLAUDE.md guide for detailed Claude Code configuration.

How long should AGENTS.md be?

Start with 20 to 30 lines. The best files from the GitHub analysis of 2,500 repositories were concise and specific. Codex enforces a 32 KiB cap and silently truncates beyond it. Shorter files performed better in the Princeton study because agents spent less time parsing instructions and more time on the task.

Can I have multiple AGENTS.md files in one repository?

Yes. Nested AGENTS.md files provide directory-specific context. The agent reads the nearest file to the code being edited. Root-level rules apply everywhere; subdirectory rules override for that subtree. OpenAI's Codex repository uses 88 AGENTS.md files across its directory structure.

Does AGENTS.md replace documentation?

No. AGENTS.md complements your README and docs. It contains agent-specific context that would clutter human documentation: exact test flags, architectural constraints an agent needs to follow, files it should never modify. Keep your README for humans, AGENTS.md for agents.

Should I auto-generate AGENTS.md?

Be careful. The second research study found that LLM-generated AGENTS.md files reduced success rates by 2% and increased cost by 23%, primarily because they duplicated content already available in the repository. Human-written files that contain genuinely non-obvious information performed better. Use /init or a generator as a starting point, then aggressively edit and trim.

What are the recommended sections in the AGENTS.md format?

The spec defines no required fields, so there is no fixed schema. The sections most repositories include are: project overview, build and test commands, code style guidelines, testing instructions, security considerations, and commit/PR guidelines. Keep each section to information the agent cannot infer from your code or package manifests.

What is the SKILL.md frontmatter schema (paths, disable-model-invocation)?

Claude Code SKILL.md frontmatter supports name, description, disable-model-invocation (true blocks auto-loading, manual /name only), user-invocable (false hides it from the / menu), allowed-tools, disallowed-tools, model, context (set to fork for an isolated subagent), and arguments. There is no paths field in SKILL.md. The paths frontmatter belongs to .claude/rules/*.md, where paths: ["src/api/**/*.ts"] scopes a rule to load only when Claude reads a matching file.