MemoryLake
Back to all articles
TutorialNovember 18, 2026·11 min read

How to Migrate Your Codex Skills to Claude Code Without Losing Context (2026)

You've built a set of skills in Codex over the past few months: one that prepares a release, one that writes migration scripts the way your team likes, one that triages flaky tests. Now part of your work runs in Claude Code, and you want the same skills there. You copied a folder into your repository, opened Claude Code, and typed the skill's name. Nothing came up.

The skill itself was fine. It was in the wrong place. Codex and Claude Code both use the same skill format, but each looks for skills in its own folders. OpenAI's documentation says: "For repositories, Codex scans .agents/skills in every directory from your current working directory up to the repository root." Claude Code looks in .claude/skills/.

This guide covers what a skill is in each tool, where each one looks, what carries over unchanged, what doesn't map one to one, two ways to bring your skills across, how to keep one copy instead of two, and how to keep the reasoning behind your skills available whichever tool you're in.

What a skill is in Codex and in Claude Code

Both tools build on the same open standard. OpenAI's documentation says: "Skills build on the open agent skills standard." Anthropic's says: "Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools."

In Codex, OpenAI describes the structure: "A skill is a directory with a SKILL.md file plus optional scripts and references. The SKILL.md file must include name and description." A skill folder can also hold scripts/, references/, assets/, and an agents/openai.yaml file.

In Claude Code, a skill is also a folder with a SKILL.md file. The frontmatter between the --- markers tells Claude when to use the skill, and the markdown below it holds the instructions.

So the core of a skill, the folder, the SKILL.md file, its name, its description, and its instructions, is the same format in both tools. That's the good news for a migration. Most of the work is about location and about the few parts each tool adds on top of the standard.

Where each tool looks for skills

This explains the opening example.

Codex reads skills from repository, user, admin, and system locations:

  • Repository: .agents/skills in the current working directory and every folder up to the repository root.
  • User: $HOME/.agents/skills, for skills that apply in any repository.
  • Admin: /etc/codex/skills, shared on the machine.
  • System: skills bundled with Codex, such as skill-creator and skill-installer.

Claude Code reads skills from these locations:

  • Project: .claude/skills/<skill-name>/SKILL.md in the repository.
  • Personal: ~/.claude/skills/<skill-name>/SKILL.md, for all your projects on that machine.
  • Enterprise: a managed settings directory that your organization deploys.
  • Plugins: skills bundled in a plugin you've enabled.

Neither tool's documentation lists the other's folders. So plan on a skill in .agents/skills not appearing in Claude Code until it's in .claude/skills/, and the same in reverse.

There's one more difference for monorepos. Anthropic's documentation says Claude Code "loads project skills from .claude/skills/ in the directory where you start it and in every parent directory up to the repository root". It adds: "Skills in a .claude/skills/ directory below where you started don't load at startup." They load the first time Claude reads or edits a file in that subdirectory.

What carries over unchanged

Because both tools follow the same standard, the parts you write most carry over as they are:

  • The folder name and SKILL.md. The structure is the same.
  • name and description. Both tools use the description to decide when a skill applies.
  • The instructions. The markdown body is plain text that either tool can follow.
  • Supporting files. Scripts, references, and templates inside the skill folder come along with it.

Descriptions deserve a second look after the move. OpenAI's advice for Codex is to "write concise descriptions with clear scope and boundaries." Anthropic's documentation adds a limit for Claude Code: "the combined description and when_to_use text is truncated at 1,536 characters in the skill listing to reduce context usage." A description that's long but fine in Codex may be cut short in Claude Code's listing.

What doesn't map one to one

A few parts of a Codex skill are specific to OpenAI's products.

agents/openai.yaml. OpenAI describes this file's purpose: "Add agents/openai.yaml to configure UI metadata in the ChatGPT desktop app, to set invocation policy, and to declare tool dependencies for a more seamless experience with using the skill." It holds display names and icons, the implicit invocation policy, and dependencies such as an MCP server. Claude Code's skill documentation doesn't describe reading this file.

Invocation policy. In Codex, the policy section of that file holds settings such as allow_implicit_invocation. Claude Code has its own frontmatter field for the same idea, disable-model-invocation. The documentation says: "Set to true to prevent Claude from automatically loading this skill." If you had turned off implicit invocation for a skill in Codex, set this field in the skill's SKILL.md after the move.

