Your AI instructions shouldn’t belong to one tool

I knew AGENTS.md was coming for me.

Not in a dramatic way. More like the slow realisation that the drawer you keep avoiding is, in fact, the drawer you have to tidy.

That was not the surprising part. AGENTS.md is already becoming a useful common denominator for coding agents. Codex expects it. Cursor supports it as a simple project-instruction file. Warp can generate or link it as project rules. Gemini still defaults to GEMINI.md, but can be configured to include AGENTS.md too.

It is not a universal standard. Not yet. But if you use more than one agent, a shared instruction file is not a radical idea. It is where the centre of gravity seems to be moving.

The problem was that I had accidentally made Claude Code the front door to my work.

My Claude setup had become my daily driver: global instructions, workspace instructions, slash commands, skills, helper scripts, hooks, local automations, runtime state, and a lot of small habits I relied on without thinking about them.

If I broke it, I was not breaking a toy config. I was breaking the system I used to get work done. That could mean losing days to a painful rebuild, dropping commitments, or falling into the kind of rabbit hole where you start by fixing a symlink and somehow end up questioning every decision you have made since January.

Then Codex started getting genuinely useful.

That was the point where this stopped being theoretical. In the Codex desktop app especially, the incentives were obvious: add a skill here, add an instruction there, make a little Codex-specific improvement because it helps today. Nothing dramatic. Just a quiet fork in the way I worked.

If I did not deal with it soon, I could feel the future debt forming. One setup for Claude. Another setup for Codex. Different skills. Different instructions. Different habits. Then eventually some horrible afternoon where my future self would curse my current self for letting it drift.

That is where the migration gets interesting. The question was not “should I use AGENTS.md?” The question was: how do I get there without knocking over the thing I use every day?

The drawer I had to tidy

Every serious agent wants a little home of its own.

Claude Code has CLAUDE.md, .claude/, slash commands, memory, settings, and runtime state. Codex has AGENTS.md, .codex/, skills, sessions, and its own assumptions. Gemini CLI has its own context files and command model. Future tools will bring more names.

That is fine when the files are truly tool-specific. A session log belongs to the tool that created it. A settings file that the tool rewrites should stay with that tool. Runtime state is not a problem.

The problem starts when the things that were really mine end up living inside one tool’s folder.

How I like agents to commit. How I want them to route work between projects. What tone I prefer. Which safety rules matter. Which workflows should be treated as stable. Those are not really Claude preferences or Codex preferences. They are mine.

If they live in one tool’s config, the tool slowly becomes the operating system.

The boring idea that worked

The pattern I settled on is almost disappointingly simple:

AGENTS.md
    ├── Claude adapter
    ├── Codex adapter
    └── future tool adapter

One source of truth. Many doors.

The durable guidance lives in AGENTS.md. Tool-specific files become thin adapters that point at it. Tool runtime stays in the tool folder that owns it.

That gives each agent the file it expects without making any one vendor the canonical home for the way I work.

The important distinction is not the filename. It is ownership.

If a rule is stable, cross-agent, and part of how I want to work, it belongs in the shared layer. If a file is generated, rewritten, temporary, private to a tool, or only meaningful to one runtime, it stays tool-specific.

Migration is not setup

If you are starting fresh, this is easy. Create AGENTS.md, point each tool at it, and keep going.

Migrating an existing setup is different.

In my case, the useful instructions were mixed up with things I did not want to move.

Some files were instructions. Some were memories. Some were logs. Some were little tripwires I had forgotten existed.

Some scripts had hardcoded .claude paths. Some local jobs could wake up and commit halfway through the migration. Some “simple” symlink changes affected how different agents loaded instructions. None of this was conceptually difficult. It was just the kind of practical mess that matters because it is attached to real work.

This is why the safe order matters.

Do not start by moving files.

First inventory. Then classify. Then decide the canonical direction. Then make the smallest safe cut. Then validate each tool separately.

It is not glamorous. Neither is checking that the electricity still works after you move the fuse box. But you do check.

What actually worked

The shape that worked was:

inventory -> classify -> plan -> move -> adapt -> validate

Inventory answers: what exists, what is real, what is a symlink, what is broken, what is runtime, and what is private?

Classify answers: what should become shared instruction, what should remain tool runtime, what should become a thin adapter, and what needs manual review?

Plan answers: what is the smallest safe sequence of changes?

Move answers: where does the canonical file actually live?

Adapt answers: how does each tool continue to see what it expects?

Validate answers: does Claude still load the instructions, do slash commands still work, does Codex see the skills, and are there any broken links?

Let the agents check each other

The paired-agent workflow helped here. Codex was good at inventory, filesystem work, and mechanical edits. Claude Code was good at validating Claude-specific behaviour: what loaded, which slash commands still worked, and whether a proposed adapter actually behaved the way the docs implied.

That was useful not because either agent was magic, but because each one could check the surface it actually uses.

The best part was not that the agents did the work. It was that they could check each other. One agent would make the mechanical change. The other would validate the bit only it could really see.

This is the part I would keep if I did the whole thing again.

Do not ask one agent to rewrite its own floor while standing on it. Let one tool do the mechanical move, and let the other validate the behaviour it owns. It is slower than a single heroic sweep, but much less likely to leave you wondering which instruction file is secretly winning.

The public version

I pulled the reusable version of this into a public repo: agents-first-playbook.

It is the playbook: templates, prompts, a read-only inspector, a migration guide, and a paired-agent protocol.

I made it for my team first, because I know they are going to run into the same problem. Then I realised the shape of the problem is not especially mine. If you have read this far, there is a decent chance you have a stake in this game too.

The useful thing is not a magic script. I do not think there should be a magic script that rewires everyone’s agent setup. The useful thing is a safe process you can point your own agent at:

inspect my setup
classify what you find
make a migration plan
do not move anything until the plan is reviewed

That last bit matters. Agent config can be surprisingly sensitive. It can reveal how you work, who you work with, what tools you use, what private repos exist, and what local automation runs in the background. The public artifact should be the method, not the contents of your private operating system.

If it saves someone else a few hours of pain, or prevents one “why is my agent now reading three different instruction files?” afternoon, that is enough.

The rule I am keeping

The tool is less interesting than the discipline around it.

AGENTS.md is useful because it creates a neutral place for durable guidance. But the real win is the habit underneath it: separating stable preferences from tool runtime, and treating tool-specific files as adapters rather than homes.

That is what makes the setup portable.

I want to be able to use Claude Code, Codex, Gemini CLI, or whatever comes next without rewriting the way I work every time. I do not want every new agent to become a new knowledge base.

The principle is simple:

You should be able to change agents without changing your operating system.

That is the thing I was really migrating.