Are agent skills portable between Claude and Codex?

Is the "one skill, every agent" claim even real?

The Agent Skills format was built by Anthropic and released as an open standard at agentskills.io, and OpenAI's own Codex docs say plainly that Codex skills "build on the open agent skills standard." That's not marketing convergence, it's a real shared spec, and we pulled the actual frontmatter from both sides on 2026-09-07 to see how far the sharing goes: openai's Codex skills catalog on one side, and coreyhaines31/marketingskills, a 48,000-star repo whose GitHub topics literally list claude, codex, and marketing, on the other.

Here is the actual frontmatter from openai/skills' bundled pdf skill:

---
name: "pdf"
description: "Use when tasks involve reading, creating, or reviewing PDF files where rendering and layout matter..."
---

And from marketingskills' copywriting skill:

---
name: copywriting
description: When the user wants to write, rewrite, or improve marketing copy for any page...
metadata:
  version: 2.0.2
---

Same shape: name, a long description written as a trigger condition, then markdown. That part of the claim is real.

Do Claude Code and Codex even look for skills in the same place?

The identical SKILL.md file still has to sit in two different places, because Claude Code and Codex never agreed on a root directory.

Scope	Claude Code	Codex
Project	.claude/skills/<name>/SKILL.md	.agents/skills/<name>/SKILL.md (walks up to repo root)
Personal / user	~/.claude/skills/<name>/SKILL.md	$HOME/.agents/skills/<name>/SKILL.md
Org / admin	/etc/claude-code/.claude/skills/<name>/	/etc/codex/skills/<name>/

That's why marketingskills doesn't fork itself into two trees. Its AGENTS.md states the skills install to .agents/skills/, "the cross-agent standard," and keeps one canonical skills/ tree at the repo root. Claude Code gets its own path through a separate .claude-plugin/marketplace.json, a thin distribution wrapper, not a second copy of the content. Its CLAUDE.md file is a single line: the word "AGENTS.md," pointing back at the one real doc. That's the whole trick, and it's the cleanest evidence that dual-vendor skills aren't hypothetical, they're a live, 48,000-star repo doing it today.

Which frontmatter fields don't travel between them?

Beyond the six fields the open spec defines, each vendor bolted on its own extensions, and neither reads the other's.

Field	Shared spec	Claude Code only	Codex only
name, description	Required, ≤64 / ≤1024 chars	+ bans "anthropic", "claude"	Docs say describe "exactly when this skill should and should not trigger"
license, compatibility, metadata, allowed-tools	Optional, all four read on both	Grants clear each turn	Metadata read; no per-turn tool grant
disable-model-invocation, context: fork, hooks, model, effort, agent, background, paths, shell, user-invocable, disallowed-tools	Not in spec	Yes, 11 fields	Not read
Sidecar file agents/openai.yaml (interface.*, policy.allow_implicit_invocation, dependencies.tools)	Not in spec	Not read	Yes, optional sidecar

Claude Code's own documentation draws this line itself, in writing: only six frontmatter fields "follow the Agent Skills spec and work across vendors." Everything past that, including the eleven fields above, is described in Claude's docs as extending the standard, not implementing it. Codex takes the opposite approach and keeps SKILL.md itself lean, pushing UI branding and invocation policy into a separate optional file that Claude has no reason to ever open.

Is there a rename you'll always have to make?

There's exactly one case where the fix is a find-and-replace, not a rewrite: Claude Code's name field rejects the words "anthropic" and "claude" outright, a rule the open spec and Codex don't share. A Codex skill legitimately named something like claude-migration-helper is spec-valid everywhere else and will refuse to load on Claude Code until you rename the folder and the frontmatter. Small, mechanical, and easy to miss if you only test on one side.

So does a skill actually port unmodified?

At the content layer, yes, and that's most of what a skill actually is. The markdown body, the part that teaches the agent how to do the task, is plain prose with no vendor lock-in, and in every real skill we opened it's the bulk of the file. If you write to the six shared fields, that file runs on both machines with zero edits.

At the control layer, no. Anything that makes a skill more than a knowledge dump, forcing a risky step through an isolated subagent, gating a deploy behind explicit invocation only, giving it a branded icon in a plugin picker, has no equivalent on the other side. That's not a syntax problem you rename your way out of. Codex genuinely has no context: fork, and Claude Code genuinely has no agents/openai.yaml. You're not porting a feature, you're rebuilding it against a different set of primitives, if the target platform has an equivalent primitive at all.

How do you actually write one that stays portable?

