AGENTS.md vs CLAUDE.md: use both without repeating yourself

· 3 min read

If you use more than one AI coding tool on a project, you meet a small, annoying problem: each tool wants its own instruction file. Claude Code reads CLAUDE.md. Other tools read AGENTS.md. GitHub Copilot has .github/copilot-instructions.md. Written separately, these drift apart within a week.

This guide explains what the files are for and a setup that keeps one copy.

What each file is

  • AGENTS.md is a plain markdown file at the root of your project with instructions for AI coding tools: what the project is, how to run it, the rules to follow. It is meant to be shared by tools, and OpenAI Codex reads it.
  • CLAUDE.md is the project instruction file Claude Code reads at the start of a session.
  • .github/copilot-instructions.md is where GitHub Copilot looks for repository instructions.

Tools change how they find these files over time, so check each tool’s documentation for the current behaviour. The pattern below does not depend on the details.

The problem with two copies

Copy the same rules into AGENTS.md and CLAUDE.md and you now maintain both. Someone updates one, the other goes stale, and two tools follow different rules on the same codebase. The fix is to write the instructions once and have the other files point to it.

One source of truth

Put everything in AGENTS.md, and make the tool-specific files thin pointers. This is how Skill Builder’s own repository is set up.

AGENTS.md holds the real content:

# AGENTS.md

Single source of truth for every AI coding assistant. Tool-specific files
only point here. Do not duplicate this content elsewhere.

## Project

...

## Commands

...

CLAUDE.md is two lines. It says where the content lives, and the @AGENTS.md line imports that file into Claude Code’s context:

# CLAUDE.md

All project instructions live in AGENTS.md, shared by every AI tool.

@AGENTS.md

.github/copilot-instructions.md does the same for Copilot: a short note and a pointer back to AGENTS.md. Now there is one file to edit, and every tool sees the same rules.

What belongs in the file

Write for a capable colleague who has never seen the project. A structure that works:

  1. Project: one paragraph on what it is and who it is for.
  2. Tech stack: the languages, frameworks and tools in use.
  3. Commands: install, run, test, build and the check to run before every commit. Exact commands, in a code block.
  4. Structure: a short map of the folders and what lives in each.
  5. Rules: the architecture and conventions that are not obvious from the code.
  6. Testing and git: how tests are written and what a commit should look like.

What to leave out

  • Anything the code already says. A tool can read the code.
  • Long tutorials. Link to documentation instead.
  • Secrets. These files are checked in and read by tools; never put keys in them.
  • Task-specific playbooks. Those belong in skills.

Instruction files and skills

An instruction file applies to every task in the project, so keep it short and general. A skill holds a playbook for one kind of task and is loaded only when that task comes up, so it can be long and detailed without costing anything the rest of the time.

If you find yourself adding “when asked to write a migration, do these twelve steps” to AGENTS.md, that is a skill. See how to write a SKILL.md and skills versus agents.

A quick checklist

  • One real file (AGENTS.md); the others are pointers.
  • Commands are exact and copy-pasteable.
  • Rules say why where it is not obvious.
  • No secrets, no duplicated content.
  • Reviewed whenever the project changes shape.

Skill Builder builds the skills and agents that sit next to these files and exports them for Claude Code, Copilot and Codex in the folders each tool reads.