Do you symlink your AGENTS.md and skills to .claude?

AGENTS.md is the cross-tool standard for AI coding instructions, but Claude Code still looks for CLAUDE.md and .claude/skills/. Instead of maintaining two copies, use symlinks so both conventions resolve to the same files.

The problem

Most AI coding tools (Cursor, GitHub Copilot, OpenCode) read AGENTS.md and .agents/skills/. Claude Code reads CLAUDE.md and .claude/skills/. If you maintain separate files, they drift apart and your team gets inconsistent AI behavior depending on which tool they use.

The solution: symlinks

Symlinks let you keep one source of truth while satisfying both conventions.

AGENTS.md → CLAUDE.md

Keep your instructions in AGENTS.md (the cross-tool standard) and symlink CLAUDE.md to it:

ln -s AGENTS.md CLAUDE.md

.agents/skills/ → .claude/skills/

Keep your skills in .agents/skills/ and symlink from .claude/skills/:

# Ensure the source and target directories exist
mkdir -p .agents/skills
mkdir -p .claude

# Create the symlink so Claude sees the same skills
ln -s ../.agents/skills .claude/skills

├── AGENTS.md
├── CLAUDE.md               ← copy of AGENTS.md (manually maintained)
├── .agents/
│   └── skills/
│       └── commit/
│           └── SKILL.md
└── .claude/
    └── skills/
        └── commit/
            └── SKILL.md    ← copy of .agents/skills/commit/SKILL.md (manually maintained)

❌ Figure: Bad example - Duplicated files will drift apart and cause inconsistent AI behavior

├── AGENTS.md                ← single source of truth
├── CLAUDE.md → AGENTS.md   ← symlink
├── .agents/
│   └── skills/              ← single source of truth
│       └── commit/
│           └── SKILL.md
└── .claude/
    └── skills → ../.agents/skills   ← symlink

✅ Figure: Good example - Symlinks keep one source of truth — edit once, both tools pick it up

Committing symlinks to git

Git tracks symlinks natively. When you commit and push, your teammates get the same symlinks when they clone or pull — no extra setup needed.

git add CLAUDE.md .claude/skills
git commit -m "Add symlinks from .claude to .agents for Claude Code compatibility"

git config core.symlinks true

What about .claude/settings.json?

The .claude/ directory may also contain Claude Code-specific configuration files like settings.json and settings.local.json. These are unique to Claude Code and don't belong in .agents/, so don't symlink the entire .claude/ directory — only symlink the shared items (skills).