Make agents-md-revise respect first-match-wins rules loading

The skill told the model to "edit whichever rules file the project already
uses." Under OpenCode's first-match-wins resolution, a CLAUDE.md co-located
with an AGENTS.md is never read, so learnings captured there would be silently
lost. The skill now describes first-match-wins and directs capture to
AGENTS.md when both exist (never the shadowed CLAUDE.md), reinforced in the
"where each addition belongs" step. A test guards it; command kept in sync.
This commit is contained in:
Wayner Barrios
2026-05-27 22:53:03 -04:00
parent e0d54b1bd9
commit a2b5459e35
3 changed files with 30 additions and 2 deletions
+3 -1
View File
@@ -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
+3 -1
View File
@@ -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
+24
View File
@@ -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);
});