docs(skills): make AGENTS.md the single source of truth

categories/ai-ml/llm-token-cost-reduction/SKILL.md

@@ -49,7 +49,7 @@ Before proposing a fix, you may run: caveman learn simulate <sink_id>. Show it o
 as scale over scanned history: it sums over scanned history and never projects
 forward.
 
-REDUCIBLE (a heavy CLAUDE.md, a never-invoked skill):
+REDUCIBLE (a heavy AGENTS.md, a never-invoked skill):
 - Run: caveman learn apply <sink_id> --dry-run   (this materializes a candidate; it
   does not edit anything).
 - Propose a concrete diff and show before -> after tokens/turn.
@@ -77,7 +77,7 @@ re-pasted every turn. The candidate carries only a LOCATOR — never the block b
   running caveman mem recall "<topic>" and reading tokens_added on the hit. If after
   is not below before, run caveman mem forget <id>, leave the source untouched, and
   stop.
-- Trim the source and write the pointer. Remove the block from its CLAUDE.md or
+- Trim the source and write the pointer. Remove the block from its AGENTS.md or
   AGENTS.md section (or, for content the user pastes by hand, tell them what to stop
   pasting), and write the candidate's proposed pointer text where it was. The pointer
   names the recall path: caveman mem recall "<topic>" for the compact form, and

categories/ai-ml/prompt-optimization/SKILL.md

@@ -47,7 +47,7 @@ For repo or agent prompts, list stable context by exact path:
 
 | Context type | Examples |
 |--------------|----------|
-| Agent rules | `AGENTS.md`, `CLAUDE.md` |
+| Agent rules | `AGENTS.md` |
 | Specs | `specs/*.md`, `docs/api.md` |
 | Policies | `SECURITY.md`, `docs/releasing.md` |
 | Examples | `examples/`, `tests/fixtures/` |

categories/caveman/caveman-compress/SKILL.md

@@ -10,7 +10,7 @@ tags: [caveman, prompt-compression]
 
 ## Purpose
 
-Compress natural language files (CLAUDE.md, todos, preferences) into caveman-speak to reduce input tokens. Compressed version overwrites original. Human-readable backup saved as `<filename>.original.md`.
+Compress natural language files (AGENTS.md, todos, preferences) into caveman-speak to reduce input tokens. Compressed version overwrites original. Human-readable backup saved as `<filename>.original.md`.
 
 ## Trigger
 

categories/cursor-rules/agent-rule-management/SKILL.md

@@ -20,7 +20,7 @@ Creates rules at project or user level and manages the rule set at both.
 | "create / add / new rule", "convention", "standard", or a declarative description with no verb | create.md |
 | "list / show rules", "what rules exist" | list.md |
 | "edit / update / change rule X" | edit.md |
-| "extract / split / move from AGENTS.md / CLAUDE.md", "AGENTS.md / CLAUDE.md is too big" | extract.md |
+| "extract / split / move from AGENTS.md", "AGENTS.md is too big" | extract.md |
 | "delete / remove rule X" | delete.md |
 
 ## Workflow

categories/cursor-rules/extra-context-prime/SKILL.md

@@ -11,7 +11,7 @@ Prime Claude with comprehensive project understanding.
 
 ## Standard Context Loading:
 1. Read README.md for project overview
-2. Read CLAUDE.md for AI-specific instructions
+2. Read AGENTS.md for AI-specific instructions
 3. List project files excluding ignored paths
 4. Review key configuration files
 5. Understand project structure and conventions
@@ -23,7 +23,7 @@ Prime Claude with comprehensive project understanding.
    - Note key technologies and dependencies
 
 2. **AI Guidelines**:
-   - Read CLAUDE.md if present
+   - Read AGENTS.md if present
    - Load project-specific AI instructions
    - Note coding standards and preferences
 

categories/documentation/agent-context-file-generation/SKILL.md

@@ -336,23 +336,9 @@ Fill in the real section names, technologies, and project-specific conventions.
 
 Agents read the nearest AGENTS.md in the directory tree. Nested files take precedence, so they should contain folder-specific details, not global ones.
 
-## CLAUDE.md Companion File
+## No Companion Files
 
