Codex Skills vs Claude Code Skills: How to Share Workflows Across Agents

OpenAI Codex and Anthropic Claude Code handle agent skills through fundamentally different paradigms: Claude Code natively parses hierarchical local folders with SKILL.md frontmatter manifests for on-demand tool execution, whereas Codex agents rely on system prompt preambles, AGENTS.md runbooks, and MCP-connected tool servers. Sharing workflows between Codex and Claude Code prevents duplicate authoring and ensures consistent engineering standards across both CLIs.

How Do Codex Skills Differ from Claude Code Skills?

Codex skills and Claude Code skills differ primarily in how instructions are packaged, discovered on disk, and loaded into the LLM context window. Claude Code employs a decentralized, file-based skill packaging standard where individual directories hold a SKILL.md manifest alongside helper scripts. OpenAI Codex systems traditionally consume operational guidance as contiguous Markdown sections embedded in system prompt preambles, repository-level AGENTS.md files, or programmatic function tools exposed via the Model Context Protocol.

Modern software engineering teams rarely standardize on a single terminal agent. An engineer might rely on Anthropic's Claude Code for autonomous multi-file refactoring, terminal command execution, and codebase-wide search, while using OpenAI Codex or ChatGPT-based developer tools for specialized mathematical reasoning, micro-benchmarking, and enterprise integrations.

As documented in Anthropic's official Claude Code Documentation: “Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools.” To execute workflows without human intervention, Claude Code scans designated filesystem directories and evaluates YAML frontmatter to determine which skills match the developer's request.

Meanwhile, the OpenAI ecosystem models instructions as structured context prompts and callable tools, as detailed in the OpenAI Prompt Engineering Guide. When developers attempt to bridge these ecosystems manually, they encounter fragmented instruction formats: Claude Code expects modular folder boundaries, while Codex requires centralized runbooks. Without a disciplined synchronization strategy, developers end up maintaining two conflicting copies of every engineering rubric.

Where Are Skills Stored in Codex vs Claude Code?

Claude Code resolves skills through a strict directory hierarchy across personal and project scopes, while Codex agents look for monolithic project files or API-level instruction sets. In Claude Code, personal skills reside in ~/.claude/skills/<skill-name>/SKILL.md and project-specific skills live in .claude/skills/<skill-name>/SKILL.md. Codex agents typically resolve operational guidance from a repository-level AGENTS.md file in the project root, a dedicated .codex/ directory, or dynamic instructions piped through an MCP server.

Understanding filesystem resolution order is essential when building cross-agent workflows. In Claude Code, if a skill named code-review exists in both ~/.claude/skills/code-review/ and .claude/skills/code-review/, the local project version completely overrides the personal version.

Here is the directory structure comparison:

# Claude Code Skill Hierarchy (Modular Directories)
~/.claude/skills/                       # Personal/Global scope (available in every repo)
├── pr-review/
│   ├── SKILL.md                        # Frontmatter + instructions
│   └── scripts/check-diff.sh           # Executable helper script
└── database-migration/
    ├── SKILL.md
    └── templates/schema.sql

.claude/skills/                         # Project-specific scope (checked into repo)
└── api-conventions/
    └── SKILL.md

# OpenAI Codex Hierarchy (Runbook & Context Injection)
my-project/
├── AGENTS.md                           # Project runbook read by Codex & coding agents
├── .codex/                             # Optional agent metadata & tool definitions
│   └── instructions.md                 # Supplementary guidelines
└── codex_config.json                   # MCP and runtime tool mappings

Notice the fundamental structural difference: Claude Code isolates each skill into its own folder with self-contained assets. Codex aggregates guidelines into higher-level runbook files. If you want a skill to execute reliably in Claude Code, it must have a valid SKILL.md entrypoint with YAML frontmatter. If you want that same skill available in Codex, its directives must be surfaced in AGENTS.md or exposed over an MCP connection.

Architecture Matrix: Codex vs Claude Code Feature Breakdown

Evaluating Codex skills alongside Claude Code skills requires analyzing how each platform handles execution scopes, context budgets, tool execution, and team sharing. The table below outlines the core technical trade-offs between both agent ecosystems.

Context Token Economics: Lazy Loading vs Prompt Preamble Overhead

The most consequential architectural difference between Claude Code skills and Codex instructions lies in context token economics. While Claude Code indexes local skill frontmatter at 35 to 50 tokens per skill until runtime activation, stuffing an equivalent collection of Codex instructions into a monolithic system prompt consumes 2,500 to 5,000 tokens on every single turn.

Consider an engineering library containing 15 standardized workflows: pull request review rubrics, schema migration rules, accessibility audits, unit testing patterns, security sanitization, and release tagging.

