Claude Md Symlinker

claude-md-symlinker

`CLAUDE.md` is Claude Code's project instruction file. It is where Claude Code expects to find repo-specific context like build commands, coding conventions, architecture notes, and workflow rules.

[`AGENTS.md`](https://agents.md/) is the industry-wide accepted way to provide context to agents. It is the same as CLAUDE.md, but your repo is NOT a billboard for Anthropic. Imagine having to include a clippy.txt in your project...

Anthropic is obstinate like a goat and it is now too late for them to back down on this convention. They say, "you can add a `CLAUDE.md` that imports `@AGENTS.md` 😉" . That works, but it still leaves every repo carrying a Claude-branded compatibility file.

How about no?

claude-md-symlinker is a service and Claude Code hook that automatically creates CLAUDE.md symlinks to AGENTS.md that are not tracked in git, so that you don't have to commit them manually. Everything just works without heavy scanning of your filesystem for AGENTS.md files.

As Claude Code traverses your filesystem, any discovered AGENTS.md files will be symlinked, which gives you automatic AGENTS.md compatibility if you are a Claude Code user. If you choose to, it will also move the CLAUDE.md files to AGENTS.md while keeping the same compatibility.

In other words:

AGENTS.md                # canonical file, committed to Git
CLAUDE.md -> AGENTS.md   # local generated shim, ignored by Git

It also gives Claude Code the same Agent Skills that other tools read from `.agents/skills`, without copying them:

.agents/skills/deploy/                 # canonical skill directory
.claude/skills/deploy -> ../../.agents/skills/deploy

The tool creates one relative link per skill. It never replaces the complete `.claude/skills` directory, so Claude-only, plugin, and unmanaged skills can stay beside managed links.

Note: the initial version of this work was the [`CLAUDE.md` to `AGENTS.md` migration guide](https://solmaz.io/log/2025/09/08/c