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

OpenAI's Codex loads skills from a SKILL.md file in .agents/skills folders, capping the initial skill list at 2 percent of the model's context window or 8,000 characters when the window is unknown, according to OpenAI's skills docs and the Codex 0.160.1 source read on October 6, 2026. Codex lists skills by name and description and reads the full SKILL.md only when a task matches or a user types $name, while Claude Code does not read the .agents/skills folder, so teams using both need one symlink per skill. Skills follow the Agent Skills open standard shared with Claude Code, Cursor and Copilot, and Codex 0.140.0 added @ for a menu of files, plugins and skills.

Blog Codex skills: how they load, and sharing them with Claude Code and Cursor Published: October 6, 2026 A Codex skill is a folder with a SKILL.md file. Codex lists your skills by name and description, and reads the full file only when a task matches or you type $name . It looks in .agents/skills from your folder up to the repository root. Claude Code does not read that folder, so a team on both needs one symlink per skill. Facts about Codex are from OpenAI's skills docs https://learn.chatgpt.com/docs/build-skills and the Codex 0.160.1 source, read 2026-10-06. The ones marked tested were run on Codex 0.155.1 in a scratch repository. 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 https://agentskills.io/specification 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? | Scope | Folder | Use it for | |---|---|---| | Repository | .agents/skills in every folder from where you start Codex up to the repository root | Skills the team checks in, per repo or per service | | User | ~/.agents/skills | Your own skills, in every repo | | Admin | /etc/codex/skills | Defaults for every user of a machine or container | | System | Bundled with Codex | skill-creator, skill-installer and a few more | 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 https://gethrbr.com/blog/why-codex-ignores-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 https://github.com/openai/codex/issues/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: | Tool | Project folders it reads | Run one by name | |---|---|---| | OpenAI Codex | .agents/skills | $name , /skills , @ | | Claude Code | .claude/skills only | /name | | Cursor | .agents/skills , .cursor/skills , and for compatibility .claude/skills and .codex/skills | / in Agent chat | | GitHub Copilot | .github/skills , .claude/skills , .agents/skills | /name in the CLI | Sources: Claude Code skills https://code.claude.com/docs/en/skills , Cursor skills https://cursor.com/docs/skills , Copilot agent skills https://docs.github.com/en/copilot/concepts/agents/about-agent-skills . Claude Code is the gap: the request to read .agents/skills , 16345 https://github.com/anthropics/claude-code/issues/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 https://gethrbr.com/blog/claude-code-skills . Why won't my Codex skill trigger? | Cause | Check | Fix | |---|---|---| | Wrong folder | Is it in .agents/skills on the path from your folder to the root? | Move it, or start Codex where it lives | | Description too vague or cut | Many skills? Descriptions are shortened first | Name the task and the trigger words in the first sentence | | Implicit use is off | allow implicit invocation in agents/openai.yaml | Call it with $name | | Disabled | skills.config in ~/.codex/config.toml | Remove the entry and restart | | Change not picked up | /skills | Restart Codex | 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 https://github.com/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 https://news.ycombinator.com/item?id=49589914 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 https://gethrbr.com/blog/served-vs-cited . Questions Where does Codex look for skills? In .agents/skills in every folder from where you start Codex up to the repository root, in ~/.agents/skills for your own skills, in /etc/codex/skills for a whole machine, and in the skills bundled with Codex. It still reads the older ~/.codex/skills. How do I use a skill in Codex? Codex picks a skill when the task matches its description, or you name it: type $ and the skill name, run /skills, or use the @ menu. Setting allow implicit invocation: false in the skill's agents/openai.yaml stops Codex choosing it on its own. Does Claude Code read Codex skills? Not from .agents/skills, the folder Codex uses; Claude Code reads .claude/skills. Keep skills in .agents/skills and symlink each skill folder into .claude/skills. Cursor and Copilot read both folders. Why is my Codex skill not triggering? Usually it sits in a folder Codex does not scan, such as .claude/skills or a service folder below where you started, its description is vague or was shortened because many skills share a small budget, or implicit use is turned off. Restart Codex if a change does not show up. What is the difference between a Codex skill and AGENTS.md? AGENTS.md is loaded at the start of every session. A skill is listed by name and description and read in full only when it is used. Put facts that are always true in AGENTS.md and repeatable jobs in skills, and keep each team decision in one place rather than copied into both.