Tool dependencies. If a Codex skill declares an MCP server in openai.yaml, Claude Code needs that server configured separately. Check that the skill's instructions still work without it, or add the server to Claude Code.

How you call a skill. In Codex CLI or the IDE extension, OpenAI says to "run /skills or type $ to mention a skill." In Claude Code, you invoke a skill directly with /skill-name.

Duplicate names. OpenAI notes: "If two skills share the same name, Codex doesn't merge them; both can appear in skill selectors." Claude Code also keeps nested skills with the same name available. If you're combining skill sets, rename any that clash before you rely on them.

Route 1: Use /import

Claude Code has a command for this. Its command reference describes /import as a way to bring configuration from OpenAI Codex and other coding agents on your machine into Claude Code, "including instruction files, MCP servers, commands, subagents, and skills."

Two options make it safer to run:

  • Preview first. The reference says: "Add --dry-run to preview without writing anything, or --yes to skip the interactive picker."
  • Run it from the terminal. claude import starts an interactive session that runs /import, with the same options.

When you set up a new project, /init also offers to carry Codex configuration over with /import if it finds any.

There's one detail in Anthropic's memory documentation worth reading before you run it. It says /import "appends a one-time copy of instruction files such as AGENTS.md to the matching CLAUDE.md and carries over MCP servers, commands, subagents, and skills."

The key words are one-time copy. After the import, your AGENTS.md and your CLAUDE.md are separate files. If you change a convention in AGENTS.md next month, Claude Code won't see it unless you update CLAUDE.md too, or run the import again. The same thinking applies to skills: once a skill is copied, editing the Codex version doesn't change the Claude Code version.

The documentation doesn't describe how /import handles agents/openai.yaml or other OpenAI-specific metadata. After an import, open each skill in Claude Code and check its frontmatter and supporting files.

Route 2: Keep one copy with a symlink

If you'll keep using both tools, two copies of every skill will drift. Both tools support symlinked skill folders, which lets you keep one source.

OpenAI's documentation says: "Codex supports symlinked skill folders and follows the symlink target when scanning these locations."

Anthropic's says a skill entry in the enterprise, personal, or project location can be a symlink to a directory elsewhere on disk. "Claude Code reads SKILL.md from the target and loads the skill once even if several locations point at the same target."

A simple layout is to keep each skill in one real folder and point the other tool's location at it:

  • Keep the skill in .agents/skills/release-notes/, where Codex finds it.
  • Add .claude/skills/release-notes as a symlink to that folder.

Edits to the one SKILL.md then reach both tools. Codex "detects skill changes automatically", and its documentation says to restart Codex if an update doesn't appear. If an edit doesn't show up in Claude Code, start a new session.

Two cautions apply. A symlinked skill shares one description, so write it to work in both tools' listings. And Claude Code-only frontmatter, such as disable-model-invocation, will sit in a file Codex also reads, so test that Codex still loads the skill after you add it.

Personal skills

The same choices apply to skills you keep for yourself rather than in a repository. Codex reads personal skills from $HOME/.agents/skills. Claude Code reads them from ~/.claude/skills/. You can copy them, run /import, or symlink individual skill folders.

Anthropic's documentation reserves one folder name in the personal location. Claude Code uses ~/.claude/skills/synced/ for skills downloaded from your claude.ai account, so don't name one of your own skills synced.

If you've moved the other way before, the same location and packaging questions came up for plugins. We covered that direction in our guide to migrating Claude Code plugins to Codex.

What to check before you start

  • Which skills you actually use. A migration is a good time to drop skills nobody calls.
  • Which skills depend on OpenAI-specific metadata. Look for agents/openai.yaml files with invocation policy or MCP dependencies.
  • Whether you'll keep using Codex. If yes, plan for symlinks. If not, a copy or /import is enough.
  • Name clashes. Compare skill names across both tools.
  • Your AGENTS.md. Decide whether Claude Code should read a copy or whether you'll maintain both files.

What people try first

Copying .agents/skills into the repository and expecting Claude Code to find it. Claude Code reads .claude/skills/.

Assuming /import keeps files in step. It appends a one-time copy of instruction files.

Leaving openai.yaml settings to carry over. Set disable-model-invocation in Claude Code if a skill shouldn't run automatically.

Keeping long descriptions as they are. Claude Code truncates the combined description text in its listing.

Maintaining two copies of the same skill. They'll drift. Use a symlink if you'll keep both tools.

