AGENTS.md vs Copilot Instructions: The Enforcement Gap Nobody Talks About

GitHub Copilot reads AGENTS.md, but it doesn’t actually enforce it. That distinction is costing teams more than they realize.

Since August 2025, AGENTS.md has become the closest thing AI coding has to a universal standard—60,000+ repositories, 28+ tools, and backing from the Linux Foundation’s Agentic AI Foundation. But Copilot’s implementation is fundamentally different from how Claude Code handles its native CLAUDE.md. Where Claude treats its config as authoritative, Copilot treats AGENTS.md as what one observer called a “very strong system prompt”—suggestive context, not binding rules. If you’re relying on AGENTS.md for policy enforcement in Copilot, you’re building on sand.

How Copilot Actually Reads AGENTS.md

Copilot’s AGENTS.md support is real, but it’s fragmented across modes. Copilot Chat in VS Code and GitHub.com reads it from the repository root or docs/ directory. Copilot Workspace walks subdirectories and applies nearest-ancestor files. Copilot Edits applies it partially. Copilot CLI ignores it entirely.

This isn’t a bug—it’s a design philosophy. Copilot ingests AGENTS.md as context that influences its behavior, not as configuration that constrains it. The file sits at the top of Copilot’s context priority hierarchy—above .github/copilot-instructions.md, prompt files, open editor tabs, inline comments, and chat history. But priority doesn’t equal enforcement. A “very strong system prompt” can still be overridden by other signals, and there’s no mechanism to guarantee rule adherence.

For teams coming from Claude Code, this is a jarring shift. Claude’s CLAUDE.md supports hooks, permission controls, and glob-based scoping. Copilot’s AGENTS.md implementation has none of that. It lacks nested scoping, glob-based rules, hooks, and permission controls. What you write in AGENTS.md is advice, not architecture.

The Native Alternative: .github/copilot-instructions.md

Before AGENTS.md arrived, Copilot already had its own instruction mechanism. .github/copilot-instructions.md is Copilot’s primary project-level configuration file, applied to every chat request and inline suggestion. It works in modes where AGENTS.md is unsupported or only partially supported.

The two files serve overlapping but distinct roles. AGENTS.md is your cross-tool compatibility layer—read by Codex, Cursor, and others. copilot-instructions.md is your Copilot-native enforcement layer. For multi-agent repositories, the recommended pattern is to make AGENTS.md the shared policy file and use tool-specific adapters to prevent instruction drift.

Here’s the practical layout:

your-project/
├── AGENTS.md                    # Cross-tool shared policy
├── .github/
│   └── copilot-instructions.md  # Copilot-specific enforcement
├── CLAUDE.md                    # Claude-specific (if needed)
└── .cursor/
    └── rules/                   # Cursor-specific (if needed)

The average developer uses 2.3 AI coding tools, so this isn’t theoretical overhead—it’s the reality of modern development. The question is whether you’re managing that complexity intentionally or letting it drift.

The Cost Dimension: Why Context Files Just Got Expensive

Here’s where the analysis gets uncomfortable. Starting June 1, 2026, GitHub Copilot moved to usage-based billing with GitHub AI Credits. Base plan prices stayed flat—Pro at $10/month, Business at $19/user/month, Enterprise at $39/user/month. But code completions and Next Edit Suggestions remain the only unlimited features. Everything else—Chat, CLI, the cloud coding agent, Spaces, third-party agents—draws from a credit pool that does not roll over month to month.

The math turns ugly fast. Agentic coding sessions cost an estimated $30-$40 each. A Copilot Pro user with $10 in monthly credits exhausts their allotment in a single working session. The very workflows that most benefit from consistent, well-structured instructions are now the most economically precarious.

This creates a perverse incentive. You need AGENTS.md and copilot-instructions.md to make agentic sessions productive—without them, you’re paying for generic, inconsistent output. But every token of context you add increases the cost of every session. Verbose instructions aren’t just a maintenance burden anymore; they’re a direct line item.

What the Research Actually Says About Context Files

The industry’s assumption—that more context is better—doesn’t hold up under scrutiny. ETH Zurich research on the AGENTbench dataset found that LLM-generated context files reduce task success rates by 3% and increase inference costs by over 20% compared to no context file at all. Human-written files fared marginally better: a 4% success rate improvement, but at up to 19% higher cost.