• In Claude Code: During session initialization, the agent parses only the YAML frontmatter (the name and description attributes) for each skill. Across 15 skills, the initial context footprint is roughly 600 to 750 tokens. The full markdown instruction body (typically 800 to 1,500 tokens) is loaded into the prompt context only if the agent decides that the current user prompt triggers that specific skill. This lazy-loading architecture delivers up to a 96% reduction in idle token overhead.
• In Monolithic Codex Setup: Because standard Codex CLI workflows read entire AGENTS.md files or append static instructions to every turn, all 15 workflows are transmitted on turn 1, turn 2, turn 5, and turn 10. Across a standard 10-turn coding session, this monolithic stuffing consumes 25,000 to 50,000 tokens solely on static rules.

This overhead does not merely increase API inference bills—it actively degrades model accuracy. When an agent's context window is crowded with thousands of tokens of irrelevant instructions, attention mechanisms suffer from retrieval dilution. Claude Code’s frontmatter indexing protects model attention by ensuring only relevant directives enter the active window.

Can You Run the Same Skill in Both Codex and Claude Code?

Yes, you can run the same skill in both Codex and Claude Code by standardizing on a canonical Markdown structure with dual-compatible metadata headers. The core body of an AI skill consists of declarative instructions, validation checklists, and execution steps, which both LLMs interpret with high fidelity. The only obstacle is file resolution and frontmatter parsing, which can be unified through cross-agent mapping.

To author a skill that functions seamlessly across both Anthropic and OpenAI runtimes, structure the skill as a standard SKILL.md package, and link it into your Codex agent's knowledge boundary.

Examine this dual-compatible database migration review skill:

---
name: database-migration-review
description: Audits PostgreSQL and MySQL database schema migrations for zero-downtime safety, index coverage, and locking risks. Use whenever reviewing or drafting schema changes.
toolAction: Auditing schema migration
toolSummary: Database migration audit
---

# Database Migration Safety Rubric

## Objective
Analyze pending SQL migration scripts and verify compliance with production zero-downtime standards.

## Execution Rules
1. Check Table Locks:
   - Disallow 'ALTER TABLE ... ADD COLUMN ... DEFAULT' on tables exceeding 50,000 rows without PostgreSQL 11+ metadata optimizations.
   - Enforce 'CREATE INDEX CONCURRENTLY' for all index additions.
2. Foreign Key Validations:
   - Ensure foreign keys are added with 'NOT VALID' followed by a separate 'VALIDATE CONSTRAINT' statement.
3. Rollback Feasibility:
   - Verify that every 'UP' migration has a corresponding, non-destructive 'DOWN' migration script.

## Verification Checklist
- [ ] No exclusive table locks acquired during peak transaction windows
- [ ] New columns default to nullable or possess instant-add metadata
- [ ] Rollback SQL script tested against staging snapshots

When Claude Code encounters this file in ~/.claude/skills/database-migration-review/SKILL.md, it reads the frontmatter, registers the trigger, and activates the rubric whenever the user says *"check this migration."*

To expose this exact same rubric to OpenAI Codex without duplicating the text, you can reference the canonical file directly in your project root AGENTS.md:

# AGENTS.md

## Operational Skills & Rubrics
When performing database operations, review the mandatory migration rubric located at:
- `.claude/skills/database-migration-review/SKILL.md`

Adhere strictly to the zero-downtime rules and validation checklists defined in that manifest.

Alternatively, if your Codex workflow connects to an MCP server, the skill directory can be served as a callable resource or tool description, allowing Codex to query the instructions dynamically without cluttering the initial system prompt. For an in-depth look at building this architecture, read our technical tutorial on building a multi-machine AI skill sync pipeline using MCP.

The Sprawl Moment: The Friction of Dual-Agent Development

You spend Thursday afternoon perfecting an autonomous database migration and schema audit skill inside Claude Code. It has strict pre-flight checks, verifies zero-downtime column additions, checks index coverage, and generates rollback scripts. On Friday morning, you switch to OpenAI Codex on your remote development container to tackle a distributed caching service that requires heavy concurrent logic. You ask Codex to run the schema migration and safety checks. Codex responds with a generic, unconstrained SQL script that completely ignores your team's migration conventions, drops columns without foreign-key validation, and misses rollback logs. You realize your carefully tested skill lives entirely inside ~/.claude/skills/ on your local MacBook. The remote Codex agent has zero access to it, forcing you to manually copy-paste snippets between terminal windows or spend forty-five minutes re-authoring the same guidelines in an unfamiliar configuration format.

How Do You Sync Skills Across Both Agents Without Git Conflicts?

