agents.md: The Complete Guide to the Open Standard for AI Coding Agents

In a fragmented ecosystem where every AI coding tool uses its own configuration format, agents.md emerges as a refreshing attempt at standardization. Created through collaboration between OpenAI, Google, and other major players, agents.md is an open, simple, and tool-agnostic format for providing project-specific guidance.

The Simplicity Philosophy

agents.md's design philosophy is radical simplicity: single file, plain markdown, optional metadata, human-first, and tool-agnostic. No directory structure, no special syntax, no custom extensions - just markdown.

Why This Matters

The AI coding tool landscape is fragmented with Cursor using .cursor/rules/, GitHub Copilot using .github/copilot-instructions.md, Claude using .claude/skills/, and more. agents.md provides a neutral, open standard that all these tools can support.

🤖 Compatible Tools

The agents.md format is supported by multiple AI coding tools:

✓
OpenAI Codex - The foundational model that powers many AI coding tools
✓
GitHub Copilot - Reads agents.md in addition to .github/copilot-instructions.md
✓
Google Gemini Code Assist - Committed to supporting the open standard
✓
Any future tool - That adopts the open standard

This is why agents.md is the recommended format for teams using multiple AI tools or wanting to avoid vendor lock-in.

📁 OpenAI Codex: Hierarchical AGENTS.md

OpenAI Codex extends the standard with a hierarchical file system:

1.
~/.codex/AGENTS.md - Global guidance (loaded for all projects)
2.
AGENTS.md - Standard behavior (merges with parent directories)
3.
AGENTS.override.md - Codex extension (replaces parent instructions)

The override variant is useful for monorepos where subdirectories need completely different conventions. This is a Codex-specific extension, not part of the base agents.md specification.

Key insight: The format's power is in what it doesn't require:

•No frontmatter (unless you want it)
•No specific sections (organize however makes sense)
•No special syntax (just markdown)
•No tool-specific features (works everywhere)

PRPM's Implementation

PRPM treats agents.md as a flexible, unstructured format. The implementation includes optional frontmatter handling, auto-description extraction from first paragraph, flexible section parsing, auto-tag inference, and graceful fallbacks.

Design Decisions

1.Optional Frontmatter: Respects simplicity - frontmatter is entirely optional
2.Auto-Description Extraction: Extracts from first paragraph if not provided
3.Section Type Inference: Infers semantic types from content structure
4.Auto-Tag Inference: Automatically detects technology tags from content

What Goes in AGENTS.md?

The beauty of agents.md is its flexibility - there are no required fields. However, the specification recommends several sections that help AI agents understand your project:

Recommended Sections

1.Project Overview - What the project does and its purpose
2.Development Environment - Setup instructions and dependencies
3.Build & Test Commands - Specific commands to build and test
4.Code Style Guidelines - Conventions the AI should follow
5.Testing Instructions - How to write and run tests
6.Contribution Guidelines - How to contribute code
7.Security Considerations - Security practices and concerns

Real-World Example

Here's a practical example of an AGENTS.md file for a TypeScript web application:

# Project: TaskManager Web App

## Overview
This is a TypeScript-based task management application using React,
Next.js 14 (App Router), and PostgreSQL. The app allows teams to
create, assign, and track tasks with real-time updates.

## Tech Stack
- **Frontend**: React 18, Next.js 14, TailwindCSS
- **Backend**: Next.js API Routes, Prisma ORM
- **Database**: PostgreSQL 15
- **Testing**: Vitest, React Testing Library
- **Type Safety**: TypeScript strict mode

## Development Setup
```bash
npm install
cp .env.example .env.local
npm run db:migrate
npm run dev
```

## Code Style Guidelines
- Use TypeScript strict mode for all files
- Prefer functional components with React hooks
- Use async/await over promise chains
- Follow the existing ESLint configuration
- Use Prettier for formatting (runs on pre-commit)
- Name files using kebab-case: `user-profile.tsx`
- Use named exports over default exports

## Component Structure
- Place components in `src/components/`
- Co-locate component tests: `button.tsx` + `button.test.tsx`
- Extract shared utilities to `src/lib/`
- Keep server components by default; mark client components explicitly

