Share Skills Between Claude Code and Codex, Plus Gemini and Grok

To share skills between Claude Code and Codex, keep each skill in one folder and symlink that folder into two places. ~/.claude/skills is read by Claude Code and Grok. ~/.agents/skills is read by Codex, Gemini CLI and Grok. Two links cover all four agents, and an edit to the skill is live in every one of them. Copying the folder into each agent's directory also works, until the copies drift apart.

The rest of this guide covers what a SKILL.md is, a table of where each runtime looks (checked against each vendor's documentation in September 2026), the uneven way the folders overlap, and four traps we found while building a scanner for these folders in Universe.

What is a SKILL.md, in 90 seconds?#

A skill is a folder with a file called SKILL.md in it. The format started at Anthropic and is now an open standard, the Agent Skills specification, which Claude Code, Codex, Gemini CLI, Grok and many others read.

pdf-forms/
├── SKILL.md        required: frontmatter + instructions
├── scripts/        optional: code the agent can run
├── references/     optional: longer docs, read on demand
└── assets/         optional: templates, lookup tables

SKILL.md starts with YAML frontmatter and then plain markdown instructions:

---
name: pdf-forms
description: Fill and flatten PDF forms. Use when the user hands you a PDF with form fields or asks to complete an application form.
---

1. List the fields with scripts/fields.py before writing anything.
2. ...

The spec's rules are strict and worth following even where one runtime is lenient:

• name is 1–64 characters: lowercase letters, digits and single hyphens. It must match the folder name.
• description is up to 1,024 characters. Say what the skill does and when to use it. That sentence is what the model reads when it decides whether to open the skill.
• Keep the body under about 500 lines and move long material into references/. The whole SKILL.md is loaded when the skill activates. A file in references/ is read only when the agent needs it.

Where does each agent look for skills?#

As of September 2026, from each vendor's own docs:

Sources: Claude Code skills, Codex skills, Gemini CLI skills, Grok Build skills.

How you invoke a skill by hand: /skill-name in Claude Code, $skill-name (or the /skills picker) in Codex, and /skill-name in Grok for user-invocable skills. All of them can also pick a skill on their own when a task matches its description.

Who reads ~/.agents/skills, and who reads .claude/skills?#

The agents do not read each other's folders evenly:

• ~/.agents/skills belongs to no single vendor. It is the open standard's folder. For Codex it is the personal folder; Codex has no ~/.codex/skills in its docs. Gemini CLI treats it as an alias of ~/.gemini/skills, and within the same tier the alias wins.
• Grok reads Claude Code's folders on purpose. xAI's docs say Grok "automatically reads Claude Code marketplaces, plugins, skills, MCPs, agents, hooks, and instruction files". They list the user-level ~/.agents/skills but, as of September 2026, say nothing about a repo's .agents/skills.
• Claude Code reads neither of the others. A skill that exists only in ~/.agents/skills is invisible to it.

So the smallest setup that reaches all four is two folders: ~/.claude/skills and ~/.agents/skills. People often assume "this is a Claude skill" when a Claude skill is also a Grok skill, and an .agents skill is a Codex, Gemini and Grok skill.

One consequence: Grok can find a skill you put in both folders twice, and its docs do not say which copy wins a name clash. Codex's docs say same-named skills from different locations are not merged, and both can appear in its skill picker. If both entries are symlinks to the same folder, it does not matter, because both lead to the same file. If they are copies that have drifted apart, you cannot tell which instructions Grok followed.

Should you copy the skill or symlink it?#

Symlink it.

Copying looks simpler and goes wrong the day after. You fix a step in ~/.claude/skills/deploy/SKILL.md, forget the copy in ~/.agents/skills/deploy/, and now Claude Code and Codex follow different procedures under the same name. Nothing errors. And to anyone opening those folders later, a copy looks exactly like a skill somebody wrote there by hand.

A symlink is one folder with several doorways into it. Claude Code's docs say an entry in the personal or project location "can be a symlink to a directory elsewhere on disk", and that it loads the skill once even when several locations point at the same target. Codex's docs say it "supports symlinked skill folders and follows the symlink target". Gemini CLI ships a /skills link <path> command for the same job. A link also documents itself: ls -l ~/.claude/skills shows where the real skill lives.

Four traps when you scan skill folders#

We built a scanner that reads all of these folders on a Mac. A naive find ~ -name SKILL.md gets four things wrong, and each mistake produces an answer that looks believable.

1. A plugin marketplace is a catalogue, not your skills#

~/.claude/plugins/marketplaces/ holds every skill in every marketplace you have added, installed or not. On one Mac we scanned it held 31 SKILL.md files, with exactly one plugin actually installed. That one plugin carried no skills. Counting that folder reports thirty skills you cannot invoke. The real list is ~/.claude/plugins/installed_plugins.json, where each entry names its own install path.

2. Codex's bundled skills hide in a dotfolder#

On the Macs we checked, the skills that ship with Codex were unpacked into ~/.codex/skills/.system. Any tool that skips dotfolders, which is the normal rule for a directory listing, misses them. On one machine those six were the only skills it had. Claude Code has a second tier of its own too: ~/.claude/skills/synced, the mirror of skills from your claude.ai account. It is a folder of skills, not a skill. Claude Code reserves the name, so never call one of your skills synced.

3. One skill, three listings#

~/.agents/skills can itself be a symlink to ~/.claude/skills. Walk both by name and every skill appears twice, or three times if a repo links it again. Resolve real paths (realpath) before you count or edit anything. Otherwise you get three "different" skills that are all one file.

4. The folder name is the command name#

In Claude Code, /deploy-staging comes from the folder name, not from the name field, except in plugins. The spec requires the two to match anyway. That has two consequences:

• Linking over an existing folder is a takeover, not a merge. If ~/.claude/skills/deploy already exists and you replace it, /deploy now runs your skill instead of the old one. Check for the name before you create a link, and refuse rather than overwrite.
• Renaming a skill means moving its links. Rename deploy to ship and leave the old link in place, and /deploy still exists while /ship does not. Nothing errors.

A fifth trap, for teams: never put a symlink into your home directory inside a repository's .claude/skills or .agents/skills. It works on your machine and is a broken skill for everyone who clones the repo. Project skills should be real folders committed to the repo. Symlinks belong only in personal folders.

What should you check in allowed-tools before adopting someone else's skill?#

Most frontmatter describes what a skill is about. allowed-tools describes what it will do. The spec defines it as "a space-separated string of tools that are pre-approved to run", marked experimental. In Claude Code it pre-approves those tools for the turn that runs the skill, so the agent does not stop to ask:

allowed-tools: Bash(git:*) Bash(curl:*) Read Write

Before you drop a skill from GitHub or a marketplace into your folders, read three things:

1. allowed-tools. Bash(git:*) is narrow. A bare Bash pre-approves any shell command.
2. Injected commands. In Claude Code, a line like !`git diff HEAD` in a skill runs before the model sees the skill, and its output is pasted in.
3. scripts/. The instructions may tell the agent to run these, so read them the way you would read any script from a stranger.

Gemini CLI asks for confirmation when it activates a skill. That prompt is a good habit to copy for the other runtimes, which do not all ask.

How to share skills between Claude Code and Codex (and Gemini and Grok)#

By hand, with a short script#

Keep your skills in one folder you control, for example ~/skills, and link each one into the two shared folders:

#!/usr/bin/env bash
# publish-skill.sh <skill-folder-name>
set -euo pipefail
name="$1"
src="$HOME/skills/$name"

[ -f "$src/SKILL.md" ] || { echo "no SKILL.md in $src"; exit 1; }

for dir in "$HOME/.claude/skills" "$HOME/.agents/skills"; do
  mkdir -p "$dir"
  dest="$dir/$name"
  if [ -L "$dest" ] && [ "$(readlink "$dest")" = "$src" ]; then
    echo "already linked: $dest"
  elif [ -e "$dest" ] || [ -L "$dest" ]; then
    echo "refusing: $dest exists and is not ours"   # never take over a command
  else
    ln -s "$src" "$dest" && echo "linked: $dest"
  fi
done

Two maintenance commands to go with it:

# links whose target is gone (a deleted or renamed skill)
find ~/.claude/skills ~/.agents/skills -maxdepth 1 -type l ! -exec test -e {} \; -print

# what each shared folder actually points at
ls -l ~/.claude/skills ~/.agents/skills

If ~/.agents/skills is already a symlink to ~/.claude/skills on your machine, the second link is redundant, and the script reports it as already linked. Then check in Grok's /skills list that nothing appears twice.

How Universe does it#

Universe is a Mac app that runs Claude Code, Codex, Gemini and Grok on the model accounts or keys you already have. Its Skills page does both halves of the job described above:

• It reads the skills already on your Mac. That covers ~/.claude/skills (including installed plugins and claude.ai-synced skills), ~/.agents/skills, ~/.codex/skills (including Codex's bundled system skills), ~/.gemini/skills, ~/.grok/skills, and the .claude/skills and .agents/skills folders of repos Universe already knows about. Each skill shows which runtimes read it. The scan is read-only.
• You can copy a personal or project skill into Universe. Its allowed-tools are shown before the copy. Plugin, synced and admin-managed skills are shown but not offered for copy, because they are maintained somewhere else and a copy would stop receiving updates.
• It publishes a Universe skill back out as a symlink into ~/.claude/skills and/or ~/.agents/skills, the two folders that reach all four agents. Edits are live everywhere at once. It never overwrites an existing skill of the same name, and it only writes to personal folders, never into a repo.

When an agent proposes a change to a skill you own, the change waits until a person accepts it.

Where it fits, honestly. If you use one CLI, or you are comfortable with the script above, you do not need an app for this. Twenty lines of bash do the linking. Universe helps when you switch between several agents (see running Claude Code, Codex, Gemini and Grok in one app). It also helps when you want to see what is already on a machine across every runtime, or when you share skills with people rather than only with your own agents. It is macOS only (Apple silicon or Intel, macOS 13 or later), it needs your own model account, and every plan, including the free one, has skills. See pricing, or download it.

If you are wiring Universe's tools or your own MCP servers into Codex as well, the approval setting catches most people out: fixing "MCP tool call requires approval".

Common questions about sharing skills#

Do skills cost context?#

Only a little until one is used. Every runtime here loads names and descriptions up front and reads the rest on activation. The spec estimates about 100 tokens of metadata per skill. Codex caps the whole skill list at 2% of the context window or 8,000 characters. Claude Code truncates a description (with when_to_use) at 1,536 characters. Setting disable-model-invocation: true removes a skill's description from Claude Code's context entirely, so only you can run it. Fifty skills with sloppy, long descriptions add up, so keep descriptions specific and short.

Why is a skill not showing up?#

Work down this list:

1. The file is named exactly SKILL.md, and its --- frontmatter starts on line one.
2. The folder is in a path that runtime reads. Check the table above; ~/.agents/skills does nothing for Claude Code.
3. The frontmatter parses. A description containing a colon needs quotes, or the YAML is invalid.
4. No same-named skill in a higher-precedence location is hiding it. In Claude Code, enterprise beats personal and personal beats project.
5. The session started before the skill existed. Restart it, or run /skills reload in Gemini CLI.
6. For a symlink, the target still exists. ls -l shows a broken link in red on most terminals.