AGENTS.md and GitHub Copilot: How Copilot Reads It, What It Ignores, and How to Make It Work (2026)

AGENTS.md has landed in GitHub Copilot — but not quite in the way you might expect. Copilot does not read AGENTS.md the same way Claude Code does, and if you set up a single AGENTS.md expecting Copilot and Claude to behave identically, you will get inconsistent results. This guide explains the actual mechanics, the gaps, and how to configure both tools so your rules land correctly.

Does GitHub Copilot Actually Read AGENTS.md?

Yes, but with conditions. GitHub Copilot added AGENTS.md support as part of its broader push toward Copilot’s agentic features in 2025. In Copilot Chat (both VS Code extension and GitHub.com), Copilot reads AGENTS.md when it is in the repository root or in a recognized subdirectory.

However, the support is not uniform across Copilot’s modes:

The key distinction: Copilot’s support is read-and-apply, not strict enforcement. It ingests the file as context, but it does not guarantee that every rule in AGENTS.md is followed as literally as Claude Code follows CLAUDE.md. Claude Code treats CLAUDE.md as authoritative configuration; Copilot treats AGENTS.md more like a very strong system prompt.

How Copilot Discovers AGENTS.md

Copilot follows a simplified discovery process compared to Claude Code or OpenAI Codex:

1. Repository root — /AGENTS.md is always checked first
2. Docs directory — /docs/AGENTS.md is checked as a fallback
3. Subdirectory files — In Copilot Workspace, Copilot walks subdirectories and applies nearest-ancestor AGENTS.md to tasks in that directory

It does not read ~/.copilot/AGENTS.md or user-level global files the way Codex reads ~/.codex/AGENTS.md. Copilot’s equivalent for user-level persistent instructions is its custom instructions feature, which works differently.

Copilot Custom Instructions vs AGENTS.md

Before AGENTS.md support landed, Copilot already had its own instructions mechanism: custom instructions files at .github/copilot-instructions.md. This is still the primary way to configure Copilot’s behavior, and it works everywhere AGENTS.md does not. For the AGENTS.md spec itself and how other tools like OpenAI Codex consume it, see AGENTS.md for Codex: Complete Setup Guide.

project-root/
├── AGENTS.md                          # Multi-tool standard (Codex, Cursor, etc.)
├── .github/
│   └── copilot-instructions.md        # Copilot-specific config
└── CLAUDE.md                          # Claude Code config

The critical difference in scope:

.github/copilot-instructions.md

• Copilot-specific and always read in Copilot Chat
• Applies to all sessions, all files, all modes
• No filesystem hierarchy — one file, global to the repo
• Supports Copilot-specific directives like topic filtering

AGENTS.md

• Multi-tool standard, read by Copilot but also Codex, Cursor, etc.
• Hierarchy-aware in Copilot Workspace
• Does not support Copilot-specific features

In practice: if Copilot is your primary tool, .github/copilot-instructions.md gives you more reliable coverage. AGENTS.md is the right choice if you want rules that travel across tools and you accept that Copilot’s adherence will be less strict than Codex’s.

What Copilot Actually Does With AGENTS.md

When Copilot reads AGENTS.md, it incorporates the content as high-priority context. Sections that work reliably:

Commands and setup instructions Copilot correctly picks up ## Commands sections and uses them when generating scripts or suggesting terminal commands. If you document pnpm test instead of npm test, Copilot will use the right package manager.

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test --run
- Lint: pnpm lint && pnpm tsc --noEmit

Coding conventions Style rules land well. Language-level conventions (TypeScript strict mode, naming patterns, preferred abstractions) are applied consistently.

## Code Style
- TypeScript: strict mode, no `any`, prefer `unknown` for external data
- React: server components by default, `'use client'` only for interactivity
- CSS: Tailwind utility classes; no inline styles except dynamic values
- Imports: absolute paths via `@/` alias, not relative for cross-module imports

