How to Share One Skills Folder Across Claude Code, Codex, and Gemini
Omarchy symlinks a single skills directory into every agent's config path. Here's how the pattern works and how to set it up yourself on macOS or any Linux distro.
How do you share one skills folder across multiple AI agents?
Symlink a single source directory into each agent’s expected skills path. Omarchy does exactly this out of the box, pointing five different locations at one folder:
~/.claude/skills # Claude Code
~/.codex/skills # OpenAI Codex
~/.pi/agent/skills # Pi
~/.gemini/config/skills # Google Antigravity
~/.agents/skills # generic locationWrite a skill once, and every agent that looks in its own conventional path finds it. The trick requires nothing from Omarchy itself — it is plain symlinks, and you can set it up on macOS, Ubuntu, or any system where these agents run.
TL;DR
- Each agent looks for skills in its own directory. Maintaining separate copies means they drift.
- A symlink from each agent’s path to one shared folder solves it — one source of truth, no copying, no sync step.
- Omarchy ships this configured, wiring five paths to a single system skills directory.
- The pattern is portable. Nothing about it is Omarchy-specific;
ln -sis all it takes. - Version-control the shared folder, and every agent on every machine gets the same skills from one
git pull. - Symlinks are not a universal answer — some tools resolve or reject them, so verify each agent picks the folder up.
Why does each agent use a different path?
Because each was designed independently, and none of them expected to share a machine with nine others.
Seven tools to build an app. Or just Remy.
Editor, preview, AI agents, deploy — all in one tab. Nothing to install.
That was a reasonable assumption when a developer ran one assistant. It is a poor one now. Running Claude Code for large refactors, Codex for a second opinion, and a cheaper agent for small edits is an ordinary setup, and the moment you do it, per-agent configuration directories become a maintenance problem rather than a detail.
The failure is quiet. You improve a skill while working in one agent, forget to copy it, and weeks later a different agent behaves worse for reasons that are not obvious. Nothing errors. The agents simply know different things, and you have no signal telling you which copy is current.
How do I set this up myself?
Four steps, and none of them require Omarchy.
1. Pick one folder as the source of truth. Anywhere you like; a dotfiles repository is the obvious choice:
mkdir -p ~/dotfiles/agent-skills2. Move any existing skills into it. Do this before creating links, so nothing is lost:
cp -r ~/.claude/skills/* ~/dotfiles/agent-skills/ 2>/dev/null3. Replace each agent’s directory with a symlink. Remove the original first — ln -s will not overwrite an existing directory, and if one is left in place you end up with a nested link inside it rather than a replacement:
rm -rf ~/.claude/skills
ln -s ~/dotfiles/agent-skills ~/.claude/skills
rm -rf ~/.codex/skills
ln -s ~/dotfiles/agent-skills ~/.codex/skills
mkdir -p ~/.gemini/config
rm -rf ~/.gemini/config/skills
ln -s ~/dotfiles/agent-skills ~/.gemini/config/skills4. Verify each link resolves:
ls -la ~/.claude/skills ~/.codex/skills ~/.gemini/config/skillsEach should print an arrow pointing at your shared directory. If one shows a real directory instead, the rm -rf did not happen before the ln -s.
Why version-control the shared folder?
Because once one folder feeds every agent, that folder is the only thing you need to move between machines.
Keeping it in a git repository means a new laptop needs one clone and a handful of symlink commands to have every agent configured identically to your existing setup. It also gives you history: a skill that made an agent worse can be reverted, and you can see when it changed.
This is the same logic behind dotfiles generally, applied to a category of configuration that did not exist two years ago. The difference is that agent skills change behaviour in ways that are harder to notice than a shell alias. History matters more, not less.
When does this pattern break?
Three cases are worth knowing before you rely on it.
A tool that rejects symlinked directories. Most respect them, since a symlinked directory behaves like a real one for ordinary file operations. But a tool doing its own path validation, or running inside a sandbox that does not follow links outside its permitted roots, may not. Verify per agent rather than assuming.
Format differences between agents. A shared folder guarantees every agent reads the same files. It does not guarantee every agent interprets them the same way. If two agents expect different frontmatter or file layouts, sharing the directory means each will read the other’s files and possibly ignore or misread them. Sharing the location is not the same as sharing a format.
Backup tools that follow links. Some backup and sync tools dereference symlinks and store a full copy behind each one, which can turn one folder into five in your backups. Check how yours handles them if the folder is large.
None of these makes the pattern a bad idea. They just mean it is worth ten minutes of verification rather than assumed to work.
Writing a capability once
The reason this pattern is worth ten minutes of setup is that it makes a capability portable. Write a skill once and it stops mattering which agent you are using — the knowledge lives in one place, and every tool inherits it instead of drifting into five slightly different copies.
The same instinct scales past configuration. A product agent like Remy builds a full-stack app you own outright — backend, database, frontend, auth, tests, and deployment — from a plain-language spec you maintain rather than a codebase you hand-edit. Because the spec is the source of truth, better models improve the app without anyone rewriting it, which is the same reason one folder beats five copies.
Frequently Asked Questions
Where does Claude Code look for skills?
Claude Code reads skills from ~/.claude/skills. Replacing that directory with a symlink to a shared folder works because the path is what matters, not whether it is a real directory.
Which skills directories does Omarchy link together?
Omarchy symlinks its system skills folder into ~/.claude/skills, ~/.codex/skills, ~/.pi/agent/skills, ~/.gemini/config/skills, and a generic ~/.agents/skills location.
Can I do this on macOS instead of Linux?
Yes. Symlinks work identically on macOS, and the agent CLIs use the same configuration paths. The commands in this post run unchanged.
Will one skill work correctly in every agent?
Not necessarily. Sharing a directory guarantees every agent sees the same files; it does not guarantee they all parse them the same way. Where agents expect different formats, test the skill in each rather than assuming portability.
Do I need to restart an agent after adding a skill?
It depends on the agent. Some scan their skills directory on each run, others cache at startup. If a newly added skill does not appear, restart the agent session before assuming the symlink is at fault.
What happens if I delete the shared folder?
Every symlink pointing at it breaks at once, and each agent behaves as though it has no skills. This is the main risk of a single source of truth, and it is the reason to keep the folder in version control rather than only on disk.