SKILL.md Portability: A Technical Look at Claude Code vs. Codex CLI

The SKILL.md format is a simple, powerful standard for extending the capabilities of coding agents. Both Anthropic’s Claude Code and OpenAI’s Codex CLI support it. This leads to a critical question for developers: does the same SKILL.md file run on both? The simple answer is yes, the file itself is portable. The useful answer is more complex, and it has less to do with the file format and more to do with the execution environment each agent provides.

At SkillProof, we install and run Claude Code skills on real work to see if they pass. We publish the results, including failures. Of 2090 skills tested in a Claude Code harness, 1291 passed (62%), 697 delivered only after configuration the listing has to spell out for you, and 102 landed on a fails verdict: some ran and left you worse off than no skill at all, others could not run at all because of a missing CLI, a dead dependency, or an example that crashes. We have never run a skill on Codex CLI. Our entire dataset is based on Claude Code execution.

However, our test corpus contains a unique, one-directional set of evidence. This article examines the technical differences between how the two agents handle SKILL.md and what our Claude-only data reveals about portability from Codex to Claude.

The Common Ground: The SKILL.md Format

Before comparing the agents, it’s essential to understand what a SKILL.md file is. It’s a text file that combines instructions for the agent with metadata. The structure is straightforward:

1. YAML Frontmatter: A block at the top of the file, fenced by ---, contains key-value pairs. name and description are fundamental. The agent uses the description to decide when to invoke the skill. An optional allowed-tools key names tools the skill wants pre-approved so it does not stop to ask mid-run. It is a convenience field, not a sandbox: it does not take tools away from the model. You can find a detailed breakdown in our frontmatter reference.
2. Markdown Body: Below the frontmatter is the instruction set for the agent, written in plain markdown. This tells the model how to accomplish the task, step by step.
3. Bundled Files: A skill can include other files, like scripts or reference data, which are packaged with it.

Crucially, SKILL.md contains no function signatures or argument schemas. It is a natural language instruction format, not a structured function-calling manifest. That is the domain of MCP, a separate and distinct protocol. For a deeper dive on this, see our comparison of Claude Skills vs. MCP.

Because SKILL.md is just structured text, any compliant parser can read it. Both Claude Code and Codex CLI can load the same file without modification. The difference is what happens next.

Loading and Execution: Two Different Environments

While the file is the same, the context in which it runs is not. The agent’s architecture, default settings, and available tooling define the execution environment. This is where the practical differences between Claude Code and OpenAI Codex emerge.

Claude Code

In our work, we test exclusively with Claude Code. Skills are loaded from ~/.claude/skills for personal skills and .claude/skills inside a project for repo-scoped ones. When you give the agent a task, it matches your prompt against the description field of all available skills. You can also call one directly by name with a slash command.

One critical behavior we’ve documented is its failure mode. If the YAML frontmatter in a SKILL.md file is malformed—a misplaced tab, a missing quote—Claude Code does not produce a validation error. The skill simply becomes invisible to the agent. It won’t be listed, and it will never be triggered. This silent failure can be difficult to debug, a topic we cover in our post on what to do when a skill isn’t triggering.

Our methodology involves running each skill against a real-world task. The results from our 2090 tests show that a ‘pass’ is not guaranteed. The 697 skills that landed on ‘setup’ required non-trivial configuration that we had to document. The 102 ‘fails’ either could not run at all due to missing dependencies or produced an outcome worse than not using a skill.

Codex CLI

Codex CLI is an open-source terminal coding agent from OpenAI. It is not an API wrapper; it’s a standalone tool that reads a codebase, performs multi-file edits, and runs commands in your local environment. It shipped SKILL.md support in December 2025, initially as an experimental feature.

The discovery paths have moved since that launch, which is worth knowing if you are following an older guide. Current OpenAI documentation lists .agents/skills in the working directory and its parents for repo-scoped skills, $HOME/.agents/skills for personal ones, and /etc/codex/skills for machine-wide skills. The original ~/.codex/skills location is the one you will still see in most third-party skill READMEs. A skill can be invoked explicitly by typing $ and picking from the list, or it can be triggered implicitly if a task matches its description.

Its primary configuration file is ~/.codex/config.toml, and its core instruction set can be customized via a file named AGENTS.md. This provides a different entry point for customization compared to Claude Code’s skill-centric model.

So, does Codex support SKILL.md? Yes, natively. The file format is a first-class citizen. The divergence comes from the environment it provides for that file to run in.

One-Directional Portability: What Our Data Shows

This is the core of the issue. We have never tested a skill on Codex CLI. We cannot provide a pass rate for Codex or a direct, side-by-side comparison based on our own test data. To claim otherwise would be inventing a dataset.

What we can provide is an honest look at a specific pattern in our Claude Code test results. Of the 2090 skills we’ve tested, our notes show that 47 of them touch Codex in some way — most often because the skill assumes Codex tooling or a Codex install path. We ran all of them in a Claude Code harness. That gives us a one-directional view of portability: what happens to a Codex-flavored skill when it lands on the other agent.

The results for those 47 skills are:

• Passed: 11
• Setup: 34
• Failed: 2

This tells a clear story: a SKILL.md file written for Codex is highly likely to require manual setup to run on Claude Code. It’s not because the file is invalid, but because the skill’s instructions rely on tools or paths that don’t exist in the new environment.

