AGENTS.md Cross-Tool Unified Management Guide [Feb 2026] - Control All AI Agents with a Single File¶

Q: Does AGENTS.md conflict with CLAUDE.md / copilot-instructions.md?

No, they don't conflict. AGENTS.md serves as shared project information for all tools, while tool-specific files provide differences for that specific tool — they are complementary. The recommended approach is to write common rules in AGENTS.md and tool-specific settings in the respective tool files.

GitHub Copilot Complete Guide

Target Audience

Teams using multiple AI coding tools

Key Points¶

Unified management with a single file
Provide consistent instructions to AI agents across GitHub Copilot, Claude Code, Codex, Cursor, and more with a single AGENTS.md file
Full monorepo support
Place nested AGENTS.md files at the root and in subdirectories to manage package-specific rules hierarchically
Backed by an open standard
Governed by AAIF (Agentic AI Foundation) under the Linux Foundation. Co-developed by Anthropic, OpenAI, Google, Microsoft, and others
Symlink strategy
Use AGENTS.md as the source of truth and link it to tool-specific files, minimizing maintenance overhead

📖 What Is AGENTS.md?¶

Write a README for your AI agents

AGENTS.md is essentially a README for AI coding agents. It allows you to describe project-specific build instructions, coding conventions, testing policies, security rules, and more in standard Markdown format, providing a shared context that multiple AI tools can read.

Standardization History¶

Timeline	Event
August 2025	OpenAI created and published the AGENTS.md format for Codex
Late 2025	GitHub Copilot, Claude Code, Cursor, and others announced support
December 2025	AAIF (Agentic AI Foundation) established under the Linux Foundation, taking over governance of the AGENTS.md specification
As of February 2026	Adopted by over 60,000 open source projects. Supported by 20+ tools

AAIF (Agentic AI Foundation) Founding Members

Anthropic (Claude Code)
OpenAI (Codex)
Google (Gemini CLI / Jules)
Microsoft (GitHub Copilot)
Amazon
Block (goose)
Bloomberg
Cloudflare

Official specification: https://agents.md/

Key Features of AGENTS.md¶

Standard Markdown format: No special syntax or schema required. Human-readable
No mandatory fields: Freely describe whatever sections are useful for your project
Version control friendly: Easy to manage diffs and reviews with git
Shared documentation for humans and AI: Also functions as onboarding material

🌐 Tool Compatibility Matrix¶

As of February 2026, virtually all major AI coding tools support AGENTS.md.

Tool	AGENTS.md	Tool-Specific File	Notes
GitHub Copilot	Supported	`.github/copilot-instructions.md`	Enable via VS Code settings
Claude Code	Supported	`CLAUDE.md`	Auto-loaded
OpenAI Codex	Supported	`AGENTS.md` (origin)	Native support
Cursor	Supported	`.cursor/rules/`	Also supports `.cursorrules`
Gemini CLI	Supported	`GEMINI.md`	Google Jules also supported
Windsurf	Supported	`.windsurfrules`	—
Devin	Supported	—	By Cognition
goose	Supported	—	By Block (donated to AAIF)
Amp	Supported	—	By Sourcegraph
Aider	Supported	`.aider.conf.yml`	—

Key Point

AGENTS.md serves as the "greatest common denominator." Tool-specific files handle the "differences," and combining both enables per-tool optimization.

⚙️ VS Code / GitHub Configuration¶

To enable AGENTS.md with GitHub Copilot, add the following to your VS Code settings.json:

// .vscode/settings.json
{
  "chat.useAgentsMdFile": true,
  "chat.useNestedAgentsMdFiles": true
}

Setting Key	Description
`chat.useAgentsMdFile`	Load AGENTS.md in Copilot Chat / Agent Mode
`chat.useNestedAgentsMdFiles`	Also enable AGENTS.md in subdirectories (monorepo support)

When Settings Take Effect

After changing settings, you may need to reload VS Code (Ctrl+Shift+P → Developer: Reload Window). Also, chat.useNestedAgentsMdFiles is unnecessary for non-monorepo projects.

🏗️ Recommended File Structure¶

We recommend placing AGENTS.md at the project root as the source of truth and combining it with tool-specific files.

project-root/
├── AGENTS.md                              # Source of Truth (shared across all tools)
├── .github/
│   └── copilot-instructions.md            # Copilot-specific additions (or symlink)
├── CLAUDE.md                              # Claude Code-specific (or symlink)
├── .cursor/
│   └── rules/
│       └── agents.md                      # Cursor-specific (or symlink)
└── packages/
    ├── frontend/
    │   └── AGENTS.md                      # Frontend-specific instructions
    └── backend/
        └── AGENTS.md                      # Backend-specific instructions

File Loading Priority

Most tools prioritize the AGENTS.md closest to the file being edited. When both packages/frontend/AGENTS.md and the root AGENTS.md exist, the package-level AGENTS.md takes priority while editing frontend files.

