Back to blog

One Config to Rule Them All: Sharing Agent Setup Across Claude Code, Copilot & Cortex

The views I express here are mine alone and do not necessarily reflect the opinions or official position of my employer.

I'm running three different coding agents day to day now — Claude Code, GitHub Copilot, and Snowflake's Cortex Agents — and for a while I had three separate sets of instructions, three separate skills/ folders, and three separate ways of drifting out of sync with each other. I'd fix a typo in one CLAUDE.md and forget the equivalent Copilot instructions file existed. So I did what any reasonably lazy engineer does: centralized everything and symlinked it back out. (I'm not the first to land here — hboon's coding agent setup post was the thing that convinced me it was worth doing properly instead of copy-pasting forever.)

The setup

Everything now lives in one place, ~/.config/coding-agents/, and every agent points back at it instead of keeping its own copy:

~/.config/coding-agents/
├── AGENTS.md          # universal source of truth
├── skills/            # shared across every agent
└── commands/          # agent-specific naming, same content

Three symlinks do the rest:

  • AGENTS.md is symlinked to both ~/.claude/CLAUDE.md (Claude Code) and ~/.copilot/AGENTS.md (Copilot)
  • skills/ is symlinked into both agents' skill directories
  • commands/ is symlinked to commands/ for Claude Code, and to prompts/ for Copilot, since that's what each tool expects to find

Edit one file once, and both agents pick up the change on their next session — no more "wait, did I update this in two places or three?"

Symlink vs. @-reference: pick one

There are two ways to point CLAUDE.md at a shared AGENTS.md, and I went back and forth on this enough that I think it's worth laying out both rather than pretending there's an obvious winner.

Option 1 — an actual symlink:

ln -s AGENTS.md CLAUDE.md

Option 2 — a one-line include inside CLAUDE.md:

@AGENTS.md
Symlink (ln -s)@AGENTS.md reference
What Claude Code seesAGENTS.md's content, transparentlyAn explicit include directive it resolves at load time
Works if the tool doesn't follow symlinksNo — some sandboxes/CI runners resolve paths literallyYes, it's just a normal file with one line in it
Git-friendlinessSymlinks can be fragile across OSes and some CI checkoutsPlain text, diffs cleanly everywhere
What I actually run—@AGENTS.md — one line, no surprises

I landed on the @AGENTS.md one-liner. It's the more boring choice, which in my experience is usually the right one for config — a real symlink is elegant right up until a CI runner or a zip-based deploy doesn't preserve it, and then you're debugging a missing-file error that has nothing to do with your actual code. There's a whole debate about this on r/ClaudeCode if you want the long version.

What I had to preserve first

Before pointing everything at the shared directory, each agent already had its own skills and commands built up over months — I wasn't about to nuke those to make a tidy diagram true. So the actual migration order was:

  1. Copy each agent's existing skills/ and commands/ into ~/.config/coding-agents/legacy-<agent>/ first, as a safety net
  2. Merge anything worth keeping into the shared skills/ and commands/
  3. Only then replace the agent-local directories with symlinks back to the shared ones

That merge step is the one people skip, then wonder why half their Copilot-specific prompts vanished. The shared directory now holds 14 skill folders — up from three separate, overlapping sets before the merge.

The gotcha that cost me a debugging session

Symlinking the files doesn't mean the agent notices instantly. Claude Code (and Copilot) index skills and commands at session start — if you edit or add something in the shared directory mid-session, the running agent won't see it until you restart. I spent a good ten minutes convinced my new skill file had a syntax error before I realized I just needed to /exit and reopen. If a skill you just added isn't showing up: restart the session before you start debugging the file itself.

The one thing still open

I originally planned this for Claude Code, Copilot, and Codex, then swapped Codex out for Cortex Agents partway through once I confirmed what was actually in daily use. Cortex's skills path is ~/.snowflake/cortex/skills, and I've linked that in the same way — but I haven't confirmed whether Cortex actually loads a global AGENTS.md the way Claude Code and Copilot do, or whether it only ever reads project-scoped instructions. Until I know that for sure, the Cortex project files stay project-local rather than pointing at the shared one. If you've run Cortex Agents with a global instructions file and gotten it to actually load, I'd genuinely like to know how.