JIMDRURY.
Jim Drury
Flat pink editorial illustration: a real .agents folder with dashed symlink arrows to a virtual .claude folder, beside a terminal tree showing .claude entries pointing to .agents and CLAUDE.md linked to AGENTS.md.
ai

Your Claude Code setup is probably wrong, I'll tell you why.

4 MIN READ

The .claude folder

Flat pink line illustration: a .claude folder inside a padlocked dashed ring labelled Claude Code only; Claude Code gets in while Cursor and OpenCode are blocked with crosses.

2 years ago, the accusation of being a vibe coder stung as much as being called basic. Now it's an everyday practice for even the most serious of engineers.

Over time we've created standards by implementing rules files, we've given LLMs dominion over repeatable tasks through skills, and fine configured our model personas using agents files.

We create each of these within a special folder, .claude, and build a directory structure akin to this:

.claude/
├── agents/
│   └── agent-name.md
├── rules/
│   └── rule-name.md
└── skills/
    └── skill-name/
        └── SKILL.md

Then at the root of our repo we create our CLAUDE.md file with a walkthrough of the platform.

It has also vendor-locked you into Claude Code - No Cursor or Open Code for you.

I often find myself switching between TUI and GUI depending on the size of the problem I'm solving. I want my agents, rules and skills to be transferrable, and .claude is only going to work for Claude Code.

Introducing the .agents folder

A simple cross platform solution is to use the .agents folder, and it's basically the same thing, but now it's not vendor specific.

The agents folder follows the exact same structure as the .claude folder, and as other coding platforms hit the market, I'd expect them to adopt it as the standard. It's even already baked into Skills.

Let's take a look at our new structure... well it's our old structure, just with a new name.

.agents/
├── agents/
│   └── agent-name.md
├── rules/
│   └── rule-name.md
└── skills/
    └── skill-name/
        └── SKILL.md

Look familiar? It should do.

The catch is that Claude Code only looks into the .claude folder.

Can we make this work for Claude Code?

As of March 2026, there are a lot of platforms adopting the .agents folder to house our new AI powers. But Claude Code doesn't pick it up.

Flat pink line illustration: a solid .agents/skills folder and a dashed ghost .claude/skills folder pointing back to it, above the command ln -s ../.agents/skills/skill-name .claude/skills/skill-name.

The answer is actually incredibly simple - the Symbolic Link (or symlink).

The simplest way to describe a symlink is that it's a virtual file or folder, that points to another "real" file or folder.

.claude/
├── agents/
│   └── agent-name.md -> .agents/agents/agent-name
├── rules/
│   └── rule-name.md  -> .agents/rules/rule-name
└── skills/
    └── skill-name/   -> .agents/skills/skill-name
        └── SKILL.md

This now allows Claude Code to read and update the skill in a way that seems native to .claude, and it's super easy to create a symlink:

ln -s ../.agents/agents/agent-name.md .claude/agents/agent-name.md

Breaking this one-liner down, it links symbolically from the real file, to a virtual file.

This is the bit that "fools" Claude into thinking you've got a .claude directory.

We can even configure git to allow our new virtual filesystem to be stored in the repo:

git config core.symlinks true

What about CLAUDE.md?

Well we treat it exactly the same - create a non-vendor specific AGENTS.md and symlink it to make it backwards compatible.

ln -s AGENTS.md CLAUDE.md

What about Cursor and Open Code?

Flat pink line illustration: one isometric cube labelled .agents plus AGENTS.md feeding three windows: Claude Code via a .claude symlink, Cursor via a .cursor symlink, and OpenCode reading .agents directly.

Open Code is great, no work needed, .agents is the default and it turns out that Cursor has their own proprietary version of this exact pattern too, and the same solution works for Cursor too!

ln -s ../.agents/agents/agent-name.md .cursor/agents/agent-name.md

Thus creating a virtual directory structure which looks like this:

.cursor/
├── agents/
│   └── agent-name.md -> .agents/agents/agent-name
├── rules/
│   └── rule-name.md  -> .agents/rules/rule-name
└── skills/
    └── skill-name/   -> .agents/skills/skill-name
        └── SKILL.md

Thoughts

You know, I love the .claude folder. It's simple, it's powerful, and allows you to create persistent superpowers for your project. Which is why I love the .agents pattern.

It's time we applied some generalised thinking to how we set up our AI tooling! Not everything needs to be proprietary. Avoid the vendor-lock and symlink.

Similar Articles