🔗 Symlink Strategy¶

Here are two approaches for managing the relationship between AGENTS.md and tool-specific files.

Approach 1: Full Unification with Symlinks¶

# Link AGENTS.md as the source of truth to other tool files
# Note: Symlinks use relative paths from the link location
ln -s ../AGENTS.md .github/copilot-instructions.md
ln -s AGENTS.md CLAUDE.md                           # Same directory, so use as-is
ln -s ../../AGENTS.md .cursor/rules/agents.md

About Relative Paths

The first argument to ln -s is the relative path from the link file's location. A link created inside .github/ uses ../AGENTS.md, while one inside .cursor/rules/ uses ../../AGENTS.md. Adjust according to your project structure.

Pros	Cons
Only one file to maintain	Cannot cover tool-specific feature differences
Complete consistency guaranteed	Cannot include Claude Code-specific MCP settings, etc.
Simple diff management with git	Some CI environments don't support symlinks

Approach 2: Shared Base + Tool-Specific Overrides¶

AGENTS.md                    ← Shared rules (build instructions, testing, coding conventions)
CLAUDE.md                    ← Claude-specific (thinking process instructions, MCP settings)
copilot-instructions.md      ← Copilot-specific (code completion style, review policies)

Pros	Cons
Tool-specific optimization possible	Multiple files need synchronization on updates
Maximizes each tool's strengths	Risk of information duplication
Easy incremental adoption	More files to manage

Common rules in AGENTS, differences in individual files

Recommendation

We recommend Approach 2 (shared base + tool-specific overrides). Write 80% of the common rules (build instructions, testing policies, coding conventions, security policies) in AGENTS.md, and keep only the differences in tool-specific files. It's helpful to explicitly note the references within AGENTS.md like this:

## Tool-Specific Files
- Claude Code: See `CLAUDE.md` (MCP settings, thinking process instructions)
- GitHub Copilot: See `.github/copilot-instructions.md` (completion style)

📝 How to Write AGENTS.md¶

Below is a template example assuming a TypeScript + React project.

# AGENTS.md

## Project Overview
A TypeScript + React web application. Backend uses Node.js + Express.

