Codex vs Claude Code skills: SKILL.md paths, /name vs $name

Claude Code reads a skill from .claude/skills/<name>/SKILL.md and runs it when you type /name; Codex reads .agents/skills and runs one when you “type $ to mention a skill,” per OpenAI's docs read October 23, 2026. Both also pick a skill on their own when your request matches its description.

Anthropic's and OpenAI's skills docs were read on October 23, 2026, for Claude Code 2.1.308 (published to npm on October 22, 2026) and Codex CLI 0.163.0 (released October 15, 2026). The docs pages carry no date of their own, so the dates on this page come from each vendor's changelog: Claude Code added skills in 2.0.20, published October 16, 2025, and Codex's changelog announces “Agent skills in Codex” on December 19, 2025. No skill was run in either tool for this post. Where a vendor's docs are silent, this page says so.

Codex vs Claude Code skills, side by side

Both tools use the same Agent Skills format: a folder with a SKILL.md file, YAML front matter on top, Markdown instructions below. Anthropic's docs say “Claude Code skills follow the Agent Skills open standard,” and OpenAI's say “Skills build on the open agent skills standard.” The folders, the way you call a skill, and the extra settings differ.

From Anthropic's skills page and OpenAI's Build skills page, both read October 23, 2026.

Yes or no: what each tool does

These are the questions that decide where a skill goes and whether it carries over.

Where SKILL.md goes in Claude Code

Claude Code loads a skill from wherever its folder sits, and the folder name becomes the command. .claude/skills/deploy-staging/SKILL.md runs as /deploy-staging, or as /deploy if the front matter says name: deploy.

• Personal: ~/.claude/skills/<name>/SKILL.md loads in all your projects on that machine.
• Project: .claude/skills/<name>/SKILL.md, committed, loads for everyone who works in the repository.
• Nested: <subdir>/.claude/skills/ loads when you start inside <subdir>, or once Claude reads or edits a file there.
• Plugin: <plugin>/skills/<name>/SKILL.md runs as /plugin-name:skill-name, so it never collides with yours.
• Enterprise: .claude/skills/ inside the managed settings directory, for every user where your organization deploys it.

Starting Claude Code in packages/frontend/ still picks up the skills at the repository root, because it searches every parent folder up to the root. When the same name exists twice, enterprise beats personal and personal beats project: with deploy in both ~/.claude/skills/ and the project, /deploy runs your personal one.

One gap trips people up. Cowork sessions and cloud sessions “don't read ~/.claude/skills/ on your machine.” To use a personal skill there, enable it on your claude.ai account. That upload accepts only the 6 front matter fields of the Agent Skills spec, and any other field fails with Unexpected key(s) in SKILL.md frontmatter.

Claude Code watches the skill folders, so editing SKILL.md in an existing folder applies in the same session. If you create a top-level skills folder that didn't exist when the session started, run /reload-skills.

Where SKILL.md goes in Codex

Codex reads skills from 4 kinds of locations. For a repository, it “scans .agents/skills in every directory from your current working directory up to the repository root.”

• Repository: .agents/skills in the current folder, its parents, and the repository root.
• User: $HOME/.agents/skills, for every repository you work in.
• Admin: /etc/codex/skills, shared by every user on the machine or container.
• System: skills bundled with Codex, such as $skill-creator.

Older guides point somewhere else. Codex's changelog entry of December 19, 2025 told you to install skills in ~/.codex/skills, or .codex/skills for a project. Today's docs list neither. This post didn't test whether 0.163.0 still reads them, so new skills belong in .agents/skills.

To install a skill someone else wrote, run $skill-installer. OpenAI's example, $skill-installer linear, installs a $linear skill. To switch one off without deleting it, add this to ~/.codex/config.toml and restart Codex:

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Front matter: what each tool requires

The Agent Skills spec requires 2 fields. name is up to 64 characters of lowercase letters, numbers, and hyphens, and must match the folder name. description is up to 1,024 characters and “Should describe both what the skill does and when to use it.” The spec also allows license, compatibility, metadata, and an experimental allowed-tools.

Codex follows the spec's 2 required fields. Claude Code requires nothing, falls back to the folder name for name and the first line of the body for description, and “ignores a field it doesn't recognize without reporting an error.” Each tool then adds its own settings in a different place:

• Claude Code puts them in the front matter: when_to_use, argument-hint, arguments, disable-model-invocation, user-invocable, allowed-tools, disallowed-tools, model, effort, context, agent, background, hooks, paths, and shell.
• Codex puts them in agents/openai.yaml next to SKILL.md: how the skill looks in the ChatGPT desktop app, the invocation policy, and the MCP servers it depends on.

A SKILL.md with only spec fields is valid in both. This example was written for this post and wasn't run in either tool:

---
name: release-notes
description: Drafts release notes from merged pull requests. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---

1. List the pull requests merged since the last tag.
2. Group them under Added, Changed, and Fixed.
3. Write one line per change, in the past tense.