-Whenever you generate an `AGENTS.md` in a folder, also generate a `CLAUDE.md` in the same folder — **only if `CLAUDE.md` does not already exist**.
-
-The `CLAUDE.md` content is always exactly:
-
-```markdown
-# CLAUDE.md
-
-<!-- Generated for repository development workflows. Do not edit directly. -->
-
-Before beginning work in this repository, read `AGENTS.md` and follow all scoped AGENTS guidance.
-```
-
-This ensures Claude Code (and similar tools that look for `CLAUDE.md`) are redirected to the authoritative `AGENTS.md` instructions.
-
-**Same guard applies:** check if `CLAUDE.md` exists before writing. If it exists, skip it.
+`AGENTS.md` is the single source of truth. Do not generate a `CLAUDE.md`, `GEMINI.md`, or any other per-tool companion or pointer file alongside it — agents that support `AGENTS.md` read it directly, and a second file only drifts from the first.
 
 ## Quality Principles
 

categories/documentation/agent-facing-documentation/SKILL.md

@@ -9,7 +9,7 @@ tags:
 - context-management
 ---
 
-Reference for writing any document an agent consumes: a skill, an `AGENTS.md` / `CLAUDE.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable, since the agent takes the same _process_ every run rather than producing the same output.
+Reference for writing any document an agent consumes: a skill, an `AGENTS.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable, since the agent takes the same _process_ every run rather than producing the same output.
 
 When the document you're writing is a skill, read `SKILL-MECHANICS.md` for frontmatter, invocation choice, and router skills.
 

categories/documentation/agent-instructions-file/SKILL.md

@@ -29,8 +29,7 @@ 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 per-tool companion files or symlinks alongside it; `AGENTS.md` is the single source of truth.
 
 ## Default Sections
 

categories/documentation/readme-authoring/SKILL.md

@@ -13,7 +13,7 @@ tags:
 Write a README that reads as a shop window, not a wiki.
 
 - **IS:** writing or rewriting `README.md` for the person deciding whether to use the project, with the project type driving which capability sections earn a place and where the file will render (GitHub only, or also a registry page) driving image and badge choices.
-- **IS NOT:** polishing the prose of a README that already covers the project, or a multi-page docs site (use `docs-writing`); AGENTS.md or CLAUDE.md agent-instruction files (use `agents-md`); fixing the install or first-run experience the README describes (use `dx-audit`); marketing copy for a landing page (use `copywriting`).
+- **IS NOT:** polishing the prose of a README that already covers the project, or a multi-page docs site (use `docs-writing`); AGENTS.md agent-instruction files (use `agents-md`); fixing the install or first-run experience the README describes (use `dx-audit`); marketing copy for a landing page (use `copywriting`).
 
 ## The reader
 
@@ -150,7 +150,7 @@ Rewriting a published package's README, say in the summary that npmjs.com and Py
 | When | Run |
 |------|-----|
 | README exists and needs a prose audit, or a full docs site | `docs-writing` |
-| Project needs agent instructions (AGENTS.md, CLAUDE.md), including the content the audience gate moved out | `agents-md` |
+| Project needs agent instructions (AGENTS.md), including the content the audience gate moved out | `agents-md` |
 | The install or first-run path the README documents is itself the problem | `dx-audit` |
 | Landing-page or marketing copy beyond the tagline | `copywriting` |
 | Drafting in the user's own voice | external `ghostwriter` skill where installed, platform `readme` |

categories/documentation/technical-docs-writing-audit/SKILL.md