Boundary rules “Never modify X” and “do not add Y” instructions work, but Copilot is more likely to suggest something and let you accept/reject rather than refusing to generate it outright.

Sections that work less reliably:

• Subdirectory-specific rules (Copilot flattens hierarchy in most modes)
• Long AGENTS.md files — instructions past ~2,000 tokens get lower attention weight
• Conditional logic (“if the PR touches auth/, then…”)

AGENTS.md vs CLAUDE.md for Copilot Users

If you use both Copilot and Claude Code on the same project, you are now managing three instruction files. That sounds like overhead, but there is a clean separation pattern that works well:

project-root/
├── AGENTS.md                          # Cross-tool foundation (commands, architecture, non-negotiables)
├── .github/
│   └── copilot-instructions.md        # Copilot-specific behavior and topic guidance
└── CLAUDE.md                          # Claude Code config — can @import from AGENTS.md

What goes in AGENTS.md (shared foundation):

• Project architecture overview
• Build and test commands
• Hard constraints (“never modify migrations/ without approval”)
• Technology stack and versions
• Directory structure explanation

What goes in .github/copilot-instructions.md (Copilot-specific):

• Response style preferences for Copilot Chat
• Topic focus (“focus on TypeScript, not Python equivalents”)
• Code review behavior
• Copilot-specific no-go zones

What goes in CLAUDE.md (Claude-specific):

• Claude Code hooks and permissions
• Sub-agent delegation patterns
• Complex multi-step workflow instructions
• @import references that pull in AGENTS.md content

Avoiding Rule Conflicts

The most common problem in mixed-tool setups is contradictory rules. Claude sees one thing, Copilot sees another, and both give you subtly different outputs for the same task.

A clean solution: make CLAUDE.md a superset of AGENTS.md using imports.

# CLAUDE.md

@import AGENTS.md

## Claude Code-Specific

### Hooks
PostToolUse: npm run lint -- {path}
Stop: node scripts/verify-build.js

### Permissions
- Bash: allow
- Write: ask for files outside src/

With this pattern, AGENTS.md is the single source of truth for shared rules. CLAUDE.md extends it with Claude-specific behavior. Copilot reads AGENTS.md directly. No duplication, no drift.

Setting Up AGENTS.md for Copilot Workspace

Copilot Workspace — GitHub’s task-based agentic environment — has the richest AGENTS.md support. Here is a setup that uses the hierarchy effectively:

project-root/
├── AGENTS.md                   # Global project instructions
├── src/
│   ├── AGENTS.md               # Frontend-specific rules
│   └── api/
│       └── AGENTS.md           # API layer rules (authentication, rate limiting, etc.)
└── tests/
    └── AGENTS.md               # Test writing conventions

Root AGENTS.md:

# AGENTS.md

## Project
E-commerce API and frontend. Node.js 22 + Next.js 15 + PostgreSQL 16.

## Architecture
- `/src/api/` — Express REST API, no GraphQL
- `/src/app/` — Next.js App Router frontend
- `/tests/` — Vitest for unit, Playwright for E2E

## Global Rules
- Never commit secrets or API keys
- All PRs require passing tests before merge
- Migrations in `/migrations/` need explicit approval before running

## Commands
- `pnpm install` — install dependencies
- `pnpm dev` — start both API and frontend in dev mode
- `pnpm test` — run all tests
- `pnpm build` — production build

src/api/AGENTS.md:

# API Layer Instructions

## Authentication
- All endpoints except `/auth/*` require JWT validation via `requireAuth` middleware
- Never hardcode token secrets — use `process.env.JWT_SECRET`
- Refresh token rotation is enabled; maintain the rotation logic in `auth/refresh.ts`

## Error Handling
- Return RFC 7807 problem+json format for all errors
- Log with correlation IDs from `req.correlationId`
- Never leak stack traces to clients in production

