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.

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.

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.

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