Organizing Agent Skills: One Source of Truth Across Every Agent

I ran find ~ -name "SKILL.md" on my machine last week. 175 results.

Skills in ~/.openclaw/skills/. Skills in ~/.claude/skills/. Skills in ~/.codex/skills/. Skills inside ARIA's config directory. Skills I wrote months ago that I'd completely forgotten about.

Some were different approaches for the same job. Some were outdated copies of things I'd already fixed somewhere else. A few only worked in one agent because they relied on conventions the others didn't understand.

If you're running more than one AI agent, you probably have the same problem. You just haven't counted yet.

How skill sprawl happens

It starts innocently. You build a skill for Claude Code that helps it understand how to connect to some tool or follow a workflow. It works. A week later, you're working in Codex and you need that same workflow or tool. So you copy the files over, tweak the format slightly, and move on.

Then you fix a bug in the Codex version. The Claude Code copy is now stale, but you don't remember that because you're already thinking about something else.

A month later, you set up OpenClaw. You need that skill again. You copy it from... somewhere. Maybe the Codex version, maybe the Claude Code version. Honestly, you're not sure which one is current anymore.

This is the same thing that happens with dotfiles. Developers often have .bashrc and .vimrc and .gitconfig scattered across machines, each slightly different, each drifting further from the others. The community eventually solved it with bare git repos and tools like GNU Stow.

Agent skills are dotfiles now. Same problem, different tools.

What actually hurts

The duplication itself isn't the real issue. It's the drift.

I have an ARIA skill that connects all 48 of my personal assistant tools: calendar, email, tasks, habits, weather, home automation. It's the most important skill I own. It exists in three places. After a few weeks of editing whichever copy happened to be open, none of them matched.

Stale copies caused real problems. I'd fix an authentication bug in one agent's version and then waste 20 minutes debugging the same issue in another agent because I forgot to update that copy.

Then there's the discovery problem. I'd go to build something and think "do I already have a skill for this?" The answer required searching across five different directories on two different machines. Half the time, I'd just build it again rather than hunt for it.

Onboarding a new agent is the worst part. Every time I set up a new tool, I'm manually copying skills, adapting formats, and hoping I grabbed the right versions. It's a 30-minute chore that should take zero seconds.

And none of this accounts for cross-machine sync. My OpenClaw instance runs on a VPS. Claude Code and Codex run on that same VPS but they also run on my laptop. Getting skills to both places means remembering to copy files between machines, which I do not reliably do.

Skills are more similar than they look

When I actually compared my skills across agents, the differences were smaller than I expected.

OpenClaw skills use a SKILL.md file with YAML frontmatter, a scripts/ directory, and optional references/. Claude Code uses CLAUDE.md or project-level instructions alongside tool definitions. Codex follows a similar pattern with its own path conventions. ARIA defines tools in code, but the documentation is still markdown.

Strip away the agent-specific stuff and what's left is always the same: markdown instructions telling the agent what the skill does, plus scripts that do the actual work. The only thing that changes is the wiring. Where the file goes. What the entry point is called. What metadata the agent expects.

That's an adapter problem. The skills themselves are portable.

Something I didn't expect: slimming down instruction files and moving process knowledge into well-structured skills made the agents more reliable. Less noise in the system prompt means the model spends less time sorting through irrelevant context. Organizing my skills wasn't just about my sanity. It was making the agents better at their jobs too.

The fix: one git repo, a manifest, and an installer

The solution I landed on is boring on purpose.

One git repo. A JSON manifest that declares which skills go where. A Bun script that symlinks everything into place.

The repo structure looks like this:

~/Development/agent-skills/
├── skills/
│   ├── aria/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   └── references/
│   ├── weather/
│   ├── github/
│   ├── obsidian-knowledge/
│   └── ...
├── adapters/
│   ├── openclaw/
│   ├── claude-code/
│   └── codex/
├── manifest.json
├── install.ts
└── README.md

Skills live in skills/ as the canonical, agent-agnostic versions. Each skill folder has everything the skill needs: instructions, scripts, reference docs.

Adapters live in adapters/ and contain the thin, agent-specific wrappers. If OpenClaw needs a slightly different entry point or Claude Code expects a different metadata format, the adapter handles that translation. The skill itself stays clean.