@@ -126,7 +126,7 @@ For the full rule list per category, read `rules/_sections.md`. The `*-defaults.
 ## Related skills
 
 - `readme-creator`: a README from scratch or a full rewrite; this skill audits and fixes existing ones in place.
-- `agents-md`: AGENTS.md/CLAUDE.md instruction files (execution-first, not reader-facing docs).
+- `agents-md`: AGENTS.md instruction files (execution-first, not reader-facing docs).
 - `copywriting`: marketing, landing-page, and product copy.
 - `dx-audit`: the product's own error messages, CLI output, and API ergonomics; this skill covers how the docs describe them.
 - `optimise-seo`: implementing `llms.txt`, AI-crawler policy, and Markdown routes in a Next.js App Router site; `nav-agent-readable` says what the docs should expose, that skill builds it.

categories/general/ag-agents-md/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ag-agents-md
-description: "This skill should be used when the user asks to \"create AGENTS.md\", \"update AGENTS.md\", \"maintain agent docs\", \"set up CLAUDE.md\", or needs to keep agent instructions concise. Enforces research-bac..."
+description: "This skill should be used when the user asks to \"create AGENTS.md\", \"update AGENTS.md\", \"maintain agent docs\", or needs to keep agent instructions concise. Enforces research-bac..."
 license: MIT
 tags: [general]
 risk: unknown
@@ -12,14 +12,13 @@ source: community
 AGENTS.md is the canonical agent-facing documentation. Keep it minimal—agents are capable and don't need hand-holding. Target under 60 lines; never exceed 100. Instruction-following quality degrades as document length increases.
 
 ## When to Use
-- The user asks to create, update, or audit `AGENTS.md` or `CLAUDE.md`.
+- The user asks to create, update, or audit `AGENTS.md`.
 - The project needs concise, high-signal agent instructions derived from the actual toolchain and repo layout.
 - Existing agent documentation is too long, duplicated, or drifting away from real project conventions.
 
 ## File Setup
 
 1. Create `AGENTS.md` at project root
-2. Create symlink: `ln -s AGENTS.md CLAUDE.md`
 
 ## Before Writing
 

categories/general/ag-ai-md/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ag-ai-md
-description: Convert human-written CLAUDE.md into AI-native structured-label format.
+description: Convert human-written AGENTS.md into AI-native structured-label format.
   Battle-tested across 4 models. Same rules, fewer tokens, higher compliance.
 license: MIT
 tags:
@@ -12,7 +12,7 @@ date_added: 2026-03-11
 
 ## Real-World Results
 
-Tested 2026-03, washinmura.jp CLAUDE.md, 5 rounds, 4 models:
+Tested 2026-03, washinmura.jp AGENTS.md, 5 rounds, 4 models:
 
 | Round | Change | Codex (GPT-5.3) | Gemini 2.5 Pro | Claude Opus 4.6 |
 |-------|--------|-----------------|----------------|-----------------|
@@ -27,7 +27,7 @@ Key findings:
 3. **Cross-model consistency**: Format that works for one model works for all (except Grok)
 4. **Semantic anchoring**: The `new-api:` label fix was the single most impactful change
 
-**The uncomfortable truth: Your beautiful, carefully-written CLAUDE.md
+**The uncomfortable truth: Your beautiful, carefully-written AGENTS.md
 might be HURTING your AI's performance. Structure > Prose. Always.**
 
 ## Limitations

categories/general/ag-code-simplifier/SKILL.md

@@ -29,7 +29,7 @@ Never change what the code does - only how it does it. All original features, ou
 
 ### 2. Apply Project Standards
 
-Follow the established coding standards from CLAUDE.md including:
+Follow the established coding standards from AGENTS.md including:
 
 - Use ES modules with proper import sorting and extensions
 - Prefer `function` keyword over arrow functions

categories/general/ag-context-fundamentals/SKILL.md

@@ -95,7 +95,7 @@ The file system itself provides structure that agents can navigate. File sizes s
 
 ### Hybrid Strategies
 
-The most effective agents employ hybrid strategies. Pre-load some context for speed (like CLAUDE.md files or project rules), but enable autonomous exploration for additional context as needed. The decision boundary depends on task characteristics and context dynamics.
+The most effective agents employ hybrid strategies. Pre-load some context for speed (like AGENTS.md files or project rules), but enable autonomous exploration for additional context as needed. The decision boundary depends on task characteristics and context dynamics.
 
 For contexts with less dynamic content, pre-loading more upfront makes sense. For rapidly changing or highly specific information, just-in-time loading avoids stale context.
 

categories/general/ag-faf-expert/SKILL.md

@@ -91,7 +91,7 @@ Expert setup of claude-faf-mcp with 33 tools:
 
 ### 🔄 Bi-Directional Sync
 Keep context synchronized across platforms:
-- `.faf` ↔ `CLAUDE.md` 
+- `.faf` ↔ `AGENTS.md` 
 - `.faf` ↔ `.cursorrules`
 - `.faf` ↔ `GEMINI.md`
 - `.faf` ↔ `AGENTS.md`

categories/general/ag-faf-wizard/SKILL.md

@@ -138,7 +138,7 @@ Already have AI context files?
 ```bash
 # Migrates existing context
 faf migrate --from .cursorrules