Put Claude Code-only fields such as disable-model-invocation in a skill only Claude Code reads. OpenAI's docs don't say what Codex does with fields it doesn't know.

How a skill gets called: /name, $name, or on its own

Claude Code. Type the name with a slash at the start of your message: /deploy staging runs the skill and passes staging as its arguments. Write the same name after other words, as in “go ahead and /deploy to staging,” and “Nothing runs directly.” The name then counts as your permission for that message, and Claude decides from your wording whether to run it. Claude also loads a skill by itself when your request matches its description.

Two front matter fields change who can call it. disable-model-invocation: true means only you can, which Anthropic suggests for skills with side effects: “You don't want Claude deciding to deploy because your code looks ready.” user-invocable: false means only Claude can, which suits background knowledge that isn't a command. Permission rules work too: Skill(deploy *) in your deny rules blocks that skill.

Codex. In the CLI or the IDE extension, “run /skills or type $ to mention a skill.” In ChatGPT, type @ instead. Codex also picks a skill when your task matches its description. To keep it from doing that, add this to the skill's agents/openai.yaml. A $name call still works:

policy:
  allow_implicit_invocation: false

Sharing a skill: personal, project, and plugin

Both tools follow the same pattern: your home folder for yourself, a committed folder for the repository, and a plugin for everyone else.

OpenAI distributes plugins “through the universal plugin directory shared by ChatGPT and Codex.” Plugins work in Chat and Work across ChatGPT, in Codex in the ChatGPT desktop app, and in Codex CLI, but “They aren't available in the IDE extension.” Codex's old custom prompts “live in your local Codex home directory (for example, ~/.codex), so they're not shared through your repository,” which is why OpenAI points you to skills instead.

Using one skill in both tools (and in Gemini CLI, Cursor, and Copilot)

Neither vendor's docs say its tool reads the other's folder. Other agents read more than one folder, though, and .agents/skills is the one most of them share:

From each vendor's docs, read October 23, 2026: Anthropic's skills page, OpenAI's Build skills page, Gemini CLI's Agent Skills page, Cursor's Agent Skills page, and GitHub's Agent skills page.

For a repository where some people use Claude Code and others use Codex, 2 routes follow from the docs:

1. Keep one copy and link it. Both tools follow symlinked skill folders. Anthropic's docs say a skill entry “can be a symlink to a directory elsewhere on disk,” and OpenAI's say “Codex supports symlinked skill folders.” Keep the skill in .agents/skills/<name>/ and link it from .claude/skills/. This wasn't tested in either tool for this post:

mkdir -p .claude/skills
ln -s ../../.agents/skills/release-notes .claude/skills/release-notes

2. Import once into Codex. Codex CLI's /import reads your Claude Code setup and turns its skills and slash commands into Codex skills, and its hooks into Codex hooks. OpenAI asks you to review “Tool restrictions or permissions in imported skills and agents” afterwards. OpenAI describes automatic updates of imported work only for the ChatGPT desktop app, so treat a CLI import as a one-time copy.

Cursor and Copilot read both folders. Their pages don't say what happens when the same skill sits in both, so check their skill lists after you add the link. GitHub also notes that the folders Copilot reads depend on where you use it.

When a skill doesn't trigger

Both tools pick a skill from a list of names and descriptions that sits in the context on every turn. When that list runs out of space, descriptions get cut, and a skill without its keywords stops matching.

• Claude Code gives the list 1% of the context window and cuts each entry's description and when_to_use at 1,536 characters. When the list overflows, it drops descriptions “starting with the skills you invoke least.” Run /doctor for the list's size, and /skill-doctor for each skill's cost and how often it was used. The skills page says /skill-doctor needs v2.1.252 or later; the changelog lists it under 2.1.261.
• Codex gives the list 2% of the context window. With many skills it “shortens skill descriptions first” and may leave some out of the list with a warning. skills.max_context_tokens raises the budget to at most 10,000 tokens.

Both vendors say to put the main use case first. OpenAI: “Front-load the key use case and trigger words so a host can still match the skill if descriptions are shortened.”

Anthropic lists these checks when Claude Code skips a skill:

1. The description includes words people would say.
2. The skill shows up when you ask What skills are available?
3. A request phrased closer to the description triggers it.
4. /skill-name runs it.

If /skill-name works and automatic use doesn't, the front matter may not parse. Claude Code then “loads the skill body with empty metadata,” so there's no description to match. claude plugin validate .claude/skills (v2.1.233 or later) finds SKILL.md files whose front matter doesn't parse. In Codex, run /skills to see whether the skill is in the list at all.

Skills next to hooks, subagents, and MCP

A skill is instructions the model reads when it needs them, and the model can still skip a step. For a rule that must hold every time, Anthropic says to “move the rule into a hook,” which Claude Code runs on every matching event whether or not Claude follows the skill. Claude Code hooks: how to block a command before it runs shows one hook, tested case by case.

