Need a standardized way to show different AGENTS.md files and/or content to different agents

[ariccio]

Now that the industry has (reasonably) standardized on AGENTS.md, some mainstream agentic toolchains are dropping support for dedicated configs (e.g. openai/codex#16100 - cc @etraut-openai ).

Sadly though, this removes the obvious and easy way to compose different instructions across agents: an AGENTS.md can compose nicely with a CODEX.md and a copilot-instructions.md.

There's no other place to put RFCs or submit other requests about the AGENTS.md standard, so I figured this is the correct place.

There are many different possible solutions. One option would be to have a naming scheme like AGENTS.[agent-name].md that gets appended in context to the AGENTS.md only for [agent-name], (e.g. AGENTS.CODEX.md).

I'm certain I'm not the only one dealing with this - it happens as soon as you start running multiple agents in your codebase and actually start trying to manage their differing good and bad behaviors.

[saero-robertpaul]

The AGENTS..md overlay idea is interesting because it pushes the per-agent variance question into filenames rather than file content, which keeps tools that don’t understand the suffix happy. The wrinkle I keep hitting in practice is that some differences aren’t just instruction text — they’re whole resource kinds (a Cursor rule with globs, a Claude skill with frontmatter, a Copilot applyTo) that don’t map 1:1. I have been compiling those from a single source per-provider with xcaffold (https://github.com/saero-ai/xcaffold), and if the spec went this direction, codifying which fields are agent-scoped vs shared would help downstream compilers a lot.

Happy to share the fidelity-loss patterns we’ve seen across providers if useful for the RFC.

[caioribeiroclw-pixel]

This is the exact place where the recent AGENTS.md evaluation changes the design bar, IMO: overlays should not just solve where do agent-specific bytes live?; they should also make it possible to prove which bytes were worth loading.

The paper Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? is relevant here: human-written context files helped a bit on average, but both human and generated files increased reasoning tokens by ~14–22% and added 2–4 extra steps; LLM-generated broad repo overviews were often net negative. Paper: https://arxiv.org/abs/2602.11988

So for AGENTS.<agent>.md / overlays, I would want the spec to distinguish three things explicitly:

1. shared invariant guidance — constraints every agent should see (use uv, security rules, test command, architecture invariants)
2. agent-specific compensation — instructions that exist only because a target has a known behavior gap/loss (Codex needs X, Cursor rule globs represent Y, Claude skill frontmatter represents Z)
3. redundant overview — repo maps / directory summaries that agents can rediscover and that may add cost without improving task success

A small frontmatter shape could make this inspectable without forcing one implementation:

scope: shared | agent-specific
appliesTo: [codex, cursor, claude-code]
whyLoaded: invariant | target-compensation | workflow | temporary-workaround
expectedBenefit: required-command | safety-constraint | path-scope | activation-semantics
knownLossyTargets: [copilot]
expiresWhen: optional issue/url/date

The important bit is whyLoaded. Without it, AGENTS.CODEX.md can become a dumping ground for more instructions and reproduce the paper's failure mode: agents faithfully follow extra text, spend more tokens, and still do not find the relevant files faster.

This also connects to @saero-robertpaul's point: some differences are not text differences, they are resource-kind / activation / path-scope differences. Those should probably be recorded as target compensation, not hidden as generic guidance.

A useful acceptance test for the RFC might be: for a repo with AGENTS.md + AGENTS.CODEX.md + Cursor/Copilot/Claude equivalents, can a tool emit a receipt saying which guidance was loaded for each target, why it was loaded, what semantics were lost, and whether it is still needed?

[caioribeiroclw-pixel]

One useful constraint for any AGENTS.<agent>.md shape: the naming scheme should probably define enough composition semantics that users can audit what actually loaded, not just guess from filenames.

The minimum I would want to see in an implementation/test fixture is:

• base file loaded: e.g. AGENTS.md
• target overlay loaded: e.g. AGENTS.cursor.md
• non-target overlays suppressed: e.g. AGENTS.codex.md during a Cursor session
• explicit load order: base first, overlay second
• fallback behavior: what happens when an overlay is missing
• target-agent applicability: which agent the overlay applies to
• no raw instruction text required in logs/telemetry, only paths/hashes/counts/policy

I tested that shape as a small receipt fixture here, if useful as prior art for evaluating proposals:
https://github.com/caioribeiroclw-pixel/pluribus/blob/main/examples/context-input-evidence/agent-overlay-otel-trace.json

The important bit is less the exact field names and more the invariant: if a standard permits overlays, it should make the selected base+overlay pair and suppressed candidates inspectable. Otherwise AGENTS.cursor.md vs AGENTS.codex.md becomes another convention that works until a tool silently loads the wrong mix.

[ariccio]

@caioribeiroclw-pixel the real question I'd have to ask first would be, is it helpful to expand the scope of the proposed change before knowing if it's useful? Additional front matter feels to me like it would be more brittle, especially given the number of closed source harnesses out there with consistently out-of-sync documentation and bad QA.

It would also increase the chance of specifying for a broad set of use cases that still don't match the needs of all users.

IMO it's not necessarily useful for a spec to decide it's not worth supporting an AGENTS.CODEX.md to protect me from creating a bad AGENTS.CODEX.md of my own, especially when I know I'm already harming my agents by giving one a set of instructions that's intended to only apply to a different harness. It's the other behavior that I would need standardized, and we'd all benefit from.

[caioribeiroclw-pixel]

That pushback is right. I overreached with the frontmatter/classification part.

The useful thing to standardize is the behavior, not a policy layer that tries to protect users from writing bad target-specific guidance. A narrower contract seems better:

• discover candidate files
• load AGENTS.md as the base
• load the one overlay that matches the current harness
• explicitly not load other harness overlays
• define load order and fallback when the overlay is missing

That gives users the thing they actually need: AGENTS.CODEX.md should not accidentally get fed to Cursor/Claude/etc. Anything about whyLoaded, lossy targets, expected benefit, etc. can be external observer metadata, not part of the core naming spec.

I updated my notes/fixture framing to reflect that reduction: caioribeiroclw-pixel/pluribus@5493288

So my vote here would be: keep the RFC small and behavioral. If a receipt/audit format exists, it should prove selected/suppressed base+overlay composition after the fact, not force the standard to become a taxonomy of all provider differences.