diff --git a/commands/agents-md-revise.md b/commands/agents-md-revise.md
index af9c5b2..5e55c4d 100644
--- a/commands/agents-md-revise.md
+++ b/commands/agents-md-revise.md
@@ -6,7 +6,7 @@ description: Capture learnings from the current session into the project-rules f
 
 Review the current session for learnings about working in this codebase, then update the project-rules file with context that would help future sessions be more effective.
 
-OpenCode reads project rules from `AGENTS.md` (native) or `CLAUDE.md` (Claude Code compatibility). When this skill creates a new file, prefer `AGENTS.md`. When updating an existing file, edit whichever the project already uses.
+OpenCode resolves project rules first-match-wins per directory: if a directory holds both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is loaded and the `CLAUDE.md` is never read. When capturing learnings, prefer `AGENTS.md` for a new file; if both already exist in the same directory, write to `AGENTS.md` — never into the shadowed `CLAUDE.md`, or the notes land in a file OpenCode ignores. If only `CLAUDE.md` exists, update it in place (and consider migrating it to `AGENTS.md`).
 
 ## Step 1 — Reflect
 
@@ -38,6 +38,8 @@ Decide where each addition belongs:
 - **`AGENTS.md` / `CLAUDE.md`** — team-shared, committed to git. Use for project-wide conventions, build commands, architectural notes.
 - **`.agents.local.md` / `.claude.local.md`** — personal / local only, gitignored. Use for personal preferences that should not affect teammates.
 
+If both `AGENTS.md` and `CLAUDE.md` exist in the same directory, target `AGENTS.md` — OpenCode ignores the co-located `CLAUDE.md`, so anything written there is lost.
+
 If no rules file exists yet, propose creating `AGENTS.md` at the project root.
 
 ## Step 3 — Draft additions
diff --git a/skills/agents-md-revise/SKILL.md b/skills/agents-md-revise/SKILL.md
index 1ad8a09..7721aab 100644
--- a/skills/agents-md-revise/SKILL.md
+++ b/skills/agents-md-revise/SKILL.md
@@ -8,7 +8,7 @@ license: MIT (translated from anthropics/claude-plugins-official/plugins/claude-
 
 Review the current session for learnings about working in this codebase, then update the project-rules file with context that would help future sessions be more effective.
 
-OpenCode reads project rules from `AGENTS.md` (native) or `CLAUDE.md` (Claude Code compatibility). When this skill creates a new file, prefer `AGENTS.md`. When updating an existing file, edit whichever the project already uses.
+OpenCode resolves project rules first-match-wins per directory: if a directory holds both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is loaded and the `CLAUDE.md` is never read. When capturing learnings, prefer `AGENTS.md` for a new file; if both already exist in the same directory, write to `AGENTS.md` — never into the shadowed `CLAUDE.md`, or the notes land in a file OpenCode ignores. If only `CLAUDE.md` exists, update it in place (and consider migrating it to `AGENTS.md`).
 
 ## Step 1 — Reflect
 
@@ -40,6 +40,8 @@ Decide where each addition belongs:
 - **`AGENTS.md` / `CLAUDE.md`** — team-shared, committed to git. Use for project-wide conventions, build commands, architectural notes.
 - **`.agents.local.md` / `.claude.local.md`** — personal / local only, gitignored. Use for personal preferences that should not affect teammates.
 
+If both `AGENTS.md` and `CLAUDE.md` exist in the same directory, target `AGENTS.md` — OpenCode ignores the co-located `CLAUDE.md`, so anything written there is lost.
+
 If no rules file exists yet, propose creating `AGENTS.md` at the project root.
 
 ## Step 3 — Draft additions
diff --git a/tests/agents-md-revise.test.mjs b/tests/agents-md-revise.test.mjs
new file mode 100644
index 0000000..854ba1e
--- /dev/null
+++ b/tests/agents-md-revise.test.mjs
@@ -0,0 +1,24 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const REPO = process.env.REPO || process.cwd();
+const skill = readFileSync(join(REPO, "skills/agents-md-revise/SKILL.md"), "utf8");
+const command = readFileSync(join(REPO, "commands/agents-md-revise.md"), "utf8");
+
+// Content-regression guards for the first-match-wins / shadowed-CLAUDE.md fix.
+
+test("agents-md-revise: describes first-match-wins rules loading", () => {
+  assert.match(skill, /first-match-wins/i);
+});
+
+test("agents-md-revise: warns against writing to a shadowed CLAUDE.md", () => {
+  assert.match(skill, /shadow|never read|ignore/i);
+  assert.match(skill, /CLAUDE\.md/);
+});
+
+test("agents-md-revise: command stays in sync with the skill", () => {
+  assert.match(command, /first-match-wins/i);
+  assert.match(command, /shadow|ignore/i);
+});