A subagent is a separate worker with its own context. In Claude Code, a skill can start one with context: fork, and the subagent “doesn't see your conversation history,” so the skill must stand on its own. Limits and config for both tools are in Codex vs Claude Code subagents.

MCP connects a skill to outside tools. OpenAI puts it this way: “skills define repeatable workflows, and MCP connects them to external tools and systems.” A Codex skill can declare the MCP server it needs under dependencies.tools in agents/openai.yaml. When the workflow's last step is putting a page online, an MCP server such as Convika's (https://mcp.convika.com) saves the page Claude Code or Codex wrote and returns a private preview link before anything goes live. See how to connect it from Claude Code or Codex.

Frequently asked questions

Where do I put SKILL.md for Codex?

Put it in .agents/skills/<name>/SKILL.md in your repository, or in $HOME/.agents/skills to use the skill in every repository. Codex scans .agents/skills in the current folder and each parent up to the repository root, plus /etc/codex/skills and its bundled skills. Codex's changelog of December 19, 2025 named ~/.codex/skills and .codex/skills, and today's docs list neither.

Can Codex use my Claude Code skills?

Yes, through /import. In a local Codex CLI session, type /import, choose Claude Code, and pick what to bring over. OpenAI's import page says skills and slash commands become Codex skills and hooks become Codex hooks. .claude/skills isn't in OpenAI's list of the folders Codex reads, and OpenAI describes automatic updates of imported work only for the ChatGPT desktop app, so import again after you change a skill.

Can Claude Code use a skill from .agents/skills?

Yes, through a symlink. Anthropic's list of locations doesn't include .agents/skills, but a skill entry in .claude/skills/ “can be a symlink to a directory elsewhere on disk.” Link .claude/skills/<name> to ../../.agents/skills/<name> and keep the front matter to spec fields so both tools accept it. This route wasn't tested for this post.

How do I call a skill in Codex?

Type $ followed by the skill's name, or run /skills and pick it, in the CLI or the IDE extension. In ChatGPT, type @. Codex also picks a skill by itself when your task matches the skill's description, unless agents/openai.yaml sets policy.allow_implicit_invocation: false.

Is name required in SKILL.md?

Yes in Codex, no in Claude Code. Codex's docs say “The SKILL.md file must include name and description,” as the Agent Skills spec does. Claude Code makes every field optional, uses the folder name when name is missing, and recommends only description. Write both if the skill may be used anywhere besides Claude Code.

Can I stop Claude Code or Codex from using a skill on its own?

Yes. In Claude Code, add disable-model-invocation: true to the front matter: the description leaves the context and only /name runs the skill. In Codex, add policy.allow_implicit_invocation: false to the skill's agents/openai.yaml. A $name call still works.

Does allowed-tools restrict which tools a skill can use?

No. In Claude Code, allowed-tools lets the listed tools run without asking during the turn that calls the skill, and Anthropic's docs say “It does not restrict which tools are available.” To keep a tool away while a skill runs, list it in disallowed-tools, or add a deny rule to your permission settings. OpenAI's skills docs don't list allowed-tools.

Is a skill the same as a custom slash command?

Yes, in how you call it in Claude Code. Anthropic's docs say “Custom commands have been merged into skills”: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, and the skill wins if both exist. A skill adds a folder for supporting files and the choice of who can call it. In Codex, custom prompts are “deprecated,” and OpenAI points to skills instead.

Do skills use up context when I don't call them?

Yes, their list does. Both tools keep every skill's name and description in the context and load the full SKILL.md only when the skill is used. Claude Code caps the list at 1% of the context window and Codex at 2% by default. Removing skills you never use leaves room for the descriptions of the ones you do.

Can a skill run in a subagent?

Yes in Claude Code. Add context: fork and an agent type to the front matter, and Claude Code starts that subagent with the skill as its prompt. The subagent “doesn't see your conversation history,” and it runs in the background unless you set background: false (v2.1.218 or later). OpenAI's skills docs don't describe running a skill in a subagent.

Sources

• Claude Code Docs: Extend Claude with skills (checked 2026-10-23)
• Claude Code changelog (checked 2026-10-23)
• npm: @anthropic-ai/claude-code release dates (checked 2026-10-23)
• Agent Skills: Specification (checked 2026-10-23)
• Codex Docs: Build skills (checked 2026-10-23)
• Codex Docs: Skills & Plugins (checked 2026-10-23)
• Codex Docs: Skill controls (checked 2026-10-23)
• Codex Docs: Customization (checked 2026-10-23)
• Codex Docs: Custom Prompts (checked 2026-10-23)
• Codex Docs: Import from another agent (checked 2026-10-23)
• Codex Docs: Configuration reference (checked 2026-10-23)
• Codex changelog (checked 2026-10-23)
• openai/codex release rust-v0.163.0 (checked 2026-10-23)
• Gemini CLI Docs: Agent Skills (checked 2026-10-23)
• Cursor Docs: Agent Skills (checked 2026-10-23)
• GitHub Docs: Agent skills (checked 2026-10-23)