The file that makes it work isn't CLAUDE.md anymore

My second brain is a Git repo: journal entries, project notes, decisions, all Markdown, all read by whatever AI tool I’m working with before a session starts. Seven weeks ago I wrote about wiring it up, and the whole thesis lived in one line: “There’s a CLAUDE.md at the root that acts as an index — that’s the file that makes it work.” I stand by the idea. I don’t stand by the file anymore.

What I got wrong

I called it “just Markdown,” but it wasn’t. Every folder pointed at one root file, written for one tool, read by one company’s product. If Claude Code disappeared tomorrow, so would the instructions for using any of it. That’s not a second brain, that’s a config file for a vendor I don’t control.

I didn’t notice this until I started using GitHub Copilot CLI for some tasks and Google Antigravity for others, and both of them just ignored CLAUDE.md. Obviously. It was never theirs to read.

AGENTS.md is canonical now. CLAUDE.md is generated.

The repo now treats AGENTS.md as the source of truth — no product name in the filename, just “the agent reading this.” CLAUDE.md in the same folder is a generated copy, kept in sync but never edited directly. Every project folder looks like this now:

projects/<name>/
├── AGENTS.md        ← canonical, I edit this
├── CLAUDE.md        ← generated, never touched by hand
└── data/
    ├── memory.md      # decisions, status changes
    ├── archive.md     # old memory, by quarter
    └── *.md           # whatever dense reference the project needs

Same content, three tools can read it.

Edit the source once. The vendor files fall out of it.

That’s a smaller change than it sounds, but it forced a discipline I didn’t have before: I edit exactly one file per project now, and its copies stop drifting out of sync the way they used to.

The same trick, one level down: skills

Skills — reusable prompt workflows I keep in the repo, one folder per task — hit the same problem. I had a create-post skill that only Claude Code could see. It still is, actually — I never went back and migrated it.

Everything new goes through .ai/skills/<name>/SKILL.md instead, with a generation step that drops copies into the three vendor folders:

.ai/skills/eli5/SKILL.md        ← canonical, written once
        │
        ▼ generation step
        ├── .claude/skills/eli5/SKILL.md
        ├── .github/skills/eli5/SKILL.md
        └── .agents/skills/eli5/SKILL.md

Yesterday I added eli5 this way — one canonical file, four generated copies, same push. Write once, every tool picks it up.

Memory doesn’t live in a vendor feature either

Same instinct, one more layer down. Claude Code has a built-in memory feature. I turned it off on purpose — anything it remembered would be trapped in one product’s storage, invisible to Copilot CLI or Antigravity, gone the day I switched tools.

Instead each project gets a data/memory.md: plain markdown, appended at the end of any conversation that actually decided something. Once it passes about fifty entries, the old ones move to data/archive.md, organized by quarter — nothing gets deleted, it just ages out of the working file. One rule I added recently: keep “verified” (checked against a source) separate from “asserted” (I said it, nobody confirmed it) — a claim I stated once shouldn’t quietly harden into a fact I proved.

It’s the least exciting part of the system and probably the most load-bearing. The repo doesn’t forget things between sessions, and it doesn’t forget them to one company either.

A skill that audits itself

The part I didn’t expect: keeping every generated copy in sync needed its own tooling, so I built repo-audit. It checks the router structure, finds AGENTS.md files whose CLAUDE.md copy has drifted, flags skill folders that didn’t regenerate cleanly, and catches stale memory notes. /repo-audit fix dry-runs the corrections and applies them after I approve. /repo-audit new <project-name> "one-liner" scaffolds a whole new project with the pattern already in place, instead of me copy-pasting a template by hand.

Funny, actually — the second brain now has a subsystem whose only job is making sure it stays honest about its own structure, including the generation mechanism I described two sections ago. Felt like scope creep at first. Now it’s the thing keeping this from rotting the way Notion and Obsidian did for me.

Nothing about daily use got harder. I still just talk to whichever tool is open. But I stopped thinking of this repo as “my Claude setup” and started thinking of it as mine — Claude is a very good tenant, not the landlord.

If you’re building something similar: don’t name the file after the tool. Name it after the reader.