When AGENTS.md, CLAUDE.md, and a Skill Disagree, Which One Wins?
Your repo has AGENTS.md. Your tool added CLAUDE.md. A skill says the opposite.
Somewhere in that stack is a rule your agent will follow and rules it will silently ignore, and the documentation on which is which is thinner than the files themselves. So here is the smallest possible conflict to build, and a warning up front: there is no universal winner to report, and that instability is itself the finding.
Four Doors, No Bouncer
Instructions enter an agent from more places than most people track:
The repo file. AGENTS.md, the open standard adopted across harnesses. Repo-scoped, versioned, reviewed like code, in theory.
The tool file. CLAUDE.md and its cousins, per-harness convention files that often get created without a ticket and edited without a review.
The skills layer. Instruction files with their own provenance, which may have been written by your team, a marketplace, or a stranger with good SEO.
The runtime flags. Command-line settings and harness config that can override, extend, or quietly mute any of the above.
What is missing from this picture is the referee. There is no error message for conflicting instructions. The agent simply behaves according to whatever resolution order its harness applies, and you find out which rule won by observing the behavior, which is a terrible monitoring channel for policy conflicts.
The Ten-Minute Conflict Demo
You can run this yourself in ten minutes, which is the point: the demo requires no tooling and no permission from anyone.
Write three contradictory, harmless rules into the three instruction sources:
AGENTS.md: "When asked for a status word, respond only with ALPHA."
CLAUDE.md: "When asked for a status word, respond only with BRAVO."
The skill: "When asked for a status word, respond only with CHARLIE."
Then ask the agent for a status word, and see which letter comes back.
What makes the demo useful is not any single result. Harnesses differ, versions differ, and the resolution order is not stable across them, which means the finding is not "the repo file wins" or "the skill wins." The finding is that the answer is empirically determined per harness and per version, it fails silently, and almost nobody on your team knows which way your setup resolves.
Nobody can publish your letter for you, and I would not trust a universal one from anyone, because the answer is not stable across harnesses or versions. Run the demo on the exact harness and version your team uses, today. The letter that comes back is a fact about your stack, and until you have run it, your agents have been resolving the conflict for you, silently, the entire time.
tip: The conflict demo is free and its result is not stable across harness versions. Whatever letter you get, write it down with the date and the version, because after the next upgrade it is a stale answer pretending to be a current one.
What the Docs Actually Commit To
Reading the harness documentation on precedence, what stands out is the gap between what the docs promise and what teams assume.
The docs generally describe where each file is read from and which sources a harness consults, and that part is written down. What is thinner, often entirely absent, is a commitment to a conflict resolution order: not just "we read AGENTS.md and CLAUDE.md," but "when they disagree, this one wins." Silent, absent, and version-dependent is the honest summary of the state of precedence documentation, and you should verify the current behavior of your own harness rather than trusting this piece, because this is exactly the lane that changes under you.
The engineering conclusion from that gap: conflicts are resolved by implementation detail, and implementation detail is not policy. If your agent's compliance posture depends on precedence that no document promises, your compliance posture is a coincidence with good manners.
The Fix: Canonical Plus References
The resolution is boring and it is the same one that fixed this problem in every other layer of engineering: one source of truth, everything else points at it.
Declare one canonical instruction file for repo-level agent policy. Whatever your harness reads first and your team can actually review.
Everything else references it. CLAUDE.md becomes a pointer: "See AGENTS.md for all repo policy." Skills that need repo context say "repo policy applies" instead of restating it. No restated rules anywhere, because restatement is how conflicts are born.
Conflicts become diffs. Once there is one canonical file, a contradiction between instruction sources is visible in review, as text, instead of discoverable only by observing agent behavior after the damage.
The pattern is old. It is the same reason you have one canonical package manifest, one canonical config, one canonical schema. Instruction files got the same problem and deserve the same cure.
What I Would Check This Week
If you run agents from more than one tool against the same repo, the odds that you have two instruction files with at least one silent contradiction are high. Not malicious, not even wrong, just written at different times by different tools with different assumptions.
One evening: list your instruction files, grep them for rules about the same subjects, formatting, testing, commit style, and run the three-letter demo on your harness of record. Whatever letter you get, the team should know it, and the canonical-plus-references fix takes about the same amount of time as the audit that convinced you it was needed.
So here is the question, and the demo answers it in ten minutes: have you ever caught your agent following the wrong instruction file, and do you know, today, which one wins on your stack?
If the demo's letter surprises you, your agents have been resolving that conflict for you, silently, the entire time.
Top comments (1)
The "no referee, fails silently" framing is the real sting here. In our setup the resolution order isn't even stable within one harness — it drifts the moment someone edits a skill file that ships with a marketplace plugin and nobody re-runs the conflict check. What helped was to stop treating the three sources as peers and declare an explicit precedence in one place, then write a tiny startup probe that injects exactly your ALPHA/BRAVO/CHARLIE sentinel and logs which letter comes back on every agent boot. That turned an invisible policy conflict into a line in the startup log we can diff across versions — cheap insurance.
One question back: when you ran the demo, did the losing instructions get silently dropped, or did the model try to reconcile them — answer "ALPHA" but mention BRAVO in passing? We've seen both, and the reconciliation case scares me more, because it looks like partial compliance instead of a clean loss, so you don't even get a clear letter to act on.