Put the expertise in the body, not the frontmatter. Keep frontmatter to the six shared fields (name, description, license, compatibility, metadata, allowed-tools) and treat every host-specific field as an optional bolt-on you're fine losing on day one of a switch. If you also want a marketplace listing on both sides, don't fork the skill, wrap it: one skills/ folder, two thin manifests (.claude-plugin/marketplace.json and, per Codex's plugin docs, a matching .codex-plugin/plugin.json pointing at the same folder). That's the actual pattern behind the repo that picked up 602 stars today for claiming both ecosystems.

Worth naming too: the trending repo everyone's pointing at, openai/skills, carries its own deprecation banner as of this research, telling readers to use openai/plugins instead, and its last commit landed July 14, 2026, weeks before the star count moved. The format inside it is still correct. The repo just isn't where OpenAI wants the next skill written. Attention and activity aren't the same signal, and this is a clean case of the gap between them.

Who shouldn't bother writing skills at all?

If you're locked into one harness for the foreseeable future and you actually need what only that harness gives you, a hard invocation gate on a destructive action, a forked subagent for an isolated deploy, a branded entry in a marketplace, writing to the portable subset costs you real capability for a vendor switch that may never happen. Use the full extension surface. And if the instructions you're about to package only get used once, in one repo, one time, skip the SKILL.md machinery entirely. The whole format exists to amortize the cost of writing something down across repeated use. A single use is cheaper as a paragraph in your CLAUDE.md or AGENTS.md than as a directory you now have to keep spec-valid.

Related: Is an agent skills registry worth building in 2026? covers the trust and versioning problem sitting one layer above this one. If you're weighing whether to sell what you write instead of just writing it, see Is selling Claude Code skills worth it in 2026?. MCP hit the same fork earlier: see Is it worth building an MCP server in 2026? for the adoption-versus-trust gap in a different open protocol.

Frequently asked questions

Does a plain SKILL.md really work in both Claude Code and Codex without any changes?

Yes, if you stick to the fields the open Agent Skills spec defines: name, description, license, compatibility, metadata, and allowed-tools. Codex's own docs describe the identical frontmatter shape Claude's docs describe, and the markdown body underneath is just instructions, so a skill using only those fields loads on both without a single edit to SKILL.md itself. What still needs work is where the folder lives and how it gets there.

What breaks first when you move a skill from Claude Code to Codex?

Any of Claude Code's extension fields, disable-model-invocation, context: fork, hooks, model, effort, agent, background, paths, shell, user-invocable, disallowed-tools, carry no meaning to Codex, whose schema is just name and description plus an optional agents/openai.yaml sidecar. A skill that leans on those fields for its actual behavior loses that behavior entirely on Codex, not just its syntax.

What breaks when you move a skill the other direction, from Codex to Claude Code?

Two things. First, the name field: Claude Code's spec bans the literal words "anthropic" and "claude" inside a skill's name, a restriction the generic spec and Codex don't enforce, so a Codex skill named something like claude-migration-helper needs a literal rename before Claude Code will load it. Second, anything configured in agents/openai.yaml has no file Claude Code reads to reproduce it.

Where do Codex and Claude Code actually look for skills on disk?

Claude Code checks .claude/skills/ at the project level and ~/.claude/skills/ at the personal level. Codex checks .agents/skills/ walking up from the working directory to the repo root, plus $HOME/.agents/skills/ for user-level skills and /etc/codex/skills/ for admin-deployed ones. The same folder has to be placed, copied, or symlinked into both trees to be available in both tools.

Can one skill directory actually serve both platforms at once?

Yes. coreyhaines31/marketingskills keeps one skills/ tree at its repo root, written to the open spec, and its own AGENTS.md states skills install to .agents/skills/, "the cross-agent standard." For Claude Code's plugin system, it adds a thin .claude-plugin/marketplace.json wrapper on top rather than forking the content.

Is the openai/skills GitHub repo the current reference for Codex skills?

Not exactly. Its README carries a deprecation notice as of this research on 2026-09-07, pointing to openai/plugins and OpenAI's Build Plugins guide instead, and its last code push landed July 14, 2026, almost two months before the September trending spike. The format documented inside it is still accurate; the repository is being phased out as the place to browse it.

What's the practical rule for writing a skill that survives a vendor switch?

Write the actual expertise in the markdown body, keep the frontmatter to the six shared fields, and treat every host-specific field as an optional bolt-on you're prepared to lose. If you want a listing in both platforms' plugin marketplaces, wrap one shared skills/ folder in two thin manifests instead of maintaining two versions of the skill.

Who shouldn't bother writing skills at all?

Anyone committed to a single harness long-term who needs today's harness-specific power gains nothing from spec-only discipline and loses real capability chasing it. And anyone writing instructions for a single one-off task should skip the format entirely: a SKILL.md exists to amortize authoring cost across repeat use, and a single use is cheaper as a plain prompt or a paragraph in CLAUDE.md or AGENTS.md.