Claude Agents Md

Apply that pattern at:

• the repo root if the repo root has AGENTS.md
• each subdirectory that has its own AGENTS.md

Migration Workflow

1. Find every AGENTS.md, CLAUDE.md, and GEMINI.md in the repo.
2. Check whether existing CLAUDE.md or GEMINI.md files are real files, symlinks, or separate instruction sources.
3. If AGENTS.md is the intended canonical source, replace the root CLAUDE.md with a real wrapper file containing @AGENTS.md.
4. For every nested directory that contains AGENTS.md, add a sibling CLAUDE.md wrapper unless one already exists with intentional different behavior.
5. Remove GEMINI.md only if the user explicitly wants Gemini support removed or handled some other way.
6. Verify coverage by confirming that every directory containing AGENTS.md also contains CLAUDE.md.

Decision Rules

• If the repo has only one root AGENTS.md, create only one root CLAUDE.md.
• If the repo has multiple nested AGENTS.md files, create matching nested CLAUDE.md wrappers.
• If a nested CLAUDE.md already exists and is not a simple wrapper, read it before changing anything.
• If the repo uses multiple agent frontends, keep AGENTS.md canonical and use thin frontend-specific wrappers instead of duplicate instruction bodies.
• If symlinks have been causing tool confusion, replace them with plain files.

Verification

• In Claude Code, use /memory to inspect which instruction files are loaded.
• In the repo, verify file coverage with a search that compares AGENTS.md paths against sibling CLAUDE.md paths.
• If opening a PR, explain that the change is instruction-file wiring, not runtime behavior.

Audit Script

audit.py (in this skill directory) scans one or more root directories for every AGENTS.md and checks whether a proper CLAUDE.md wrapper exists alongside it. Output is JSONL — one record per AGENTS.md found, plus a final summary record.

# Scan current directory (default)
python3 "${CLAUDE_SKILL_DIR}/audit.py"

# Scan specific roots
python3 "${CLAUDE_SKILL_DIR}/audit.py" ~/projects ~/.openclaw ~/.hermes

Each record contains:

• directory — the directory containing AGENTS.md
• status — ok | missing | symlink | wrong_content | empty | read_error
• fix — plain-English action to take (null when status is ok)

Act only on records where status != "ok". The script never modifies files.

Gotchas

• Do not remove GEMINI.md unless the user explicitly says Gemini support is unwanted. Removing it silently breaks Gemini instruction loading.
• Root-only wrapper is the most common mistake. Claude loads per-directory instruction files — a root CLAUDE.md alone does NOT cover subdirectories that have their own AGENTS.md. Run the audit script to catch misses.
• Symlinks to AGENTS.md do not work as CLAUDE.md. A symlink causes tool confusion (reported by users). Use a real file with @AGENTS.md content instead.
• @AGENTS.md is relative to the CLAUDE.md file. If you put the wrapper in a subdirectory, the @ import resolves relative to that subdirectory — it must have its own sibling AGENTS.md, not point up to the root.