In Copilot Workspace, when you create a task that touches src/api/, Copilot picks up both the root AGENTS.md and src/api/AGENTS.md. It applies both, with the subdirectory file taking precedence on conflicts.

Measuring What Copilot Actually Uses

The practical challenge with Copilot is that you cannot inspect what context it loaded for a given session the way you can with Claude Code (where you can explicitly ask “what does your CLAUDE.md say about X?”).

The workaround: after setting up or updating AGENTS.md, open Copilot Chat and ask it directly:

What are the main conventions and constraints defined for this project?

Copilot will enumerate what it absorbed from AGENTS.md. This is your QA check. If it misses something critical, either move that rule earlier in the file (Copilot weights earlier content higher) or add it to .github/copilot-instructions.md for guaranteed coverage.

Real measurement from a production TypeScript/Next.js project: a 680-token AGENTS.md covering architecture, commands, and TypeScript conventions was fully absorbed and correctly applied. A 2,800-token AGENTS.md covering the same plus detailed explanations and rationale had roughly 60–70% adherence on convention rules — the explanatory text diluted the instruction signal. The fix: trim rationale from AGENTS.md, put it in a separate CONTRIBUTING.md that humans read. The same token discipline applies to CLAUDE.md — our CLAUDE.md token optimization guide covers the techniques in depth.

Quick Reference: Copilot + AGENTS.md Decision Guide

AGENTS.md gives you portability. .github/copilot-instructions.md gives you reliability within Copilot. The right answer for most teams is both, with a clear layer separation.

2026 Q2 Update: What Changed Since This Article First Published

A few notable shifts since publication in April 2026:

Copilot Coding Agent reached general availability. The agentic background-execution feature (formerly preview) is now GA. Coding Agent reads AGENTS.md from the repository root and applies it across multi-file refactors. Practical implication: AGENTS.md is now load-bearing not just for inline / Workspace suggestions but for autonomous task execution. This raises the cost of a misconfigured AGENTS.md.

The Agentic AI Foundation took stewardship of the AGENTS.md spec. OpenAI pushed AGENTS.md initially for Codex, but the spec is now hosted by the Agentic AI Foundation (a directed fund under the Linux Foundation). GitHub Copilot, Cursor, Cline, Windsurf, and Codex CLI all align on the same format with no single vendor controlling its evolution. Rule files written today have longer durability across vendors.

Copilot CLI still does not read AGENTS.md. Copilot CLI (the terminal companion) uses .agent.md custom agent files instead. This is unchanged in 2026 Q2. If your team uses Copilot CLI heavily, you need a parallel .agent.md strategy alongside any AGENTS.md.

