We all love skills. A skill is just a folder with a SKILL.md in it, and that's the good news: they're portable by design. The same skill works in Claude, Codex, or any other agent CLI.
The bad news is that every agent looks for them in a different place. Most CLIs have settled on .agents as the convention: Codex reads ~/.agents/skills, Gemini accepts it too. Claude ignores the convention and reads ~/.claude/skills.
The naive fix is to put your skills in both places. Now you have two copies. You improve a skill while working in Claude, and Codex keeps running the stale version. A month later you can't tell which copy is current, and neither is in version control, so there's no history to check.
The actual fix is to make sure there is only ever one real folder. Mine is a private GitHub repo, checked out at ~/c/skills. Every path an agent reads is a symlink pointing into it:
~/.agents/skills -> ~/c/skills/active
~/.claude/skills -> ~/.agents/skillsA symlink isn't a copy, it's another name for the same directory. Claude thinks it has its own skills folder, Codex thinks it has one too, and both are reading the identical files. Edit a skill anywhere and every agent gets it. Commit and the library has history. There is nothing to keep in sync, because there's only one thing.
Notice the link points at active/, not the repo root. That's deliberate. Every visible skill description costs context in every session; Codex budgets skill metadata at 2% of the context window, capped at 8000 tokens. So active/ holds a small set of daily drivers and router skills, and the long tail sits in a library/ folder in the same repo, indexed and loaded on demand. I even have a skill-cleanup skill whose job is policing this: find the fattest descriptions, move rarely used skills behind routers, keep the always-visible set small.
The setup pays off again with installers. npx skills add writes into .claude/skills, symlinks resolve, and the files land inside the repo. A new skill shows up in git status, I read it, I commit it. Nothing floats around loose on the machine.
Two things to watch.
Claude marketplace plugins skip all of this. They install to ~/.claude/plugins and never reach the repo. When someone ships the same skills both ways, like Matt Pocock does, pick one path or every skill shows up twice. I take the editable files.
And installer-owned skills stay installer-owned. npx skills update overwrites, so I don't hand-edit them. When I want my own version, I fork it into the repo and stop updating it.
That's the whole setup. Skills are code: one canonical place, version control, deliberate updates.