chore: Remove CLAUDE.md symlink

README.md

@@ -41,7 +41,7 @@ Works with Claude Code, Cursor, Cline, GitHub Copilot, and other compatible agen
 
 | Skill | Description |
 |-------|-------------|
-| [agents-md](skills/agents-md/SKILL.md) | Create and maintain concise, reference-backed AGENTS.md and CLAUDE.md files. |
+| [agents-md](skills/agents-md/SKILL.md) | Create and maintain concise, reference-backed AGENTS.md files. |
 | [blog-writing-guide](skills/blog-writing-guide/SKILL.md) | Write, review, and improve blog posts for the Sentry engineering blog following Sentry's specific writing standards, voice, and quality bar. |
 | [brand-guidelines](skills/brand-guidelines/SKILL.md) | Write copy following Sentry brand guidelines. |
 | [claude-settings-audit](skills/claude-settings-audit/SKILL.md) | Analyze a repository to generate recommended Claude Code settings.json permissions. |
@@ -106,7 +106,6 @@ sentry-skills/
 │   └── commit/
 │       └── SKILL.md
 ├── AGENTS.md                 # Agent-facing documentation
-├── CLAUDE.md                 # Symlink to AGENTS.md
 └── README.md                 # This file
 ```
 

skills/agents-md/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agents-md
-description: Creates and maintains concise AGENTS.md and CLAUDE.md project instruction files. Use when asked to create AGENTS.md, update AGENTS.md, maintain agent docs, set up CLAUDE.md, document repository agent conventions, or keep coding-agent instructions minimal and reference-backed.
+description: Creates and maintains concise AGENTS.md project instruction files. Use when asked to create AGENTS.md, update AGENTS.md, maintain agent docs, set up CLAUDE.md, document repository agent conventions, or keep coding-agent instructions minimal and reference-backed.
 ---
 
 # Maintaining AGENTS.md
@@ -24,8 +24,9 @@ Goal: concise, actionable agent instructions. Target under 60 lines; never excee
 ## File Setup
 
 - Create `AGENTS.md` at the repository root.
-- If a Claude-compatible entrypoint is required, symlink `CLAUDE.md` to `AGENTS.md`.
-- Do not maintain divergent `AGENTS.md` and `CLAUDE.md` copies.
+- Do not create `CLAUDE.md`; Claude Code reads `AGENTS.md` when no `CLAUDE.md` exists.
+- Remove a `CLAUDE.md` symlink to `AGENTS.md`.
+- If a real `CLAUDE.md` exists, move its instructions into `AGENTS.md` and delete it; Claude Code ignores `AGENTS.md` while `CLAUDE.md` exists.
 
 ## Default Sections
 

skills/agents-md/SOURCES.md

@@ -18,6 +18,7 @@ Why: this skill is a repeatable authoring workflow with pre-inspection, scoped o
 | `skills/skill-writer/SKILL.md` and references | local canonical | canonical | 2026-05-04 | high | Skill update workflow, source capture, authoring, validation | local repository authority | Primary authoring workflow |
 | `https://agents.md/` | official format guide | canonical | 2026-05-04 | high | AGENTS.md purpose, common sections, nested files, closest-file precedence | public format guidance | Supports path-backed and scoped instructions |
 | `https://developers.openai.com/codex/guides/agents-md` | official product docs | canonical | 2026-05-04 | high | Codex discovery order, global/project scopes, nested precedence, size cap, verification commands | OpenAI-specific behavior | Used only for compatibility guidance |
+| `https://github.com/anthropics/claude-code/tree/main/mods/agents-md` | official product docs | canonical | 2026-09-21 | high | Claude Code loads `AGENTS.md` by default when no `CLAUDE.md` exists on the path | Claude Code-specific behavior | Replaces the `CLAUDE.md` symlink convention |
 | `https://agentskills.io/specification` | official spec | canonical | 2026-05-04 | high | Skill frontmatter, progressive disclosure, focused references | skill format guidance | Supports concise runtime file shape |
 
 ## Decisions
@@ -30,9 +31,9 @@ Why: this skill is a repeatable authoring workflow with pre-inspection, scoped o
    Status: adopted
    Why: official AGENTS.md and Codex docs both describe hierarchical instructions where narrower files override broader guidance.
 
-3. Keep `CLAUDE.md` as a compatibility symlink when needed.
+3. Do not create `CLAUDE.md`; remove `CLAUDE.md` symlinks to `AGENTS.md`.
    Status: adopted
-   Why: one canonical instruction file avoids divergent provider-specific copies.
+   Why: Claude Code reads `AGENTS.md` directly, and any `CLAUDE.md` on the path stops it from loading `AGENTS.md`.
 
 4. Treat OpenAI `AGENTS.override.md` behavior as compatibility guidance, not a shared-repo default.
    Status: adopted
@@ -51,7 +52,7 @@ Why: this skill is a repeatable authoring workflow with pre-inspection, scoped o
 | Nested scope and precedence | complete | official AGENTS.md guide, OpenAI Codex docs |
 | Prose minimization | complete | user concern, Agent Skills progressive disclosure |
 | Command precision | complete | AGENTS.md examples, repo contribution conventions |
-| CLAUDE.md compatibility | complete | existing skill behavior, local repo convention |
+| CLAUDE.md compatibility | complete | Claude Code agents-md docs |
 | Provider-specific variance | partial | OpenAI Codex docs covered; other tools deferred until a concrete repo need |
 
 ## Open gaps

skills/agents-md/SPEC.md

@@ -12,7 +12,7 @@ In scope:
 
 - Root `AGENTS.md` files.
 - Nested `AGENTS.md` files for subtree-specific overrides.
-- `CLAUDE.md` compatibility symlinks when needed.
+- Removing `CLAUDE.md` symlinks and merging existing `CLAUDE.md` files into `AGENTS.md`.
 - Concise command tables, external reference tables, and commit attribution rules.
 - Removing duplicated prose from existing agent docs.
 
@@ -38,7 +38,7 @@ Out of scope:
 - Keep root guidance broad and nested guidance narrow.
 - Keep `AGENTS.md` under 60 lines when practical and under 100 lines always.
 - Preserve the commit attribution section when the repo requires AI co-authorship.
-- Use a `CLAUDE.md` symlink only for compatibility; avoid divergent copies.
+- Do not create `CLAUDE.md`; Claude Code reads `AGENTS.md` when no `CLAUDE.md` exists.
 
 ## Source And Evidence Model