{"slug": "codex-skills-how-they-load-and-sharing-them-with-claude-code-and-cursor", "title": "Codex skills: how they load, and sharing them with Claude Code and Cursor", "summary": "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.", "body_md": "Blog\n\n# Codex skills: how they load, and sharing them with Claude Code and Cursor\n\nPublished: October 6, 2026\n\nA 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.\n\nFacts 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.\n\n## What is a Codex skill?\n\nA 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.\n\nAt 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.\n\n## Where does Codex look for skills?\n\n| Scope | Folder | Use it for | \n|---|---|---|\n| 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 | \n| User | `~/.agents/skills` | Your own skills, in every repo | \n| Admin | `/etc/codex/skills` | Defaults for every user of a machine or container | \n| System | Bundled with Codex | skill-creator, skill-installer and a few more | \n\nFour 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).\n\n## How do you write a SKILL.md for Codex?\n\nA skill that adds a payments webhook handler:\n\n```\n.agents/skills/add-webhook-handler/\n├── SKILL.md\n└── scripts/\n    └── scaffold.sh\n\n---\nname: add-webhook-handler\ndescription: Scaffold a payments webhook handler with its job and test.\n  Use when asked to handle a new webhook event.\n---\n\n1. Run scripts/scaffold.sh <event-name>.\n2. Put the work in jobs/<event-name>.ts. The handler only checks\n   the signature, enqueues the job and returns 200.\n3. Run pnpm test payments.\n```\n\nThe 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.\n\n## How do you run a skill in Codex?\n\nTwo 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.\n\nTo keep Codex from choosing a skill by itself, set this in the skill's `agents/openai.yaml`:\n\n```\npolicy:\n  allow_implicit_invocation: false\n```\n\nThat 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.\n\n## Can Codex, Claude Code and Cursor share one skills folder?\n\nNot as one folder. Each tool reads its own list, and no folder is on all four lists:\n\n| Tool | Project folders it reads | Run one by name | \n|---|---|---|\n| OpenAI Codex | `.agents/skills` | `$name` ,`/skills` ,`@` | \n| Claude Code | `.claude/skills` only | `/name` | \n| Cursor | `.agents/skills` ,`.cursor/skills` , and for compatibility`.claude/skills` and`.codex/skills` | `/` in Agent chat | \n| GitHub Copilot | `.github/skills` ,`.claude/skills` ,`.agents/skills` | `/name` in the CLI | \n\nSources: [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).\n\nSo 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:\n\n```\nmkdir -p .claude/skills\nfor s in .agents/skills/*/; do\n  ln -s \"../../$s\" \".claude/skills/$(basename \"$s\")\"\ndone\n```\n\nTwo 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).\n\n## Why won't my Codex skill trigger?\n\n| Cause | Check | Fix | \n|---|---|---|\n| Wrong folder | Is it in `.agents/skills` on the path from your folder to the root? | Move it, or start Codex where it lives | \n| Description too vague or cut | Many skills? Descriptions are shortened first | Name the task and the trigger words in the first sentence | \n| Implicit use is off | `allow_implicit_invocation` in`agents/openai.yaml` | Call it with `$name` | \n| Disabled | `[[skills.config]]` in`~/.codex/config.toml` | Remove the entry and restart | \n| Change not picked up | `/skills` | Restart Codex | \n\nTo 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.\n\n## How should a team share Codex skills?\n\nIn 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”.\n\nPart 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.\n\n## Where Harbor fits\n\nHarbor 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).\n\n## Questions\n\n### Where does Codex look for skills?\n\nIn .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.\n\n### How do I use a skill in Codex?\n\nCodex 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.\n\n### Does Claude Code read Codex skills?\n\nNot 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.\n\n### Why is my Codex skill not triggering?\n\nUsually 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.\n\n### What is the difference between a Codex skill and AGENTS.md?\n\nAGENTS.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.", "url": "https://wpnews.pro/news/codex-skills-how-they-load-and-sharing-them-with-claude-code-and-cursor", "canonical_source": "https://gethrbr.com/blog/codex-skills", "published_at": "2026-10-06 00:00:00+00:00", "updated_at": "2026-10-06 08:48:36.914295+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "agent-protocols"], "entities": ["OpenAI", "Codex", "Claude Code", "Cursor", "Copilot", "Agent Skills"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/codex-skills-how-they-load-and-sharing-them-with-claude-code-and-cursor", "markdown": "https://wpnews.pro/news/codex-skills-how-they-load-and-sharing-them-with-claude-code-and-cursor.md", "text": "https://wpnews.pro/news/codex-skills-how-they-load-and-sharing-them-with-claude-code-and-cursor.txt", "jsonld": "https://wpnews.pro/news/codex-skills-how-they-load-and-sharing-them-with-claude-code-and-cursor.jsonld"}}