Do you share one AGENTS.md and skills folder across AI tools?

AGENTS.md is the cross-tool standard for AI coding instructions. Claude Code and GitHub Copilot code review both read it directly now, so you don't need a CLAUDE.md or .github/copilot-instructions.md copy of it. Skills are the one gap left: Claude Code only loads skills from .claude/skills/, so symlink that folder to .agents/skills/.

The problem

If you keep the same instructions in several files, they drift apart and your team gets different AI behavior depending on which tool they use.

Here is where the main tools look today:

The solution

Instructions: keep only AGENTS.md

Put your instructions in AGENTS.md and don't add a CLAUDE.md next to it. By default, Claude Code reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any folder above it. Adding one of those files makes Claude Code ignore your AGENTS.md.

Copilot code review also reads AGENTS.md from the root of the repository, so you no longer need to symlink .github/copilot-instructions.md to it. Only use copilot-instructions.md for guidance that should apply to Copilot alone.

When you do need a CLAUDE.md

Some cases still need a CLAUDE.md:

• You want to add Claude-specific instructions
• Someone on the team uses a Claude Code version older than v2.1.277, or has turned off the built-in agents-md plugin

In those cases, import AGENTS.md at the top of CLAUDE.md:

@AGENTS.md

## Claude Code

- Claude-specific instructions go here

Use an import rather than a symlink. A symlinked CLAUDE.md turns into a one-line text file on Windows clones unless the developer has symlinks set up (see the note below).

❌ Figure: Bad example - Telling Claude Code to read AGENTS.md in words doesn't load it

Skills: symlink .claude/skills to .agents/skills

Keep your skills in .agents/skills/ and symlink .claude/skills/ to it:

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

# Create the symlink so Claude Code 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, read by every tool
├── .agents/
│   └── skills/              ← single source of truth
│       └── commit/
│           └── SKILL.md
└── .claude/
    └── skills → ../.agents/skills   ← symlink

✅ Figure: Good example - One AGENTS.md and one skills folder - edit once, every tool picks it up

Already symlinked CLAUDE.md or copilot-instructions.md?

• CLAUDE.md → AGENTS.md - harmless, because Claude Code reads the content once. Delete it to drop the Windows problem below, or replace it with an @AGENTS.md import if you need a CLAUDE.md
• .github/copilot-instructions.md → AGENTS.md - delete it, because Copilot code review already reads AGENTS.md

Committing symlinks to git

Git tracks symlinks natively. When you commit and push, your teammates get the same symlink when they clone or pull.

git add .claude/skills
git commit -m "Symlink .claude/skills to .agents/skills"

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).