Skip to main content
Many projects already have agent instruction files under different names. Migrating to AGENTS.md is low-risk — it’s plain Markdown, so there’s no format to convert. You’re mostly renaming files and optionally leaving symlinks for backward compatibility.

​
Common file names to migrate from

  • AGENT.md — the predecessor to AGENTS.md
  • CLAUDE.md — used by Claude / Anthropic tooling
  • CURSOR.md — used by Cursor
  • Agent sections embedded in README.md

​
Migrating from AGENT.md

If you already have an AGENT.md, migration is a single command. The symlink keeps any tooling that looks for the old name working.
1

Rename the file

Rename AGENT.md to AGENTS.md:
mv AGENT.md AGENTS.md
2

Create a symlink for backward compatibility

Point the old name to the new file so any tools or scripts that reference AGENT.md continue to work:
ln -s AGENTS.md AGENT.md
3

Commit both files

Commit the renamed file and the symlink together:
git add AGENTS.md AGENT.md
git commit -m "chore: rename AGENT.md to AGENTS.md, keep symlink"
4

Verify the agent picks up the new file

Run your agent and confirm it reads from AGENTS.md. Because the symlink resolves to the same content, both names work immediately.

​
Migrating from CLAUDE.md or CURSOR.md

If your instructions live in a tool-specific file, copy the content into AGENTS.md and keep the original for tools that require it.
1

Copy the content

Copy your existing instructions into a new AGENTS.md:
cp CLAUDE.md AGENTS.md
Or, if you want a single source of truth, replace the original with a symlink after creating AGENTS.md:
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md
2

Review the content

Open AGENTS.md and check that the instructions are still accurate. This is a good time to add any missing sections — build commands, test instructions, or code style rules.
3

Commit

git add AGENTS.md
git commit -m "chore: add AGENTS.md"

​
Migrating from a README.md agent section

Some projects document agent instructions inside README.md under a heading like “For AI assistants” or “Copilot instructions.”
1

Extract the section

Copy the relevant section(s) from README.md into a new AGENTS.md at the project root.
2

Remove or replace the section in README.md

Either delete the section from README.md or replace it with a short note pointing to AGENTS.md:
## For AI coding agents
See [AGENTS.md](./AGENTS.md) for build commands, test instructions, and code style guidelines.
3

Commit both files

git add AGENTS.md README.md
git commit -m "chore: extract agent instructions into AGENTS.md"

​
Configuring other tools to read AGENTS.md

Some tools need explicit configuration to pick up AGENTS.md. Aider — add to .aider.conf.yml: 
read: AGENTS.md
Gemini CLI — add to .gemini/settings.json: 
{
  "context": {
    "fileName": "AGENTS.md"
  }
}

​
Why migration is low-risk

  • AGENTS.md is plain Markdown — no schema, no required fields, no validation to pass.
  • A symlink means old tooling keeps working without any changes.
  • Agents that already read AGENT.md or similar files will pick up AGENTS.md once configured.
  • You can migrate incrementally: start with a minimal file and expand it over time.
Treat AGENTS.md as living documentation. Update it whenever build commands, test runners, or workflows change — just like you would a README.

Build docs developers (and LLMs) love

Get started for freeTalk to us