Do you symlink your AGENTS.md to other tool-specific files?

AGENTS.md is the cross-tool standard for AI coding instructions, but some tools still look for their own files — Claude Code wants CLAUDE.md and .claude/skills/, and GitHub Copilot's PR review reads .github/copilot-instructions.md. Instead of maintaining multiple copies, use symlinks so every convention resolves to the same source.

The problem

Most AI coding tools (Cursor, GitHub Copilot, OpenCode) read AGENTS.md and .agents/skills/. Claude Code reads CLAUDE.md and .claude/skills/. GitHub Copilot's pull request review feature reads .github/copilot-instructions.md. 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.md → .github/copilot-instructions.md

GitHub Copilot's pull request review feature reads .github/copilot-instructions.md. Symlink it to AGENTS.md so PR reviews use the same instructions:

ln -s ../AGENTS.md .github/copilot-instructions.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)
├── .github/
│   └── copilot-instructions.md   ← another copy (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
├── .github/
│   └── copilot-instructions.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 .github/copilot-instructions.md .claude/skills
git commit -m "Symlink tool-specific files to AGENTS.md for cross-tool 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).