You can sync skills across both agents without git conflicts by decoupling your personal skill library from application repositories and utilizing an automated synchronization manager. Committing personal developer workflows into a team repository’s .claude/skills/ or AGENTS.md causes branch conflicts, pollutes pull request diffs, and forces teammates to adopt rules they never requested.

Engineers often attempt to solve multi-machine skill sharing with shell scripts or Git submodules. However, symlinks break across operating systems (such as developing on a macOS laptop and deploying to an Ubuntu container), and Git submodules require manual pull steps that developers inevitably forget.

This is where a specialized agent skill manager transforms your workflow.

Prompttly is a skill manager for AI agents — one library for your skills and prompts that syncs into Claude Code, Codex, ChatGPT, and Claude and is one hotkey away on your Mac, so your setup follows you across every machine, repo, and tool.

Instead of juggling disjointed folders across tools, Prompttly solves the dual-agent challenge through automated, bidirectional synchronization:

• Native Filesystem Synchronization: Prompttly automatically writes your skills to ~/.claude/skills/ for Claude Code and outputs corresponding AGENTS.md runbooks and MCP descriptors for OpenAI Codex, ensuring both agents reflect your latest changes in real time.
• Sub-200ms Mac Hotkey Palette: Press a global keyboard shortcut from anywhere on macOS to summon your complete prompt and skill library, instantly inserting tested instructions into terminal sessions, IDE chat windows, or browser interfaces.
• Two-Way Sync on Mac: Edits made directly in your local code editor to SKILL.md files are detected and synchronized back to the Prompttly cloud library, maintaining version history across all your machines.
• Multi-File Skill Packaging: Bundle reference schemas, test fixtures, and bash scripts alongside your skills without polluting your application repositories.
• MCP Server Connectivity: Expose your entire skill library to any autonomous AI agent using a secure Model Context Protocol connection with full read and write access.

When NOT to Use Prompttly (Simpler Alternatives)

Prompttly is designed for developers managing multi-agent workflows across multiple machines, but it is not necessary for every engineering setup. If your workflow is strictly confined to a single environment, simpler built-in tools will serve your needs with less complexity.

A dedicated skill manager is unnecessary in the following scenarios:

• Single-Agent, Single-Repo Workflows: If you exclusively use Claude Code inside one primary repository and never switch to Codex, Cursor, or remote development boxes, checking a handful of skills directly into .claude/skills/ via Git is completely sufficient.
• Static Prompt Libraries: If your team relies on fewer than three general prompts that change once a year, storing them in a shared team wiki or using a basic snippet expander avoids introducing another tool.
• Strict Air-Gapped Environments: If you work on isolated air-gapped workstations where outbound cloud synchronization is prohibited by enterprise security policies, manually managing local dotfiles via internal Git mirrors is the appropriate choice.

However, once you author more than 10 reusable workflows, operate across both Claude Code and OpenAI Codex, or switch between a work MacBook and a home desktop, managing skills manually inevitably leads to instruction drift, lost prompts, and wasted context tokens.

Frequently Asked Questions About Codex Skills vs Claude Code Skills

Below are practical answers to the most common questions developers ask when coordinating workflows across OpenAI Codex and Anthropic Claude Code.

What happens if you feed Claude Code frontmatter directly to Codex?

OpenAI Codex treats YAML frontmatter as standard Markdown text. While Codex will not throw a syntax error, it will interpret the frontmatter block as conversational guidance rather than indexing metadata, consuming prompt tokens unnecessarily. Stripping or abstracting the frontmatter via an MCP bridge is the best way to optimize token efficiency in Codex.

Do Claude Code subagents support the same skills as Codex agents?

Yes. Claude Code subagents spawned via task delegation inherit access to both personal and project-level skill directories. Similarly, Codex agents configured with tool-calling capabilities can invoke operational skills if exposed as MCP tools. Both architectures support multi-agent delegation when skills are cleanly decoupled from the parent runtime.

How can I convert my existing prompts into structured skills for both agents?

You can use Prompttly's free Claude Skill Creator to turn raw instructions into production-ready SKILL.md packages with structured YAML frontmatter, input parameters, and validation checklists. For conversational system instructions, our free Custom Instructions Generator formats preambles optimized for ChatGPT and Claude.

Can these skills also be shared with Cursor and Windsurf?

Yes. While Cursor relies on .cursor/rules/*.mdc and Windsurf uses .windsurfrules, the core operational directives can be shared across all four tools. For a comprehensive breakdown of rule formats across IDEs, consult our guides on Cursor Rules vs Claude Skills and Codex Skills Architecture.

What is the fastest way to prevent rule drift across multiple laptops?

The most reliable approach is to maintain a single centralized skill repository that synchronizes automatically with local dotfiles. For a detailed walkthrough on multi-device synchronization, read our guide on how to sync prompts and rules across laptops.