Codex vs Claude Code Skills: Setup, Settings, and How to Share Skills Across Both

Name

Soren Atelier

Updated on 2/10/2026

"Skills" are quickly becoming the portable unit of reuse for AI coding agents. A skill is a folder that bundles instructions, optional scripts, and reference files into something an agent can discover and apply reliably. If you work with more than one AI coding tool, you have probably already felt the friction of maintaining separate configurations for each.

OpenAI Codex and Anthropic Claude Code both support skills, and both build on the Agent Skills open standard. Codex explicitly states its skills build on that standard and use "progressive disclosure" to manage context efficiently. Claude Code also follows the Agent Skills standard while adding its own extensions like invocation controls, subagents, and dynamic context injection.

That shared base is what makes a "write once, use in both tools" workflow possible — if you are careful about where skills live, how settings differ, and which frontmatter fields are portable. This guide breaks down every practical difference and shows you how to share a single skill across both agents.

Quick Comparison: Codex Skills vs Claude Code Skills

Mental Model: Same SKILL.md, Different Ecosystems

Both tools share the core idea: a directory with a SKILL.md file that contains YAML frontmatter (name, description) and Markdown instructions. The agent reads the metadata to decide when to use the skill and loads the full instructions when it activates. The differences are in discovery paths, configuration formats, and power features.

What Codex Means by "Skills"

Codex skills are directories containing a required SKILL.md and optional scripts/, references/, assets/, plus an optional agents/openai.yaml for UI metadata and dependencies (like MCP servers).

Codex loads skill metadata first and only loads the full instructions if it decides to use the skill. This is called progressive disclosure — it keeps context windows lean by only injecting what the agent actually needs.

What Claude Code Means by "Skills"

Claude Code skills are also SKILL.md-based and act like reusable slash commands. Claude can invoke them automatically when relevant, or you can run them directly via /skill-name.

Claude Code explicitly merged custom slash commands into skills:

• .claude/commands/review.md and .claude/skills/review/SKILL.md both create /review
• Skills add supporting files, invocation control, and auto-loading when relevant

How to Create and Install a Skill in Codex

1. Skill Directory Structure

At minimum, a Codex skill needs:

my-skill/
  SKILL.md

A full-featured skill can include:

my-skill/
  SKILL.md
  scripts/
    run-check.sh
  references/
    CHECKLIST.md
  assets/
    diagram.png
  agents/
    openai.yaml

The SKILL.md must include name and description in its YAML frontmatter.

2. Where Codex Discovers Skills

Codex scans multiple locations with a defined precedence:

Codex also explicitly supports symlinked skill folders and follows the symlink target while scanning.

3. Use Built-in Skill Tools

Codex provides two built-in helpers:

• $skill-creator — scaffolds a new skill directory with the correct structure
• $skill-installer — pulls and installs skills from external sources

4. Enable or Disable Skills in Settings

Codex can disable a skill without deleting it by adding entries under [[skills.config]] in the TOML config:

# ~/.codex/config.toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Restart Codex after changing the config.

5. Codex Settings Format

Codex configuration lives in TOML files with a clear precedence order:

CLI flags > profiles > project config (.codex/config.toml) > user config (~/.codex/config.toml) > system config > defaults

Skills can be controlled via these settings, and those settings can be scoped per project.

How to Create and Install a Skill in Claude Code

1. Skill Directory Structure

Claude Code skills are directories with SKILL.md as the entrypoint. Additional files are optional:

my-skill/
  SKILL.md
  template.md
  examples/
    sample.md
  scripts/
    validate.sh

Reference supporting files from your SKILL.md so Claude knows what they contain and when to load them.

2. Where Claude Code Discovers Skills

Claude Code has multiple scopes with precedence:

Claude Code also supports nested discovery in monorepos: if you are editing packages/frontend/..., it also looks for packages/frontend/.claude/skills/.

3. The SKILL.md Format: YAML + Markdown

Claude Code skills have two parts — YAML frontmatter and Markdown instructions:

---
name: explain-code
description: Explains code with visual diagrams and analogies.
---
 
When explaining code:
1) Start with an analogy
2) Draw an ASCII diagram
3) Walk step-by-step
4) Highlight a gotcha

The name becomes the /slash-command, and description helps Claude decide when to auto-load it.

4. Claude Code's Extended Skill Features

Claude Code extends the standard with features not available in Codex:

This is the single biggest practical difference: Claude skills can behave like mini-workflows with preprocessing and subagents, while Codex skills emphasize packaging instructions, resources, and scripts with progressive loading.

5. Claude Code Settings Format

Claude Code settings are JSON, scoped by managed/user/project/local, and editable via /config in the interactive REPL:

• User: ~/.claude/settings.json
• Project: .claude/settings.json
• Local overrides: .claude/settings.local.json

Key Differences: Side-by-Side Breakdown

Discovery Paths

Codex:        .agents/skills/  →  $HOME/.agents/skills/  →  /etc/codex/skills/
Claude Code:  .claude/skills/  →  ~/.claude/skills/       →  enterprise managed

This is the primary reason sharing skills requires symlinks or a shared repo.

Settings Formats

Activation UX

• Codex: /skills list and $ mention in CLI/IDE; implicit selection from description
• Claude Code: /skill-name invocation; auto-load based on description

Tool-Specific Extensions

• Codex: Optional agents/openai.yaml for UI metadata and dependency declarations (e.g., MCP servers)
• Claude Code: Frontmatter fields like disable-model-invocation, context: fork, command preprocessing (!`…`), argument passing

The Shared Core: Agent Skills Open Standard

If you want one skill to work in both Codex and Claude Code, anchor it in the Agent Skills specification. Here is what the spec requires:

Required Frontmatter Fields

Codex requires both fields. Claude Code is more forgiving (it can default name to the directory), but for cross-agent reuse, treat both as required.

File References

The spec recommends referencing files using relative paths from the skill root:

See [the reference guide](references/REFERENCE.md) for details.
 
Run the extraction script:
scripts/extract.py

Keep references one level deep to avoid complex nested chains.

How to Share One Skill Across Both Agents Using Symlinks

The cleanest pattern for using one skill in both tools:

1. Maintain a single canonical skills repo or folder
2. Symlink those skill folders into each agent's discovery path

Step-by-Step Setup

Assume you keep shared skills in ~/shared-agent-skills/:

~/shared-agent-skills/
  code-review/
    SKILL.md
    references/
      REVIEW_CHECKLIST.md
  test-writer/
    SKILL.md
    scripts/
      run-tests.sh

Link into a project for Codex:

mkdir -p .agents/skills
ln -s ~/shared-agent-skills/code-review .agents/skills/code-review
ln -s ~/shared-agent-skills/test-writer .agents/skills/test-writer

Link into the same project for Claude Code:

mkdir -p .claude/skills
ln -s ~/shared-agent-skills/code-review .claude/skills/code-review
ln -s ~/shared-agent-skills/test-writer .claude/skills/test-writer

Or link at user level for all projects:

# Codex (user scope)
ln -s ~/shared-agent-skills/code-review $HOME/.agents/skills/code-review
 
# Claude Code (user scope)
ln -s ~/shared-agent-skills/code-review ~/.claude/skills/code-review

Symlink Compatibility Notes

If Claude Code's /skills listing does not show your symlinked skill, you can still invoke it directly by name.

A Portable SKILL.md Template

Here is a spec-compliant template that works in both agents:

---
name: code-review
description: >
  Perform a structured code review for correctness, security,
  performance, and readability. Use when asked to review a
  diff, PR, or when preparing changes for merge.
license: MIT
compatibility: >
  Intended for coding agents (Codex, Claude Code) in Git repos.
  Requires read access to the repo.
metadata:
  owner: platform-team
  version: "1.0.0"
---
 
# Code Review Skill
 
## Inputs
- A diff, PR link, or list of changed files.
- The relevant module/service context.
 
## Process
1. Identify the goal of the change and expected behavior.
2. Review for correctness (edge cases, error handling).
3. Review for security (authz/authn, injection risks, secrets).
4. Review for performance (N+1 queries, hot paths, allocations).
5. Review for maintainability (naming, structure, tests).
6. Summarize findings with:
   - Must-fix items
   - Suggestions
   - Positive notes
 
## Reference checklist
See [our checklist](references/REVIEW_CHECKLIST.md) for the full list.

Adding Codex-Specific Metadata (Optional)

Add agents/openai.yaml for Codex UI metadata and dependencies. Other tools will ignore it:

# agents/openai.yaml
display_name: "Code Review"
icon: "🔍"
dependencies:
  mcp_servers:
    - github

Adding Claude Code-Specific Features (Optional)

For Claude-only workflows, you can add extended frontmatter in a separate Claude-scoped skill or in a .claude/-specific override:

---
name: code-review
description: Structured code review with security focus.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff*)
context: fork
---

Best Practices for Cross-Agent Skills

1. Keep Portable Content in the Shared Folder

Stick to the Agent Skills spec fields (name, description) and use references/ with relative links for long docs and checklists. This ensures both agents can parse and use the skill.

2. Isolate Tool-Specific Power Features

• For Claude Code: context: fork, ! command preprocessing, and allowed-tools are powerful but Claude-specific
• For Codex: agents/openai.yaml is Codex-specific but cleanly separated into its own file

Neither tool chokes on unknown fields — they simply ignore them. But for clarity, keeping tool-specific features in tool-specific files or overrides is better practice.

3. Use a Shared Git Repo for Skills

shared-agent-skills/          # Git repo
├── code-review/
│   ├── SKILL.md
│   └── references/
├── test-writer/
│   ├── SKILL.md
│   └── scripts/
├── setup-links.sh            # Symlink installer script
└── README.md

A simple setup-links.sh can automate symlinking:

#!/bin/bash
SKILL_DIR="$(cd "$(dirname "$0")" && pwd)"
 
# Link into Codex user scope
mkdir -p "$HOME/.agents/skills"
for skill in "$SKILL_DIR"/*/; do
  name=$(basename "$skill")
  [ "$name" = "scripts" ] && continue
  ln -sfn "$skill" "$HOME/.agents/skills/$name"
done
 
# Link into Claude Code user scope
mkdir -p "$HOME/.claude/skills"
for skill in "$SKILL_DIR"/*/; do
  name=$(basename "$skill")
  [ "$name" = "scripts" ] && continue
  ln -sfn "$skill" "$HOME/.claude/skills/$name"
done
 
echo "Skills linked for both Codex and Claude Code."

4. Version Your Skills

Include a version field in metadata and tag releases in your shared skills repo. When a skill changes behavior, bumping the version helps teams track what changed and when.

If you use AI coding agents like Codex or Claude Code for data analysis workflows, tools like PyGWalker (opens in a new tab) can turn your DataFrames into interactive visualizations — and you can build a skill that integrates PyGWalker into your agent's toolkit for on-demand data exploration.

FAQ

What is the Agent Skills open standard?

The Agent Skills open standard is a specification that defines how AI coding agents discover and use reusable skill packages. It establishes a common format — a directory with a SKILL.md file containing YAML frontmatter and Markdown instructions — so that skills can be portable across different agent tools.

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

Yes. Both agents build on the Agent Skills standard and recognize SKILL.md files with name and description frontmatter. The key requirement is placing the skill in each agent's discovery path (.agents/skills/ for Codex, .claude/skills/ for Claude Code), which you can do with symlinks from a single canonical location.

What are the main differences between Codex skills and Claude Code skills?

The core differences are discovery paths (.agents/skills/ vs .claude/skills/), settings formats (TOML vs JSON), and extension features. Claude Code adds subagent context forking, shell command preprocessing, and tool access controls. Codex adds agents/openai.yaml for UI metadata and MCP server dependencies. The base SKILL.md format is compatible across both.

Do symlinks work for sharing skills between agents?

Codex explicitly supports symlinked skill folders and follows the targets. Claude Code also works with symlinks for invocation, though the /skills listing command may not detect symlinked skills in some versions. You can still invoke symlinked skills by name even if they don't appear in the list.

What frontmatter fields are required for portable skills?

The Agent Skills specification requires name (must match the parent directory, lowercase with hyphens, 1-64 characters) and description (helps agents decide when to use the skill). Both Codex and Claude Code support these fields. Additional fields like license, compatibility, and metadata are optional but recommended.

Where should I put skills for user-wide access?

For Codex, place skills in $HOME/.agents/skills/. For Claude Code, use ~/.claude/skills/. Both locations make skills available across all projects without needing per-repo setup.

Conclusion

Codex and Claude Code skills share more DNA than their different ecosystems suggest. Both build on the Agent Skills open standard, both use SKILL.md as the entrypoint, and both support progressive loading based on skill descriptions. The practical differences — discovery paths, config formats, and extension features — are real but manageable.

The best strategy is to maintain a single source of truth for your skills, stick to the spec-required name and description fields for the portable core, and use symlinks to make each agent see the same skill folder. Keep tool-specific power features (Claude's subagent forking, Codex's YAML metadata) in their respective extension files. This way, you get portability without sacrificing the advanced capabilities of either tool.