-faf migrate --from CLAUDE.md  
+faf migrate --from AGENTS.md  
 faf migrate --from README.md
 
 # One format, works everywhere

categories/general/ag-gha-security-review/SKILL.md

@@ -33,7 +33,7 @@ Review the workflows provided (file, diff, or repo). Research the codebase as ne
 - `.github/workflows/*.yml` — all workflow definitions
 - `action.yml` / `action.yaml` — composite actions in the repo
 - `.github/actions/*/action.yml` — local reusable actions
-- Config files loaded by workflows: `CLAUDE.md`, `AGENTS.md`, `Makefile`, shell scripts under `.github/`
+- Config files loaded by workflows: `AGENTS.md`, `Makefile`, shell scripts under `.github/`
 
 ### Out of Scope
 
@@ -122,7 +122,7 @@ Are elevated credentials (PATs, deploy keys) accessible to untrusted code?
 ### Check 5: Config File Poisoning
 
 Does the workflow load configuration from PR-supplied files?
-- AI agent instructions: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`
+- AI agent instructions: `AGENTS.md`, `.cursorrules`
 - Build configuration: `Makefile`, shell scripts
 
 ### Check 6: Supply Chain

categories/general/ag-hierarchical-agent-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ag-hierarchical-agent-memory
-description: "Scoped CLAUDE.md memory system that reduces context token spend. Creates directory-level context files, tracks savings via dashboard, and routes agents to the right sub-context."
+description: "Scoped AGENTS.md memory system that reduces context token spend. Creates directory-level context files, tracks savings via dashboard, and routes agents to the right sub-context."
 license: MIT
 tags: [general]
 risk: safe
@@ -10,13 +10,13 @@ date_added: 2026-02-27
 
 # Hierarchical Agent Memory (HAM)
 
-Scoped memory system that gives AI coding agents a cheat sheet for each directory instead of re-reading your entire project every prompt. Root CLAUDE.md holds global context (~200 tokens), subdirectory CLAUDE.md files hold scoped context (~250 tokens each), and a `.memory/` layer stores decisions, patterns, and an inbox for unconfirmed inferences.
+Scoped memory system that gives AI coding agents a cheat sheet for each directory instead of re-reading your entire project every prompt. Root AGENTS.md holds global context (~200 tokens), subdirectory AGENTS.md files hold scoped context (~250 tokens each), and a `.memory/` layer stores decisions, patterns, and an inbox for unconfirmed inferences.
 
 ## When to Use This Skill
 
 - Use when you want to reduce input token costs across Claude Code sessions
 - Use when your project has 3+ directories and the agent keeps re-reading the same files
-- Use when you want directory-scoped context instead of one monolithic CLAUDE.md
+- Use when you want directory-scoped context instead of one monolithic AGENTS.md
 - Use when you want a dashboard to visualize token savings, session history, and context health
 - Use when setting up a new project and want structured agent memory from day one
 
@@ -28,28 +28,28 @@ Auto-detects your project platform and maturity, then generates the memory struc
 
 ```
 project/
-├── CLAUDE.md              # Root context (~200 tokens)
+├── AGENTS.md              # Root context (~200 tokens)
 ├── .memory/
 │   ├── decisions.md       # Architecture Decision Records
 │   ├── patterns.md        # Reusable patterns
 │   ├── inbox.md           # Inferred items awaiting confirmation
 │   └── audit-log.md       # Audit history
 └── src/
-    ├── api/CLAUDE.md      # Scoped context for api/
-    ├── components/CLAUDE.md
-    └── lib/CLAUDE.md
+    ├── api/AGENTS.md      # Scoped context for api/
+    ├── components/AGENTS.md
+    └── lib/AGENTS.md
 ```
 
 ### Step 2: Context Routing
 
-The root CLAUDE.md includes a routing section that tells the agent exactly which sub-context to load:
+The root AGENTS.md includes a routing section that tells the agent exactly which sub-context to load:
 
 ```markdown
 ## Context Routing
 