The manual migration

Step 1: List your Codex skills

Collect the skills in .agents/skills across your repository, in $HOME/.agents/skills, and in any admin location you use.

Step 2: Preview the import

Run /import with --dry-run in Claude Code to see what it would bring over.

Step 3: Import or link

Run the import, or create symlinks from .claude/skills/ to the skill folders you'll keep in one place.

Step 4: Adjust frontmatter

Add disable-model-invocation where a Codex skill had implicit invocation turned off, and shorten long descriptions.

Step 5: Reconnect dependencies

Configure any MCP servers a skill depended on through openai.yaml.

Step 6: Test each skill by name

Invoke each skill with /skill-name, then try a request that should trigger it automatically.

The Better Way: Keep the reasons behind your skills in one place

A skill captures how to do a task. The reasons behind it, such as why the release checklist has a manual step, which migration pattern replaced an older one, or what a test-triage skill should never touch, are project context. When you move skills between tools, the instructions come along, but the history of why they read the way they do can live only in someone's memory.

MemoryLake is a memory layer for that kind of project context, such as decisions, conventions, and the reasons behind your workflows, kept in one place you maintain and available to the assistants you connect, such as ChatGPT, Claude Code, and Codex.

You write the entries yourself, in your own words. Nothing is read out of, written to, or deleted from your skill folders, your SKILL.md files, your AGENTS.md or CLAUDE.md files, your Codex or Claude Code settings, or any vendor's store. Skills and /import work the way OpenAI and Anthropic describe them.

Step 1: Create an API key

Sign in and generate a key from the dashboard. Store it outside your repositories, like any other credential.

The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent
The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent

Step 2: Upload your first memories

Start with the skills you listed in Step 1 of the manual migration. For each one, write down why it exists and what it must not change. One skill per entry.

The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory
The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory

Step 3: Connect your AI & agents

Connect Claude Code, Codex, and the other assistants you use. Each can draw on the same reasons, whichever tool runs the skill.

The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer
The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer

What this changes in practice

The first difference is a cleaner migration. Skills can be trimmed to instructions, because the history lives elsewhere.

The second is consistency across tools. The same reasoning is available in Claude Code and in Codex.

The third is easier updates. When a convention changes, you update one entry and the skill that follows it.

Best practices for moving Codex skills to Claude Code

Put skills where Claude Code looks. Use .claude/skills/ or ~/.claude/skills/.

Preview before importing. Use --dry-run.

Remember the one-time copy. Instruction files don't stay in sync after /import.

Symlink if you'll use both tools. One folder avoids drift.

Translate invocation policy. Use disable-model-invocation in Claude Code.

Keep descriptions short. Both tools match on them, and Claude Code truncates long ones.

Test by name and by request. Check both manual and automatic invocation.

Conclusion

Codex and Claude Code use the same skill format, built on the open agent skills standard, so a skill's folder, SKILL.md, name, description, and instructions carry over unchanged. What differs is where each tool looks: .agents/skills for Codex and .claude/skills/ for Claude Code. Codex-specific metadata in agents/openai.yaml needs a Claude Code equivalent, such as disable-model-invocation.

You can bring skills across with /import, which also appends a one-time copy of instruction files like AGENTS.md, or keep one copy with a symlink that both tools follow. Either way, check each skill after the move, and keep the reasons behind your skills somewhere both tools can use.

Frequently asked questions

Can Claude Code use Codex skills?

Yes. Both follow the same open standard. Move or link the skill folder into .claude/skills/ so Claude Code can find it.

Where does Claude Code look for skills?

In .claude/skills/ in the project and its parent directories, in ~/.claude/skills/, in managed settings, and in enabled plugins.

Does /import bring over Codex skills?

Yes. Claude Code's command reference lists skills among the configuration /import brings in, along with instruction files, MCP servers, commands, and subagents.

Does /import keep AGENTS.md and CLAUDE.md in sync?

No. Anthropic's documentation says it appends a one-time copy of instruction files.

Can I use one skill folder for both tools?

Yes. Both Codex and Claude Code support symlinked skill folders.

What happens to agents/openai.yaml?

Claude Code's skill documentation doesn't describe reading it. Set equivalent options, such as disable-model-invocation, in SKILL.md.

How do I call a migrated skill in Claude Code?

Type / followed by the skill name, or describe a task that matches its description.