Per-path instruction files in .github/instructions/ matured. GitHub Copilot now supports .github/instructions/*.instructions.md files with frontmatter targeting specific paths (e.g., applyTo: "src/api/**"). This is Copilot’s answer to per-directory AGENTS.md and works alongside (not in place of) AGENTS.md. For projects with complex monorepo structure, this pattern gives more reliable scoping than AGENTS.md hierarchies.

Token budget measurements now reproducible. The 680-token sweet spot mentioned earlier in this article has held up across more production projects. New finding: splitting a long AGENTS.md into a small root file (commands, hard constraints) plus per-path .github/instructions/*.instructions.md files outperforms a single 2,800-token AGENTS.md for both Copilot and Coding Agent.

Frequently Asked Questions

Does GitHub Copilot natively read AGENTS.md files?

Not directly. GitHub Copilot reads its own configuration files — primarily .github/copilot-instructions.md at the repository root, plus per-language and per-path instruction files. AGENTS.md is read by Copilot Workspace (the agentic mode) but not by inline Copilot suggestions. The practical pattern is to maintain both: AGENTS.md as the cross-tool shared baseline, and .github/copilot-instructions.md as the Copilot-specific overlay.

Should I use AGENTS.md or .github/copilot-instructions.md?

If your team uses only Copilot, prefer .github/copilot-instructions.md — it has stronger adherence within Copilot. If you use Copilot alongside Claude Code, Cursor, or Codex, use AGENTS.md as the shared foundation and add a thin .github/copilot-instructions.md for Copilot-specific overrides. The two files can reference shared content via include patterns.

Where does Copilot Workspace look for AGENTS.md?

Copilot Workspace walks the directory tree from the file being edited up to the repository root, reading every AGENTS.md it encounters along the way. The closest file wins on conflicts. This matches the discovery model used by OpenAI Codex CLI and other Agentic AI Foundation–compliant tools.

What’s the optimal AGENTS.md size for Copilot?

Production measurements show ~680 tokens is the sweet spot for full instruction adherence. At ~2,800 tokens, adherence drops to 60–70% as explanatory text dilutes the instruction signal. Move rationale to CONTRIBUTING.md (for humans) and keep AGENTS.md focused on actionable rules.

Can I have different AGENTS.md per directory?

Yes — both Copilot Workspace and Codex CLI support per-directory AGENTS.md files. Place a project-wide file at the repo root and add directory-specific files inside subdirectories (e.g., apps/web/AGENTS.md, apps/api/AGENTS.md). The closest file wins on conflicts, allowing monorepos to scope instructions cleanly.

Does AGENTS.md affect Copilot inline suggestions?

Not directly. Inline Copilot suggestions read .github/copilot-instructions.md and per-language settings. AGENTS.md primarily affects Copilot Workspace (agentic tasks) and cross-tool consistency. For inline suggestions, mirror critical rules into .github/copilot-instructions.md.

Does Copilot Coding Agent read AGENTS.md?

Yes. Copilot Coding Agent (the GA autonomous background coding feature as of 2026 Q2) reads AGENTS.md from the repository root. Because Coding Agent executes multi-file changes without inline review, AGENTS.md is more load-bearing here than in inline suggestions. Misconfigured AGENTS.md causes Coding Agent to ship incorrect changes — keep your AGENTS.md authoritative and current if you use Coding Agent on production repos.

Does Copilot CLI read AGENTS.md?

No. Copilot CLI (the terminal companion) uses its own .agent.md custom agent file format, not AGENTS.md. If your team standardizes on Copilot CLI alongside Copilot Workspace, you need a parallel .agent.md strategy. For cross-tool consistency, Claude Code CLI and Codex CLI both read AGENTS.md — only Copilot CLI is the outlier on this point.

Who maintains the AGENTS.md spec now?

The spec was originally pushed by OpenAI for Codex but is now hosted by the Agentic AI Foundation (a directed fund under the Linux Foundation). GitHub Copilot, Codex CLI, Cursor, Cline, and Windsurf all align on the same format with neutral multi-vendor stewardship. Technical spec — frontmatter conventions, discovery hierarchy, override mechanism — is unchanged.

How do .github/instructions/*.instructions.md files compare to AGENTS.md?

.github/instructions/*.instructions.md is GitHub Copilot’s per-path instruction system (with applyTo: frontmatter targeting). It works alongside AGENTS.md, not in place of it. For complex monorepo scoping, .github/instructions/ gives more reliable rule application than AGENTS.md hierarchies because Copilot’s path-matching is deterministic. Use AGENTS.md for portable cross-tool rules, .github/instructions/ for Copilot-specific precision.

Related Articles

• AGENTS.md vs CLAUDE.md: What’s the Difference and When to Use Each
• AGENTS.md for OpenAI Codex: Complete Setup and Configuration Guide
• Writing Effective CLAUDE.md: The Complete Guide
• AGENTS.md Best Practices: Structure, Scope, and Real Examples
• CLAUDE.md Token Optimization 2026
• AGENTS.md vs Cursor Project Rules
• Caveman.MD: The Complete 2026 Guide to AGENTS.md Token Compression
• Claude Code Plugins: The Complete 2026 Reference
• 15 Best Claude Code Skills You Should Install in 2026