These aren’t dramatic numbers until you scale them. Across a team of ten developers running multiple sessions daily, that’s real money. More critically, the research suggests that much of what teams put in context files is either already inferable by the model or actively counterproductive. The industry’s rush to auto-generate repository context—LLM-written AGENTS.md files, sprawling policy documents—isn’t just neutral; it’s degrading performance while inflating bills.

This aligns with what I’ve observed in practice. The most effective AGENTS.md files I’ve seen are ruthlessly minimal: exact build commands, forbidden patterns, and verification steps. They’re operational policy, not documentation. Anything that reads like a README for humans is probably wasting tokens and diluting enforcement.

Feature Comparison: AGENTS.md vs. Copilot’s Native Stack

Dimension	AGENTS.md	.github/copilot-instructions.md	Custom Agents (.agent.md)	Skills (.skills/)
Scope	Cross-tool standard	Repository-wide Copilot	Specialized personas	Reusable workflows
Enforcement	Soft (context hint)	Soft (context hint)	Medium (tool-bound)	Medium (on-demand)
Copilot Chat	Full read	Full apply	N/A	N/A
Copilot Edits	Partial	Full apply	N/A	N/A
Copilot CLI	Ignored	Full apply	N/A	N/A
Subdirectory scoping	Yes (Workspace only)	No	No	No
Hooks/permissions	No	No	No	No
Best for	Shared baseline	Copilot-specific rules	Role-based tasks	Multi-step procedures

Copilot also supports custom agents and skills as extensibility mechanisms, but these are orthogonal to the instruction file question. Agents give you specialized personas with tool access; skills give you reusable instruction sets. Neither solves the core problem: Copilot’s instruction architecture lacks hard enforcement, and AGENTS.md inherits that limitation while adding cross-tool portability.

A Practical Decision Framework

So what should you actually do? The answer depends on your team’s constraints more than any universal best practice.

If you’re Copilot-only: Use .github/copilot-instructions.md as your primary instruction file. It’s the only format that works across all Copilot modes, including CLI. Keep AGENTS.md minimal or omit it unless you need cross-tool compatibility for future migration.

If you’re multi-tool today: Make AGENTS.md your shared policy file, but treat it as a compatibility shim, not a policy layer. Route enforcement-critical rules through tool-specific files. For a deeper walkthrough of this layered architecture, see our guide on how to write AGENTS.md files that work across Cursor, Copilot, and Codex.

If you’re cost-constrained under usage-based billing: Ruthlessly minimize context. Every token matters. Focus AGENTS.md on non-inferable details—exact build commands, custom tooling, forbidden patterns. Move explanatory prose to documentation that humans read, not agents. The comparison of AGENTS.md and Cursor’s proprietary .cursor/rules format breaks down how instruction budget impacts differ across tools.

If you need policy enforcement: Look beyond instruction files entirely. Copilot’s hooks (in preview) and custom agents with restricted tool access are closer to real enforcement than anything in .md format. But recognize that you’re working around a platform limitation, not using a platform feature.

The Harder Question

The deeper tension here is between portability and power. AGENTS.md’s whole value proposition is cross-tool compatibility—write once, run anywhere. But the tools it targets have divergent capabilities. Claude Code’s CLAUDE.md supports hooks and permissions that AGENTS.md can’t express. Copilot’s native stack has its own extensibility model that AGENTS.md doesn’t map to. The standard’s minimalism is its strength and its ceiling.

Meanwhile, GitHub Copilot code review added AGENTS.md support on June 18, 2026, applying relevant instructions when generating review feedback. This expands the surface where AGENTS.md matters, but doesn’t change its fundamental character as suggestive rather than binding context.

The honest assessment: AGENTS.md is a coordination tool for multi-tool teams, not an enforcement mechanism for any single tool. If you’re treating it as the latter, you’re misunderstanding what it can do—and potentially paying a premium for the confusion. The teams that navigate this well will be the ones that match their instruction architecture to their actual tool mix and cost constraints, rather than defaulting to the most “standard” option available.

What’s your current split between AGENTS.md and tool-native instruction files? Are you seeing cost surprises under the new billing model that are changing how you think about context?