Claude Code skills: write one SKILL.md that Codex reads too

What a skill is, and what it isn’t

Anthropic’s skills page gives the trigger: “Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact.” The difference from CLAUDE.md or AGENTS.md is when it costs you context: those files load in every session, while “a skill’s body loads only when it’s used, so long reference material costs almost nothing until you need it.” The neighbours, in the makers’ own terms:

• An MCP server gives the agent tools and data from outside, such as a database or an API; a skill gives it knowledge and procedure, including how to use those tools well. Connecting an MCP server is a separate step.
• A subagent is a separate worker with its own context; a skill adds to the context it’s used in. They combine: a subagent can preload skills, and a Claude Code skill can run itself in a subagent with context: fork.
• A hook always fires on its event; a skill is instructions the model interprets. Anthropic’s advice: “Put guardrails in hooks.”
• A plugin is packaging: skills, hooks, subagents and MCP servers in one installable unit, covered in the plugins guide. Plain skills work without one.
• A slash command is now a skill in Claude Code: “Custom commands have been merged into skills,” and a file in .claude/commands/ keeps working. Codex deprecated its custom prompts in favour of skills in January 2026.

“Claude skills” also means the same thing in the Claude apps: you upload a skill as a ZIP under Customize, then Skills, on any plan with code execution turned on. Claude Code copies the skills enabled on your claude.ai account into ~/.claude/skills/synced/ when you sign in with that account (version 2.1.273 and later), one way only.

Writing one

The Agent Skills specification, which Anthropic first wrote and then published as an open standard in December 2025, is the shared format. The smallest valid skill is a folder whose name matches the skill’s, holding this:

---
name: release-notes
description: Drafts release notes from the merged pull requests since the last tag. Use when asked for release notes or a changelog entry.
---

1. Find the last tag with `git describe --tags --abbrev=0`.
2. List the merged pull requests since it with `gh pr list --state merged`.
3. Group them under Added, Changed and Fixed, one line each.

The rules that matter: the name is up to 64 lowercase letters, digits and single hyphens, and matches the folder; the description is up to 1,024 characters and says both what the skill does and when to use it, because that sentence is all the agent sees until it decides to load the skill. The specification budgets about 100 tokens a skill for that listing, recommends under 5,000 tokens for the body, and suggests keeping SKILL.md under 500 lines, with longer material in files beside it (scripts/, references/, assets/) that the body points to and the agent opens only when needed.

Each agent adds its own controls on top. Claude Code accepts about twenty frontmatter fields; the useful ones are disable-model-invocation: true (only you can start the skill, for anything with side effects such as a deploy), allowed-tools (tools it may use without asking during that turn), context: fork (run in a subagent), and in the body $ARGUMENTS for what you type after the command and !`command` to put a command’s output in before the model reads it. It also ignores fields it doesn’t know without an error, and claude plugin validate .claude/skills finds skills whose frontmatter doesn’t parse. Codex reads only the name, the description and a short description, and keeps its own settings in an optional agents/openai.yaml inside the skill folder, where policy.allow_implicit_invocation: false does what Claude’s disable-model-invocation does.

Where each agent looks

Two older Codex folders still load: .codex/skills/ in a repository, from Codex’s project configuration layer, and ~/.codex/skills/, which Codex’s source keeps “for backward compatibility” and where its own $skill-installer still puts what it installs. Neither is in OpenAI’s docs, and Claude Code reads neither.

When two skills share a name, Claude Code takes the managed one over yours and yours over the repository’s (a plugin’s is namespaced, so both load); Codex “doesn’t merge them; both can appear in skill selectors.” Claude Code picks up a skill you add or edit without a restart; Codex usually does, and its docs say to restart it if a change doesn’t show.

One skill for both agents

Both makers document symlinked skill folders, so the one-folder setup is a link rather than a copy:

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

We checked it on October 9, 2026, with Claude Code 2.1.295 and Codex 0.160.0, in a fresh repository holding a skill in each agent’s folder and one in Codex’s older .codex/skills/. Asked to list its skills, Claude Code named only the one in .claude/skills/; Codex named the ones in .agents/skills/ and .codex/skills/ and not Claude’s. After the symlink, both listed the shared skill, both ran it when called by name (a slash before the name in Claude Code, a dollar sign in Codex), and both chose it on their own from a question its description matched. Codex read the body by running cat on the file through its shell; Claude Code loaded it through its skill tool.

The same file still meets two different readers, which the test showed twice and the docs a third time:

• No description: Claude Code listed the skill with the first line of its body as the description, as its docs say it will; Codex dropped it from the list without a warning.
• disable-model-invocation: true: Claude Code hid the skill from its list, ran it when we typed its name, and, asked a question it answered, said the skill was hidden from it and read the file from disk instead. Codex ignores the field and used the skill freely.
• allowed-tools: Claude Code applies it; Codex doesn’t read it, and its sandbox and approval settings decide what the skill’s commands may do.

So a shared skill is best written to the specification alone (name, description, plain instructions), with each agent’s extras added knowing the other will ignore them. One caution for plugin authors: claude plugin validate doesn’t follow symlinks, and says so, so validate the real folder.

Sharing skills

The plainest way is to commit the folder: everyone who opens the repository gets it. For a skill you want everywhere on your machine, a skill folder can simply be copied into ~/.agents/skills/ for Codex or ~/.claude/skills/ for Claude Code. To publish skills for others to install, both makers point to plugins and marketplaces, and Codex can install from a Claude Code marketplace; the plugins guide has the commands. Moving the other way, Codex’s /import brings instructions, settings, skills and plugins across from a Claude Code setup on the same machine, and turns Claude Code’s slash commands into skills.

Before you use someone else’s

A skill is instructions an agent follows with your access, and often scripts it runs. Anthropic’s skills overview says to use skills “only from trusted sources,” to audit every file before use, and that “malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks”; skills that fetch from outside URLs are the riskiest, since what they fetch can change. Two facts make that concrete for a repository you clone. Claude Code applies a project skill’s allowed-tools “even in a -p run in a folder you’ve never trusted,” so its docs say to review them before running Claude Code there. And in our test, run non-interactively, both agents loaded and used the skills in a repository neither had opened before, with no prompt: the repository’s skills are part of what you trust when you run an agent in it.