Keep your repos harness agnostic

I use four AI harnesses in a normal week. An IDE with fast file navigation when I’m exploring, one CLI for personal projects, a desktop app for work, and occasionally a fourth when I want a second opinion on the same repo.

That’s not a recommendation, it’s just the situation. And it has one consequence: anything I set up inside one of them is invisible to the other three. A saved session memory, a skill in some platform’s format, a per-tool config file. All of it disappears the moment I open the same folder somewhere else.

So the rule I work by is simple. Only real files in the repo are shared between harnesses. Everything else is a convenience I’m renting.

Three things follow from that.

1. Skills are plain Markdown, not a platform format

A skill here is just a procedure: how to import a bank export, how to publish a post, how to run a translation. Every serious harness now has its own format for these, and they’re all different.

Writing them in one vendor’s format gets you autocomplete and costs you portability. So I use a dumber version: one Markdown file per procedure, in a skills/ folder in the repo.

skills/
  transaction_import_skill.md
  linkedin_post_skill.md
  video_editing_skill.md

Then I list them in the instructions file with a path and one line on when to use them:

Any agent, in any tool, can read that table, open the file it needs, and follow it. There’s no runtime and nothing to register. When a new harness shows up, it works on day one.

2. One instructions file, symlinked

AGENTS.md is becoming the convention, and several tools read it directly. One of the tools I use looks for CLAUDE.md instead.

That’s one ln -s away from not being a problem:

ln -s AGENTS.md CLAUDE.md

Now there’s one file, four readers, and one rule written at the top of it: only AGENTS.md gets edited. The symlink follows on its own.

What this avoids isn’t dramatic, which is why it’s worth doing. Two instruction files drift apart over a few weeks, and you end up with two agents confidently following two different conventions in the same repo.

3. Assume no memory survives the session

Every harness has some form of persistent memory and none of them share it. So anything that matters, I write down as a file: decisions in a log, conventions in the instructions, procedures in a skill.

This sounds like extra work. In practice it’s the same work done once instead of four times, and it had a side effect I didn’t expect. Things written for an agent to read turn out to be things I can read six months later. My own notes got better because I started writing them for a reader with no context at all.

The part I haven’t solved: MCP servers

Every harness needs its MCP connections set up separately. Same servers, same credentials, four setups, and they drift apart.

It’s also wasteful in a way that shows up in the bill. One analytics server I use exposes 275 tools. Every one of those definitions, with its description and schema, takes up context on every request, and I call maybe four of them.

My guess at where this goes: a single MCP server you connect once in every harness, which then manages which sub-servers and which subset of their tools get exposed per project. Something like Cloudflare’s code mode would help here, replacing a flood of tool definitions with a small interface the model calls programmatically. It would also fix a second annoyance, which is running the same server against different accounts depending on the project.

If someone has already solved this, I’d like to know. It’s the last piece of my setup that’s still tool-shaped instead of file-shaped.

Sources

• Claude Code 2.1.277 adds an AGENTS.md fallback
• The AGENTS.md specification