## Build & Run
```bash
npm install
npm run dev        # Start development server
npm run build      # Production build
npm run test       # Run tests

Code Style¶

TypeScript strict mode
ESLint + Prettier (config in .eslintrc.js)
Use functional components + hooks
Naming: camelCase (variables/functions), PascalCase (components/types)

Testing¶

Jest + React Testing Library
Test files go in __tests__/ directory
Coverage target: 80% or higher

PR Guidelines¶

1 PR = 1 feature or 1 bug fix
Title: conventional commits format (feat:, fix:, docs:, etc.)
All CI checks must pass before review

Security¶

Never commit .env files
API keys via environment variables

Always validate user input

### Writing Tips

!!! abstract "5 Principles for Writing an Effective AGENTS.md"
    1. **Be specific** — Instead of "write clean code," say "follow ESLint + Prettier settings"
    2. **Prioritize build instructions** — The first thing an agent needs is how to build and test
    3. **Explicitly state prohibitions** — Such as "don't commit .env" or "don't use `any`"
    4. **Show the directory structure** — Helps agents locate files
    5. **Keep it concise** — Recommended under 500 lines. Too long and it consumes the context window

## 🏢 Usage in Monorepos

For large monorepos, a hierarchical AGENTS.md layout is effective.

monorepo/ ├── AGENTS.md # Shared across all packages (language settings, CI, security) ├── packages/ │ ├── web/ │ │ └── AGENTS.md # Web frontend-specific (React, CSS policies) │ ├── api/ │ │ └── AGENTS.md # API server-specific (REST design, DB operations) │ └── shared/ │ └── AGENTS.md # Shared library-specific (public API design policies) └── infra/ └── AGENTS.md # Infrastructure-specific (Terraform, Docker)

### Priority Rules

| Priority | File Location | Description |
|----------|--------------|-------------|
| High | AGENTS.md in the same directory as the edited file | The closest file takes highest priority |
| Medium | AGENTS.md in parent directories | Applied in order from parent directories |
| Low | Root AGENTS.md | Always applied as project-wide rules |

!!! example "Real-World Example: OpenAI Repository"
    OpenAI's own repository contains **88 AGENTS.md files**. Project-wide policies are in the root, with module-specific instructions in each module directory. This serves as a practical reference for monorepo usage at scale.

## 📊 Comparing copilot-instructions.md / CLAUDE.md / AGENTS.md

Here is a comparison of the positioning and characteristics of these three files.

| Aspect | AGENTS.md | copilot-instructions.md | CLAUDE.md |
|--------|-----------|------------------------|-----------|
| **Governance** | Linux Foundation (AAIF) | GitHub / Microsoft | Anthropic |
| **Supported Tools** | 20+ tools | GitHub Copilot only | Claude Code only |
| **Format** | Free-form Markdown | Free-form Markdown | Free-form Markdown |
| **Loading Priority** | Depends on tool settings | Auto-loaded by Copilot | Auto-loaded by Claude Code |
| **Monorepo Support** | :white_check_mark: Nested support | :x: Root only | :white_check_mark: Nested support |
| **Purpose** | Project-wide agent instructions | Copilot-specific instructions | Claude-specific instructions |
| **Unique Features** | Cross-tool compatibility | Code Review integration | MCP settings, `/` commands |

!!! info "Relationship Between the Three Files"
    - **AGENTS.md**: Shared "project information" for all tools (build instructions, testing policies, coding conventions)
    - **copilot-instructions.md**: Copilot-specific "completion style and review policies"
    - **CLAUDE.md**: Claude Code-specific "thinking process, MCP settings, and skill definitions"

    These three are **complementary, not competing**. The best practice is to use AGENTS.md as the foundation and manage differences through tool-specific files.

## 🚀 Getting Started

=== "Before (Individual Management)"

    ```
    3 tools × separate config files = 310 lines total
    - copilot-instructions.md: 120 lines
    - CLAUDE.md: 110 lines
    - .cursorrules: 80 lines
    Rule duplication: ~80%
    ```

=== "After (Unified with AGENTS.md)"

    ```
    1 shared file + slim overrides = 120 lines total
    - AGENTS.md: 90 lines (shared rules)
    - CLAUDE.md: 15 lines (MCP-specific only)
    - copilot-instructions.md: 15 lines (completion-specific only)
    Rule duplication: 0%
    ```

??? tip "Quick Start (5 Minutes)"

    ```bash
    # 1. Create AGENTS.md at project root
    touch AGENTS.md

    # 2. Add VS Code settings
    cat << 'EOF' >> .vscode/settings.json
    {
      "chat.useAgentsMdFile": true,
      "chat.useNestedAgentsMdFiles": true
    }
    EOF

    # 3. Create symlinks (optional)
    ln -s AGENTS.md CLAUDE.md
    ln -s ../AGENTS.md .github/copilot-instructions.md

    # 4. Commit
    git add AGENTS.md .vscode/settings.json
    git commit -m "feat: add AGENTS.md for cross-tool AI agent management"
    ```

Here are the steps to introduce AGENTS.md into an existing project.

### Step 1: Create AGENTS.md

If you already have `copilot-instructions.md` or `CLAUDE.md`, start by extracting the **common information** (build instructions, testing policies, coding conventions) from them.

```bash
# Create at the project root
touch AGENTS.md
# Consolidate common parts into AGENTS.md, keeping only differences in tool-specific files

Step 2: Add VS Code Settings¶

// Add to .vscode/settings.json
{
  "chat.useAgentsMdFile": true
}

Step 3: Organize Existing Tool-Specific Files¶

# Keep only differences in tool-specific files (recommended)
# Or replace with symlinks for full unification
ln -s AGENTS.md CLAUDE.md
ln -s ../AGENTS.md .github/copilot-instructions.md

# Commit AGENTS.md to git
git add AGENTS.md .vscode/settings.json
git commit -m "feat: add AGENTS.md for cross-tool AI agent management"

Note: Check .gitignore

Make sure AGENTS.md is not included in your .gitignore. It's important that all team members can access the AGENTS.md file.

❓ Frequently Asked Questions (FAQ)¶

Q: Does AGENTS.md conflict with CLAUDE.md / copilot-instructions.md?

No, they don't conflict. AGENTS.md serves as shared "project information" for all tools, while tool-specific files provide "differences for that specific tool" — they are complementary. The recommended approach is to write common rules in AGENTS.md and tool-specific settings (MCP, Hooks, etc.) in the respective tool files.

Q: What is the recommended length for AGENTS.md?

We recommend keeping it under 500 lines. If it's too long, it consumes the context window and reduces the agent's response accuracy. An effective structure is to separate detailed procedures into Agent Skills and include only summaries and reference links in AGENTS.md.

Q: Should I use symlinks or separate files?

If more than 80% of the rules are shared across tools, use full unification (symlinks). If tool-specific syntax is needed, use a shared base plus separate files (coexisting approach). Also consider your team's infrastructure, as some CI environments don't support symlinks.

Multi-Agent Collaboration Guide →

After unified configuration, move on to practical multi-agent operations

Custom Instructions Complete Guide
Detailed writing practices and best practices for .github/copilot-instructions.md - applyTo Pattern Guide
Optimize instructions with file path-based conditional branching - Agent Skills Guide
SKILL.md format, Progressive Disclosure, and on-demand procedural knowledge activation - Multi-Agent Collaboration Guide
Development automation strategies combining GitHub Copilot and Claude Code