## Testing Requirements
- Write unit tests for all utility functions
- Write integration tests for API routes
- Write component tests for interactive UI
- Maintain >80% code coverage
- Run tests before committing: `npm test`

## Database Changes
- Never modify migrations directly
- Create new migrations: `npm run db:migrate:create`
- Test migrations on dev database first
- Include rollback instructions in migration comments

## Security Practices
- Never commit API keys or secrets
- Use environment variables for all sensitive data
- Validate all user inputs on both client and server
- Sanitize data before database queries (Prisma handles this)
- Use HTTPS in production
- Implement rate limiting on public API endpoints

## Build Commands
- **Development**: `npm run dev` (port 3111)
- **Production Build**: `npm run build`
- **Type Check**: `npm run type-check`
- **Lint**: `npm run lint`
- **Test**: `npm test`
- **Test Coverage**: `npm run test:coverage`

## Common Tasks
- **Add new page**: Create file in `src/app/[route]/page.tsx`
- **Add API endpoint**: Create file in `src/app/api/[route]/route.ts`
- **Add database table**: Modify `prisma/schema.prisma`, run `npm run db:migrate:create`
- **Add environment variable**: Add to `.env.example` and update `src/env.ts`

Template Examples by Project Type

Different projects need different guidance. Here are starter templates:

🗄️ Backend API Project

Focus on API design, database patterns, authentication, error handling

Sections: API Routes, Database Schema, Auth Flow, Error Handling, Rate Limiting

⚛️ React Frontend Project

Focus on component patterns, state management, routing, styling

Sections: Component Structure, State Management, Routing, Styling, Testing Components

📦 Library/Package Project

Focus on API design, versioning, exports, documentation

Sections: Public API, Breaking Changes, Build Process, Publishing, Examples

🐍 Python Data Science Project

Focus on notebook patterns, data pipeline, model training, reproducibility

Sections: Data Pipeline, Model Training, Notebook Conventions, Dependencies, Reproducibility

Best Practices

1. Be Specific and Actionable

Don't write vague guidelines like "Write clean code." Instead, be concrete: "Use async/await over promise chains" or "Prefer functional components with hooks."

❌ Too Vague

"Write good tests"

✅ Specific

"Write unit tests for all utility functions. Maintain >80% coverage. Use Vitest."

2. Complement README, Don't Duplicate

README.md is for humans (project description, features, installation). AGENTS.md is for AI agents (how to write code, coding patterns, technical constraints).

3. Update Regularly

Keep AGENTS.md in sync with your codebase. When you change conventions, update the file. Outdated guidance leads to inconsistent AI-generated code.

4. Organize by Concern

Group related guidelines together (Code Style, Testing Strategy, Error Handling, Security) rather than mixing unrelated concerns. This helps AI agents find relevant guidance quickly.

Using agents.md with PRPM

PRPM (Prompt Package Manager) makes it easy to discover, install, and share agents.md packages. With 2,100+ packages across multiple formats, PRPM is the largest cross-platform repository for AI coding guidance.

Installing agents.md Packages

# Install an agents.md package directly
prpm install typescript-best-practices

# Search for agents.md packages
prpm search --format agents.md

# Search by subtype
prpm search --format agents.md --subtype agent
prpm search --format agents.md --subtype tool

# Install and convert to another format
prpm install typescript-best-practices --as cursor
prpm install typescript-best-practices --as copilot

Publishing Your Own agents.md Package

# Initialize a new package
prpm init

# Select "agents.md" as format
# Choose subtype: agent or tool

# Publish to PRPM registry
prpm publish

# Your package is now discoverable by 1,700+ users!

🎯 Why Publish to PRPM?

•Reach multiple tools: Your package works with Codex, Copilot, Gemini, and any future tool supporting agents.md
•Cross-format conversion: Users can install as Cursor, Claude, or any other format
•Discoverability: Listed in search results alongside 1,700+ other packages
•Version management: Semantic versioning with automatic updates

Format Comparison

How does agents.md compare to other AI coding tool formats?