The manifest declares what goes where:

{
  "skills": {
    "aria": {
      "targets": ["openclaw", "claude-code", "codex"],
      "core": true
    },
    "weather": {
      "targets": ["openclaw", "claude-code"],
      "core": true
    },
    "coding-agent": {
      "targets": ["openclaw"],
      "core": false
    }
  },
  "agents": {
    "openclaw": { "path": "~/.openclaw/skills/" },
    "claude-code": { "path": "~/.claude/skills/" },
    "codex": { "path": "~/.codex/skills/" }
  }
}

core: true means the skill gets synced to every agent in its target list. The agents block tells the installer where each agent expects to find its skills. Simple mapping.

The installer is a short Bun script:

bun run install.ts --target openclaw    # install just OpenClaw skills
bun run install.ts --target all         # install everything everywhere
bun run install.ts --target all --copy  # copy instead of symlink
bun run install.ts --dry-run            # preview what would change

Default mode is symlinks. Edit the canonical skill, every agent sees the change immediately. No drift. No sync step. If you need copies instead (containers, CI, environments where symlinks are a pain), pass --copy.

Since the whole thing is a git repo, cross-machine sync comes for free. My VPS (where OpenClaw runs) and my laptop (where Claude Code and Codex live) both clone the same repo. Pull, run the installer, done. I'm considering a post-pull git hook that runs the install automatically, but honestly, I don't update skills often enough for that to matter yet.

That's it. No framework. No build step. Just files, links, and a script.

I open-sourced the skeleton repo if you want to fork it and adapt it to your setup: github.com/imjoshnewton/agent-skills

Not everything goes everywhere

One thing I got wrong early on was trying to sync every skill to every agent. That's unnecessary and creates noise.

Some skills are core. My ARIA tools, weather, GitHub, Obsidian search, web research — I want those available no matter which agent I'm talking to. Those get core: true and target all agents.

Other skills are agent-specific and should stay that way. OpenClaw's heartbeat system doesn't make sense in Claude Code. The coding-agent skill that spawns Claude Code sessions from OpenClaw has no business in Codex. Codex's sandbox tools are irrelevant to everything else.

That classification lives in the manifest. When I add a new skill, I decide once where it belongs. The installer handles the rest.

What doesn't exist yet (but should)

My repo-and-manifest approach works for me, but I built it from scratch. There's no standard for any of this.

There's no package.json equivalent for agent skills. No way to declare dependencies between skills, pin versions, or describe what a skill requires from the host agent. If I share a skill with someone else, they have to read the code and figure out how to wire it up themselves.

Cross-agent skill discovery doesn't exist either. I can't run skill search "weather" and have it find matching skills regardless of which agent I'm in. Each agent has its own search, or more likely, no search at all.

ClawhHub is moving in this direction with a community skill registry for OpenClaw. That's a start, but it's one agent's ecosystem. The real gap is a standard that works across agents. A shared format for skill metadata that OpenClaw, Claude Code, Codex, and whatever comes next can all understand.

I think skills are where the real value is heading in AI agents. The models are commoditizing fast. The agents themselves look more alike every month. What makes one agent more useful than another comes down to what it can actually do. That's skills. Whoever builds the npm-for-skills is going to own a big piece of this.

Where to start

If you're running multiple agents and haven't organized your skills yet, here's the path I'd take:

1. Run find ~ -name "SKILL.md" and count the results. The number will surprise you.
2. Group what you find by domain: calendar skills, email skills, coding skills, etc.
3. Identify the duplicates. Pick the best version of each.
4. Create a single directory (git repo or not) as the canonical source.
5. Symlink from each agent's expected path into the canonical source.
6. Add a manifest if you want to get organized about what goes where.
7. Add an installer script if you want to automate the symlinking.

Steps 1 through 5 take about an hour. Steps 6 and 7 are optional but worth it if your skill count keeps growing.

The important thing is to centralize before the sprawl gets worse. Every new agent you try, every new skill you build, every machine you work on — they all multiply the problem.

Fix it once. Every future skill is just a manifest entry and a symlink. Your agents don't care where the files live. They just need to find them.