Convert Claude Skill to Codex Without Breaking Workflows

When I was sitting in my damp home office in Manchester on a dreary morning, I found myself wrestling with a Claude Code skill that I had spent weeks perfecting for our team’s workflow. It worked like magic in Claude, but as our team started experimenting with Codex, I realised that moving a Claude skill over takes more than just dragging and dropping a folder across directories. File paths break, metadata behaves slightly differently, and hidden Claude-specific commands can stall your workflow. OpenAI now provides built-in migration tooling such as the migrate-to-codex workflow that handles the heavy lifting for supported instruction files, skills, agents, and MCP setups.

However, some Claude-specific habits still need a careful manual eye. If you want to convert Claude skill to Codex cleanly without breaking your setup, this practical step-by-step guide will walk you through the entire journey.

Can You Convert a Claude Skill to Codex?

Yes, you can convert a Claude skill to Codex, and the direct answer is that most of your core instructions will survive the trip intact. Current OpenAI tooling includes a dedicated migrate-to-codex skill designed specifically to scan, map, and transform supported instruction files, skills, subagents, and Model Context Protocol (MCP) settings directly into Codex project and global config spaces.

Yes, but it is not always a one-click conversion

While the overall concepts align well, treating migration as a simple file rename will eventually bite you. Claude and Codex interpret local paths, environment metadata, background commands, and runtime execution models in slightly different ways.

• What can usually be migrated: Core Markdown instructions, standard YAML frontmatter, standalone documentation, reference guides, and general helper scripts.
• What may need manual review: Custom shell hooks, Claude-specific tool calls, hardcoded system paths, and specialized plugins.
• Why testing still matters: An instruction file might load into memory without any syntax errors, but the agent could still fail when trying to run a script due to missing shell environment flags.
• Difference between file conversion and behaviour conversion: Moving a text file changes where instructions live, but updating the behavior ensures the underlying AI agent understands how to invoke tools and resolve local file paths within Codex.

Claude skills and Codex skills share an important idea

Both systems build upon the open Agent Skills pattern. The core idea relies on a central SKILL.md file containing metadata and core guidance, supported by modular subfolders for scripts, templates, and deep reference documentation. Anthropic’s skill documentation describes this layout directly, and Codex adopts a compatible folder layout.

Plaintext

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

When should you migrate manually instead?

Automated scripts are fantastic for bulk work, but manual conversion is often faster and cleaner in specific scenarios:

• Very small skill: If your skill is just a single 20-line SKILL.md file, copying it over manually takes under a minute.
• Claude-specific plugin dependency: Skills relying heavily on vendor-specific Claude plugins will fail automatically without manual refactoring.
• Heavy use of Claude-only commands: Custom slash commands specific to Claude Code require manual prompt remapping.
• Custom hooks: Event hooks written for .claude/settings.json need manual translation into .codex/hooks.json.
• Complex path assumptions: Hardcoded paths like /mnt/skills/ or home folder shortcuts must be updated for your target project structure.
• Sensitive production workflow: High-risk deployment skills should be inspected line-by-line rather than converted via automated scripts.

Claude Skills vs Codex Skills

Before moving files around, it helps to understand what changes between environments. The table below highlights the practical shifts you will see during a migration.

The structural differences between both setups determine how skills are discovered and loaded at runtime.

Note: OpenAI’s migration guidance explicitly marks Claude plugins as manual migration targets rather than automated conversions.

Claude Code skill structure

Claude skill packages group instructions and assets together inside local or global hidden directories.

Plaintext

.claude/
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── scripts/
        ├── references/
        └── assets/

Codex skill structure

Codex looks for skills inside designated project directories like .agents/skills/ or system-wide locations, though exact path resolutions can evolve with tool updates.

Plaintext

.agents/
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── scripts/
        ├── references/
        └── assets/

What You Need Before Converting a Claude Skill

A quick sanity check before touching any code saves hours of tedious debugging later on.

Find the original Claude skill

Locate your source skill folder first:

• Project-level skills: Check .claude/skills/ inside your target project root.
• User-level global skills: Check ~/.claude/skills/ in your user home directory.
• Plugin-provided skills: Locate installed plugin paths within your Claude storage folders.
• Verify active status: Make sure the skill is currently functional in Claude before migrating it.

Read the entire SKILL.md

Take a moment to read through your source SKILL.md file from top to bottom. Anthropic highlights that keeping core skills lean while moving detailed background information into reference subfolders improves execution speed and accuracy. Scan for:

• YAML frontmatter blocks (name and description)
• Trigger conditions and context descriptions
• Hardcoded file or folder paths
• Tool and command names specific to Claude
• Environment variable expectations
• Example prompts and sample script calls

Make a migration checklist

Having a physical or digital checklist at your desk keeps the task structured:

• Source SKILL.md located and verified
• YAML frontmatter checked for valid key-value pairs
• Supporting scripts, assets, and references listed
• Claude-specific syntax and commands flagged
• Target Codex directory (.agents/skills/) created
• Converted skill tested with sample prompts

How to Convert Claude Skill to Codex Using OpenAI’s Migration Tool

OpenAI provides built-in migration workflows designed to parse Claude setup trees and generate native Codex skill structures automatically.

Step 1: Inspect the Claude project first

Before running a full conversion, perform a dry run to map out existing surfaces. The migration tool includes scanning mechanisms to review active files.

Bash

# Scan local Claude configuration without writing changes
python3 scripts/migrate-to-codex.py --scan-only

During this initial check, the migrator identifies active project skills, global skills, custom slash commands, agent configurations, hooks, and MCP server setups.

Step 2: Run the migration process

Execute the migration script or trigger the migrate-to-codex skill within Codex to perform the file transformations.

Plaintext

Source: .claude/skills/<name>/SKILL.md
Target: .agents/skills/<name>/SKILL.md

The migration engine copies instructions, moves supported supporting subdirectories, normalizes metadata tags, and flags unsupported settings automatically.

Step 3: Read the migration report

Once the tool finishes, inspect the output report (usually written to .codex/migrate-to-codex-report.txt or displayed directly in the terminal). The report groups findings into clear status levels:

• Added: Items successfully converted and mapped into Codex-native files.
• Check before using: Items converted with minor semantic updates that need a quick manual review.
• Not Added: Unsupported features like vendor plugins, custom binary hooks, or incompatible tools that require manual setup.

Step 4: Inspect the generated Codex skill

Open the generated SKILL.md file in .agents/skills/<name>/ and verify that the content aligns with your original workflow. Double-check that all relative paths point to existing files and that the frontmatter contains clear activation triggers.

How to Convert a Claude SKILL.md Manually

Manual conversion gives you total control when updating small, custom, or complex skills.

Copy the core skill structure

Start by setting up a fresh skill directory inside your target project.

Plaintext

.agents/skills/my-skill/
└── SKILL.md

Move supporting resources

Copy over any supporting subfolders directly from your source directory without breaking relative references.

Plaintext

.agents/skills/my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Review YAML frontmatter

Both Anthropic and Codex require clean frontmatter blocks. The name and description fields tell the AI agent when to trigger the skill.

YAML

---
name: code-reviewer
description: Automatically reviews pull requests for style compliance, unit tests, and security vulnerabilities.
---

Rewrite Claude-specific instructions

Scan the body text of SKILL.md and adjust tool names, system references, or shell assumptions.

Preserve the task, not the old tool’s wording

Instead of copying phrases like “Use Claude’s built-in file search tool,” rewrite the instruction around the core goal: “Search the local codebase for matching class definitions.” This ensures the skill remains functional regardless of underlying engine updates.

Claude Commands Are Not the Same as Skills

A common trap when migrating is confusing Claude slash commands with Agent Skills. Commands are user-triggered shortcuts, whereas skills are context-aware capabilities loaded dynamically by the model.

Identify .claude/commands files

Look inside .claude/commands/ to locate existing slash command definitions. Categorize them into:

• Simple user shortcuts: Short prompt aliases.
• Multi-step workflows: Complex multi-file prompts that act like skills.
• Parameter-heavy prompts: Commands relying on positional arguments or dynamic shell evaluation.

Decide whether the command should become a Codex skill

• If the command performs a repeatable, multi-step task, convert it into a full Codex skill under .agents/skills/.
• If the command is just a brief prompt template, add it as a standard prompt instruction inside your primary instructions file.

Avoid blindly copying command syntax

Claude commands often rely on specific argument passing syntax like $1 or $ARG. Reframe these instructions into clear natural language descriptions so Codex understands how to handle user inputs gracefully.

What Happens to Claude Plugins, Hooks and Agents?

A full configuration migration often involves broader project surfaces beyond isolated skills.

Claude plugins