Format	File Location	Structure	Cross-Tool
agents.md	`AGENTS.md`	Flexible markdown	✅ Yes
Cursor	`.cursor/rules/`	Plain text rules	❌ Cursor only
GitHub Copilot	`.github/copilot-instructions.md`	Markdown with frontmatter	⚠️ Partial (also reads agents.md)
Claude	`.claude/skills/*.md`	Directory of skills	❌ Claude only
Continue	`.continue/rules/*.md`	Directory of rules	❌ Continue only
Windsurf	`.windsurf/rules/`	Directory of rules	❌ Windsurf only

💡 Key Insight

agents.md is the only format designed to work across multiple tools. While tool-specific formats optimize for their respective ecosystems, agents.md prioritizes portability and standardization. This makes it ideal for:

•Teams using multiple AI coding tools
•Open source projects with diverse contributors
•Organizations avoiding vendor lock-in
•Package authors wanting maximum reach

Migrating to agents.md

Already using another format? Here's how to migrate to agents.md:

From Cursor (.cursor/rules/)

Cursor rules are already plain text instructions, making migration straightforward:

1.Copy content from .cursor/rules/ files
2.Create AGENTS.md and paste content
3.Add markdown structure: headings, lists, code blocks
4.Organize into sections (Project Overview, Code Style, etc.)
5.Keep .cursor/rules/ if still using Cursor (both can coexist)

From GitHub Copilot (.github/copilot-instructions.md)

Copilot instructions are already markdown, so migration is easy:

1.Copy .github/copilot-instructions.md content
2.Remove YAML frontmatter (agents.md doesn't require it)
3.Create AGENTS.md at project root with content
4.Keep Copilot file if still using Copilot (both can coexist)

Note: GitHub Copilot reads both agents.md and .github/copilot-instructions.md, so you can use either or both.

From Claude (.claude/skills/)

Claude uses a directory of separate skill files:

1.Combine all skill files from .claude/skills/
2.Create sections in AGENTS.md for each skill
3.Remove XML tags if present (use markdown instead)
4.Keep Claude skills if still using Claude

Automated Conversion with PRPM

# Convert Cursor to agents.md
prpm install my-cursor-package --as agents.md

# Convert Copilot to agents.md
prpm install my-copilot-package --as agents.md

# Convert Claude to agents.md
prpm install my-claude-package --as agents.md

# PRPM handles the conversion automatically!

File Location and Precedence

Understanding where to place AGENTS.md and how tools read it:

Standard Location (All Tools)

Place AGENTS.md at your project root:

project-root/
├── AGENTS.md          ← Place here
├── src/
├── package.json
└── README.md

OpenAI Codex: Hierarchical System

Codex searches from current directory up to repository root, merging instructions:

~/.codex/
└── AGENTS.md          ← Global (always loaded)

project-root/
├── AGENTS.md          ← Project-level
└── src/
    └── components/
        └── AGENTS.md  ← Component-level (merged with parents)

# Override variant (Codex-specific):
project-root/
└── src/
    └── legacy/
        └── AGENTS.override.md  ← Replaces all parent instructions

Precedence (highest to lowest): AGENTS.override.md → Closest AGENTS.md → Parent directories → ~/.codex/AGENTS.md

GitHub Copilot: Dual Support

Copilot reads both agents.md and its own format:

project-root/
├── AGENTS.md                         ← Read by Copilot
├── .github/
│   └── copilot-instructions.md       ← Also read by Copilot
└── README.md

Both files are read and merged. If there are conflicts, Copilot-specific instructions typically take precedence.

Why agents.md Matters

The AI coding tool landscape is fragmented today, but agents.md points toward a future where developers write guidance once (not 6 times), AI tools compete on features (not lock-in), open standards win over proprietary formats, and the community shares patterns freely.

The Vision: Universal AI Guidance

Imagine a world where you write one AGENTS.md file that works with every AI coding tool. Where you can switch tools without rewriting guidance. Where open source projects use a neutral format that welcomes all contributors. That's the promise of agents.md — and with PRPM's 1,700+ cross-platform packages, we're building that future today.

Explore More Formats

Continue Deep Dive View All Posts