Codex skills: how they load, and sharing them with Claude Code and Cursor

What is a Codex skill?

A packaged, repeatable job: the steps, and any scripts or reference files they need. The folder holds a SKILL.md with two required fields, name and description, and can add scripts/, references/, assets/ and an agents/openai.yaml for Codex-only settings. Skills follow the Agent Skills open standard, so the format is the same one Claude Code, Cursor and Copilot read.

At the start of a session the model sees only a list: each skill's name, description and path. The list gets at most 2 percent of the model's context window, or 8,000 characters when the window is unknown. When there are more skills than fit, the docs say Codex “shortens skill descriptions first” and may leave some skills out. The full SKILL.md is read only when the skill is used.

Where does Codex look for skills?

Four details decide whether a skill shows up. A skill in services/payments/.agents/skills is listed only when you start Codex in that service, not at the root (tested). Codex still reads the older ~/.codex/skills, and in our test also a project .codex/skills, which the docs do not list; do not build on that. Two skills with the same name are not merged, and both can appear. And unlike AGENTS.md, skills still load in a project marked untrusted (tested), which does not hold for AGENTS.md.

How do you write a SKILL.md for Codex?

A skill that adds a payments webhook handler:

.agents/skills/add-webhook-handler/
├── SKILL.md
└── scripts/
    └── scaffold.sh

---
name: add-webhook-handler
description: Scaffold a payments webhook handler with its job and test.
  Use when asked to handle a new webhook event.
---

1. Run scripts/scaffold.sh <event-name>.
2. Put the work in jobs/<event-name>.ts. The handler only checks
   the signature, enqueues the job and returns 200.
3. Run pnpm test payments.

The description does the routing, so say what the skill does and when to use it, in the words a request would use. Codex uses name and description and ignores keys it does not know, including Claude Code's. Keep the name lowercase with hyphens, at most 64 characters, and the same as the folder: Codex does not require the match, but the standard and Cursor do.

How do you run a skill in Codex?

Two ways. Codex picks a skill on its own when the task matches the description. Or you name it: type $ and the skill name, use /skills, or since 0.140.0 type @ for the menu of files, plugins and skills.

To keep Codex from choosing a skill by itself, set this in the skill's agents/openai.yaml:

policy:
  allow_implicit_invocation: false

That takes the skill off the list the model sees (tested). The docs say $name still works; open issue #23454 reports cases where it does not. To switch a skill off entirely, add a [[skills.config]] entry with its path and enabled = false to ~/.codex/config.toml, and restart Codex.

Can Codex, Claude Code and Cursor share one skills folder?

Not as one folder. Each tool reads its own list, and no folder is on all four lists:

Sources: Claude Code skills, Cursor skills, Copilot agent skills. Claude Code is the gap: the request to read .agents/skills, #16345, has been open since 2026-01-05. Codex does not read .claude/skills (tested).

So keep the skills in .agents/skills and link each one into .claude/skills. Claude Code's docs say a skill folder can be a symlink, and Codex follows symlinks too:

mkdir -p .claude/skills
for s in .agents/skills/*/; do
  ln -s "../../$s" ".claude/skills/$(basename "$s")"
done

Two traps remain. Cursor and Copilot read both folders, so check that each skill shows up once. And the tools do not share their extra settings. Codex ignores Claude's disable-model-invocation: true, so a skill you hid from Claude's model is on Codex's list (tested); give it the agents/openai.yaml above as well. More on the Claude side in Claude Code skills.

Why won't my Codex skill trigger?

To see the list exactly as the model gets it, run codex debug prompt-input "hi" from your usual folder and search the output for the skill's name.

How should a team share Codex skills?

In the repository, in .agents/skills, reviewed like code. To distribute skills beyond one repository, OpenAI's docs say “prefer plugins”, and its openai/skills catalog has carried a deprecation notice since June pointing to the plugins repository. Keeping copies current is the open problem. In the Ask HN thread on managing skills files (320 points, September), one engineer put it as “The biggest problem is keeping skills up to date across users”.

Part of that problem is what goes into a skill. Look at step 2 of the example: “The handler only checks the signature, enqueues the job and returns 200.” That is not a step. It is a decision the team made in #eng-payments, copied into a skill. When the team changes it, every skill, AGENTS.md and prompt that carries a copy is wrong until someone finds it. A skill is the right home for how to do a job. What the team decided needs a home with an owner and a date.

Where Harbor fits

Harbor is that home for engineering decisions. It reads them where they are made, in Slack threads, pull request reviews and docs. A person approves each one, or a policy you set approves the routine ones, and Harbor serves the ones that apply to the task to Codex, Claude Code and Cursor at session start. A skill can then say “follow the team's webhook rule” and stay correct when the rule changes. Each rule shows how often it was served and how often an answer cited it; a cite is evidence that a rule was used, not proof that it was obeyed. The method is in served vs cited.