Plugins do not convert automatically. You will need to install equivalent native tools or configure relevant API connections manually within your Codex environment.

Claude hooks

Event hooks defined in .claude/settings.json must be re-mapped into .codex/hooks.json. Verify event hook names, shell execution pathways, and permission settings post-migration.

Claude agents

Claude subagents defined in .claude/agents/ convert into Codex custom agent TOML files inside .codex/agents/. Ensure model aliases and tool permissions are updated accordingly.

MCP configuration

Model Context Protocol definitions in .mcp.json convert directly into [mcp_servers] blocks inside .codex/config.toml. Check server command paths and environment keys after migration.

Common Claude-to-Codex Migration Problems

Even smooth migrations can hit minor speed bumps. Understanding common failure modes makes troubleshooting straightforward.

Broken file paths

The most frequent issue stems from absolute path assumptions. Paths like /mnt/skills/my-skill/script.sh will fail on systems expecting local project references. Always rewrite paths to be relative to the skill folder.

Unsupported frontmatter

Metadata fields supported by one system may trigger parse warnings in another. Stick to clean name and description parameters unless specific advanced fields are required.

Claude-only tool instructions

Instructions explicitly referencing Claude-native actions can cause the Codex agent to stall. Translate vendor-specific commands into general task directions.

Scripts work but the skill does not

If a script runs perfectly when invoked directly in the terminal but fails inside a skill run, check:

• Relative file paths within the script
• Current working directory expectations
• Executable permissions (chmod +x scripts/*.sh)
• Environment variable inheritance

The skill loads but behaves differently

Parsing a skill successfully simply means the file format is valid. If the agent misinterprets instructions, refine the prompt phrasing in SKILL.md to be clearer and more explicit.

How to Test a Converted Claude Skill in Codex

Testing validates that your converted skill performs reliably under real working conditions.

Test the basic trigger

Issue a simple prompt designed to activate the skill and verify the initial behavior:

• Did the skill trigger as expected?
• Did the model load the correct instructions from SKILL.md?
• Did it identify the intended task boundaries?

Test a normal workflow

Run a standard real-world request through the skill. Monitor the input arguments, tool execution steps, intermediate script calls, and final outputs.

Test edge cases

Push the skill outside its comfort zone to see how robustly it handles errors. Test scenarios involving missing files, unexpected data formats, empty inputs, or read-only directory permissions.

Compare Claude and Codex outputs

Evaluating execution across environments ensures functional consistency.

How to Improve a Converted Skill After Migration

Migration provides a great opportunity to clean up verbose instructions and improve overall structure.

Keep SKILL.md focused

Follow Anthropic’s progressive disclosure principle: keep SKILL.md focused on essential top-level instructions, while offloading detailed tables, API schemas, and extensive examples into the references/ directory.

Plaintext

my-skill/
├── SKILL.md
└── references/
    ├── api-schema.json
    └── detailed-examples.md

Move detailed information into references/

Offload non-essential context from your primary file:

• Verbose API document references
• Large JSON or YAML schema definitions
• Edge-case handling guides
• Historical migration notes

Keep deterministic work in scripts

If a process follows strict logic such as parsing a file format or validating a data checksum write a shell or Python script in scripts/ instead of relying on the AI model to re-invent the steps every run.

Improve the description

A clear, descriptive frontmatter summary ensures the model triggers the skill at the right time.

YAML

# Avoid vague descriptions:
description: Does code reviews.

# Use specific descriptions:
description: Triggers when reviewing pull requests or diffs. Analyzes code changes for bugs, style consistency, and security issues.

Best Practices for Claude Skill to Codex Migration

• Keep paths portable: Always use project-relative paths instead of absolute system locations.
• Avoid vendor lock-in: Focus core instructions on the task itself rather than specific AI engine interfaces.
• Use realistic examples: Provide practical code snippets inside your reference documentation.
• Track changes with Git: Commit your original files before running automated migration scripts.
• Keep backups intact: Retain your working .claude source files until post-migration testing is complete.

Claude Skill to Codex Migration Checklist

Before migration

• Locate source skill folders (.claude/skills/)
• Inspect SKILL.md frontmatter and instructions
• List supporting resources in scripts/, references/, and assets/
• Identify hardcoded file paths or system-specific commands
• Check for associated hooks, subagents, and MCP configurations

During migration

• Run the migration script (--scan-only or full run)
• Review generated output inside .agents/skills/ or .codex/skills/
• Inspect migration report warnings and unmapped surfaces
• Fix relative paths and frontmatter tags manually

After migration

• Test skill activation using target trigger phrases
• Run standard and edge-case workflows end-to-end
• Verify script execution rights and environment settings
• Document manual adjustments for team members

Frequently Asked Questions About Converting Claude Skills to Codex

Can I convert a Claude skill to Codex?

Yes. OpenAI provides automated migration tools (like migrate-to-codex) that read Claude skill packages and map them into Codex structures, though custom scripts and vendor-specific features may need manual adjustments.

Where do Codex skills live?

Codex looks for project-level skills inside .agents/skills/ or .codex/skills/, as well as user-level global skill paths in your home directory.

Can I use the same SKILL.md in Claude and Codex?

In many cases, yes. Because both follow the open Agent Skills pattern, a basic SKILL.md file without vendor-specific tools can run in both environments with minimal tweaks.

Do Claude plugins automatically migrate to Codex?

No. Plugins rely on vendor-specific ecosystems and require manual setup or equivalent native integration within Codex.

Do Claude commands automatically become Codex skills?

Automated tools map custom commands into skills or prompt templates, but parameter handling and syntax should be reviewed manually.

Why does my converted skill fail to find files?

This usually points to hardcoded absolute paths or broken relative links. Update your skill instructions to reference files relative to the project root or skill directory.

Should I manually rewrite every Claude skill?

Simple skills take only a minute to copy and adapt manually. For larger repositories with multiple agents, skills, and MCP configurations, use the automated migrator first and manually review the report.

How do I know if the migration worked?

Test the skill end-to-end in Codex. Verify that the model triggers the skill correctly, runs all supporting scripts, reads reference materials, and produces expected outputs.

Expert Advice on Moving AI Agent Skills Between Tools

Focusing on portable skill design saves significant time as tooling evolves.

Simon Willison’s perspective on portable AI tooling

Developer and open-source advocate Simon Willison frequently highlights the value of lightweight, tool-agnostic formats for AI workflows. Keeping instructions plain, modular, and decoupled from proprietary platforms ensures your skills remain adaptable as models and CLI engines shift over time.

What experienced developers should prioritise

• Portability: Standardize instructions using plain Markdown and universal shell commands.
• Modular files: Offload long documentation into reference files so main prompt files stay clean.
• Clear triggers: Write unambiguous descriptions in frontmatter to ensure accurate skill invocation.
• Deterministic logic: Use dedicated scripts for calculations or file processing instead of relying on model generation.
• Version control: Keep skill definitions tracked in Git alongside your source code.

A Real-World Claude-to-Codex Migration Example

To see how this works in practice, consider a pull request review skill configured for a development workflow.

The original Claude skill

The skill lived inside .claude/skills/code-review/SKILL.md and contained instructions for scanning code diffs, verifying unit tests, and checking basic security patterns.

YAML

---
name: code-review
description: Scans git diffs and runs test suites to output a PR review report.
---

The migration

Moving the skill over involved shifting the folder structure into the designated Codex location:

Plaintext

.claude/skills/code-review/  -->  .agents/skills/code-review/

The first test

Running the skill in Codex revealed two immediate points to address:

• What worked: The model triggered the skill automatically upon seeing a review request.
• What broke: A helper script failed because of a hardcoded path pointing to a Claude-specific directory.
• What needed changing: Updating the script invocation to use a relative project path (./scripts/check-format.sh) resolved the issue immediately.

The final clean-up

With paths corrected, detailed review checklists were moved into references/checklist.md, keeping the core SKILL.md lean and efficient.

Final Recommendation

When you convert Claude skill to Codex projects across your development team, automated tools like migrate-to-codex provide a fantastic starting point. However, taking a few minutes to review your file paths, YAML frontmatter, and supporting scripts manually will ensure your workflows remain fast, reliable, and portable across platforms. Keep your main skills focused, delegate complex tasks to scripts, and test thoroughly to get the best out of both environments.

Ehatasamul Alom

Ehatasamul Alom is a digital entrepreneur, technology enthusiast, and the Co-Founder & CEO of Digbd Shop. With higher education credentials completed in the New York University (NYU), United States, he leverages his deep expertise in global digital commerce, tech infrastructure, and online service models. Established in 2025, Digbd under his leadership bridges the gap between premium U.S. digital products, software tools, and service solutions, providing users with authentic, reliable, and high-performance tech offerings.