Let’s look at specific examples from our catalog:

• Generate 2D Map (Verdict: Setup): The skill’s upstream README explicitly states it’s for Codex/Grok and lists install paths of ~/.codex/skills and ~/.grok/skills, not the ~/.claude/skills its listing claimed. Its primary pipeline needs a built-in image-generation and image-viewing tool pair that Claude Code does not have. We tested it on the one branch that does not need images — building a Tiled orthogonal map as JSON — and the skill tied the base model exactly: byte-identical tile arrays, identical spawn and exit metadata. The file loaded; the part worth installing it for did not run.

• Generate 2D Sprite (Verdict: Setup): This skill has the same problem. It hard-depends on image generation capabilities that ship with Codex and Grok but not Claude Code. It can plan a sprite sheet, but it can’t execute the final step of producing the art.

• Ablation Planner (Verdict: Setup): The headline mechanic of this skill involves handing off design work to a specific Codex tool. When run in our Claude Code harness, that tool was unavailable. The step had to be performed manually, which is the definition of a ‘setup’ verdict.

These examples show that the SKILL.md file is portable, but the skill’s logic may not be. The instructions are just text; if they instruct the agent to use a tool that isn’t there, the process will halt.

Conversely, 11 of these Codex-oriented skills passed without issue. Skills like Better Codex and PinMe Share passed our tests on Claude Code. Both carry their value in text rather than in vendor tooling. Better Codex is a pure-prompt behavioral overlay with no external files or scripts, and it still beat the base model on a config-parser task, where the baseline silently broke on values containing an equals sign. PinMe Share installs from a single valid SKILL.md with no dangling references, and its edge is exact knowledge of an ordinary npm CLI: it emitted the canonical upload command and the required auth steps, where the base model guessed the command and skipped the login. That is the shape of a portable skill. It needs a tool you can install, not a built-in that ships with one vendor’s agent.

Key Differences at a Glance

A direct comparison highlights the trade-offs when considering codex cli or claude code for coding with skills.

Feature	Claude Code	Codex CLI
Skill Path	~/.claude/skills (personal), .claude/skills (project)	$HOME/.agents/skills (personal), .agents/skills (repo), /etc/codex/skills (machine)
Config	settings.json, plus CLAUDE.md for instructions	~/.codex/config.toml, plus AGENTS.md for instructions
Sandboxing	Opt-in; env vars inherit from the parent shell	On by default in workspace-write, network off unless enabled
Malformed SKILL.md	Silently fails to load	(Behavior not tested by us)

The Sandbox Trade-Off

The most significant difference in execution environments is the default sandboxing behavior.

Codex CLI, according to its documentation, operates with a stricter default security posture. In its workspace-write mode, network access is disabled unless you explicitly enable it in config.toml. File system writes are scoped to the current workspace, and the agent’s approval policy defaults to asking for confirmation before taking action. This is a ‘default-deny’ model.

Claude Code, as documented by Anthropic, takes a different approach. Sandboxing is something you turn on rather than something you turn off, and even with it on the shell inherits the parent process environment by default. This means if you have credentials like AWS_ACCESS_KEY_ID exported in your terminal session, a skill invoked by Claude Code can potentially read them. That makes skills which talk to external services or local credentials work out of the box, and it puts the burden of managing that exposure on you.

Neither approach is inherently better; it’s a trade-off. Codex’s model prioritizes security by default, potentially requiring more configuration to get a networked skill running. Claude Code’s model prioritizes out-of-the-box functionality, potentially exposing more of the host environment. A skill that shells out to curl an API might just work on Claude Code but be blocked by default on Codex CLI.

The Decision Rule: Judge the Environment, Not the File

So, Claude Code vs Codex CLI: which should you use for skills?

Our data provides an honest, if incomplete, answer. The SKILL.md file format itself is not the deciding factor. The same file will load on both platforms. The real decision hinges on the execution environment and the dependencies of the skills you want to run.

1. Check for Tool Dependencies: Does the skill rely on built-in, agent-specific tools (like the image generation in Generate 2D Map)? If so, it will not be portable.
2. Check for Universal CLI Dependencies: Does the skill only use ubiquitous command-line tools? It has a high chance of being portable, as shown by the 11 Codex-oriented skills that passed in our Claude Code harness.
3. Consider Your Sandbox Preference: Do you prefer a system that is locked down by default and requires explicit permissions (Codex CLI)? Or do you prefer one that works with less friction out of the box but inherits your full environment context (Claude Code)?

We cannot declare a universal winner because we have not tested on both platforms. The choice depends on your specific needs and security posture. What we can say with certainty is that assuming a skill will work just because the SKILL.md file is compatible is a mistake. The environment is everything.

Related reading: AGENTS.md vs Claude Skills covers the other half of the cross-tool question — the instruction file each agent reads before any skill loads. And if you are choosing between terminal agents on grounds other than skills, Claude Code vs Cursor works through that trade-off.

At SkillProof, our value is in eliminating this uncertainty for the Claude Code ecosystem. We do the testing so you don’t have to. Every ‘pass’ verdict in our catalog represents a skill we installed and ran on Claude Code, on real work. For a curated starting point, our role-based skill packs each collect ten tested skills for one job function — developer, security review, marketing, design and four more — for $10 a pack, with each skill’s verdict stated up front.