-→ api: src/api/CLAUDE.md
-→ components: src/components/CLAUDE.md
-→ lib: src/lib/CLAUDE.md
+→ api: src/api/AGENTS.md
+→ components: src/components/AGENTS.md
+→ lib: src/lib/AGENTS.md
 ```
 
 The agent reads root, then immediately loads the relevant subdirectory context — no guessing.
@@ -60,20 +60,20 @@ Launches a web dashboard at localhost:7777 that visualizes:
 - Token savings (HAM-on vs HAM-off sessions)
 - Daily token and cost trends
 - Per-directory session breakdown
-- Context file health (missing/stale/inherited CLAUDE.md coverage)
+- Context file health (missing/stale/inherited AGENTS.md coverage)
 - Routing compliance (how often the agent follows the routing map)
 - Carbon/energy estimates
 
 ## Commands
 
 | Trigger | What it does |
 |---|---|
-| `go ham` | Set up HAM — auto-detect platform, generate CLAUDE.md files |
+| `go ham` | Set up HAM — auto-detect platform, generate AGENTS.md files |
 | `ham savings` | Show token and cost savings report |
 | `ham dashboard` | Launch the interactive web dashboard |
 | `ham audit` | Health check on memory files |
 | `ham insights` | Generate actionable insights from session data |
-| `ham route` | Add/update Context Routing section in root CLAUDE.md |
+| `ham route` | Add/update Context Routing section in root AGENTS.md |
 | `ham carbon` | Show energy and carbon efficiency data |
 
 ## Examples
@@ -84,14 +84,14 @@ Launches a web dashboard at localhost:7777 that visualizes:
 User: go ham
 
 Agent: HAM setup complete. Created 8 files.
-  - CLAUDE.md (root)
+  - AGENTS.md (root)
   - .memory/decisions.md
   - .memory/patterns.md
   - .memory/inbox.md
-  - src/api/CLAUDE.md
-  - src/components/CLAUDE.md
-  - src/lib/CLAUDE.md
-  - src/utils/CLAUDE.md
+  - src/api/AGENTS.md
+  - src/components/AGENTS.md
+  - src/lib/AGENTS.md
+  - src/utils/AGENTS.md
 
 Baseline captured in .memory/baseline.json
 Run "HAM savings" to see your token and cost savings.
@@ -114,8 +114,8 @@ Agent:
 
 ## Best Practices
 
-- Keep root CLAUDE.md under 60 lines / 250 tokens
-- Keep subdirectory CLAUDE.md files under 75 lines each
+- Keep root AGENTS.md under 60 lines / 250 tokens
+- Keep subdirectory AGENTS.md files under 75 lines each
 - Run `ham audit` every 2 weeks to catch stale or missing context files
 - Use `ham route` after adding new directories to keep routing current
 - Review `.memory/inbox.md` periodically — confirm or reject inferred items
@@ -125,8 +125,8 @@ Agent:
 - Token estimates use ~4 chars = 1 token approximation, not a real tokenizer
 - Baseline savings comparisons are estimates based on typical agent behavior
 - Dashboard requires Node.js 18+ and reads session data from `~/.claude/projects/`
-- Context routing detection relies on CLAUDE.md read order in session JSONL files
-- Does not auto-update subdirectory CLAUDE.md content — you maintain those manually or via `ham audit`
+- Context routing detection relies on AGENTS.md read order in session JSONL files
+- Does not auto-update subdirectory AGENTS.md content — you maintain those manually or via `ham audit`
 - Carbon estimates use regional grid averages, not real-time energy data
 
 ## Related Skills

categories/general/ag-kaizen/SKILL.md

@@ -356,7 +356,7 @@ Follow established patterns. Document what works. Make good practices easy to fo
 
 **Documentation lives with code:**
 - README for setup and architecture
-- CLAUDE.md for AI coding conventions
+- AGENTS.md for AI coding conventions
 - Comments for "why", not "what"
 - Examples for complex patterns
 
@@ -466,7 +466,7 @@ Documents why, when, and how
 **Before adding new patterns:**
 
 - Search codebase for similar problems solved
-- Check CLAUDE.md for project conventions
+- Check AGENTS.md for project conventions
 - Discuss with team if breaking from pattern
 - Update docs when introducing new pattern
 
@@ -482,7 +482,7 @@ Documents why, when, and how
 - Check consistency with existing code
 - Point to examples in codebase
 - Suggest aligning with standards
-- Update CLAUDE.md if new standard emerges
+- Update AGENTS.md if new standard emerges
 
 ### 4. Just-In-Time (JIT)