How Each Tool Organizes a Project

Same idea, different file names and formats. Here's what each tool expects.

Claude Code

Anthropic's coding agent

One folder holds settings, agents, and skills.

Instructions
CLAUDE.md
Sits at the project root. Loads automatically.
Config Folder
.claude/
Holds skills, agents, rules, and settings.
Skills
.claude/skills/<name>/SKILL.md
Slash commands you can build yourself.
Sub-Agents
.claude/agents/<name>.md
Markdown with a small header on top.
Settings
.claude/settings.json
Hooks, permissions, env vars.
Global Config
~/.claude/
Same structure, but applies to every project on your machine.
Codex

OpenAI's coding agent

Config and agents live in .codex. Skills live in .agents.

Instructions
AGENTS.md
Sits at the project root. Loads automatically.
Temp Override
AGENTS.override.md
Quick way to override AGENTS.md without editing it.
Config Folder
.codex/
Holds config and agent definitions.
Skills Folder
.agents/skills/<name>/SKILL.md
Codex scans from your current directory up to the repo root.
Sub-Agents
.codex/agents/<name>.toml
TOML format, not markdown.
Settings
.codex/config.toml
Sandbox, MCP servers, env vars, profiles.
Global Config
~/.codex/ and ~/.agents/skills/
Global config/agents live in ~/.codex. Global skills live in ~/.agents/skills.
3

What It Looks Like in Your Folder

Claude keeps everything in one folder. Codex splits config and skills into two folders.

Claude Code

your-project/
  CLAUDE.md
  .claude/
    settings.json
    agents/
      researcher.md
    skills/
      youtube-video/
        SKILL.md

Codex

your-project/
  AGENTS.md
  .codex/
    config.toml
    agents/
      researcher.toml
  .agents/
    skills/
      youtube-video/
        SKILL.md
Claude Code files Codex files Shared (any tool)
4

The Cheat Sheet

When you forget where something lives, this table has the answer.

What You Need
Claude Code
Codex
Project instructions
CLAUDE.md
AGENTS.md
Project config folder
.claude/
.codex/
Where skills live
.claude/skills/<name>/SKILL.md
.agents/skills/<name>/SKILL.md
Where sub-agents live
.claude/agents/<name>.md
.codex/agents/<name>.toml
Agent file format
Markdown + YAML header
TOML
Hooks / permissions / env
.claude/settings.json
.codex/config.toml
Personal / temp override
CLAUDE.local.md
AGENTS.override.md
Global config
~/.claude/
~/.codex/ + ~/.agents/skills/
User-wide instructions
~/.claude/CLAUDE.md
~/.codex/AGENTS.md
Scoped subfolder instructions
Nested CLAUDE.md
Nested AGENTS.md
5

5 Things That Trip Up Beginners

Worth reading before you start. These are the differences you can't paper over.

1

Both tools have skills, in different folders.

Claude reads from .claude/skills/. Codex reads from .agents/skills/. Same basic SKILL.md shape, but Claude-specific tool names or hooks may need small edits for Codex.

2

Different formats for agents.

A Claude agent is a .md file with a small YAML header. A Codex agent is a .toml file. The instructions inside are the same idea, just wrapped differently.

3

Settings files are not interchangeable.

You can't copy .claude/settings.json into .codex/config.toml. They're different formats and configure different things. Keep them separate.

4

Codex reads nested instructions.

Both tools support a CLAUDE.md or AGENTS.md inside a subfolder for scoped instructions. Codex chains them from the repo root down to your current directory. The closer file wins.

5

Sub-agents work differently.

Claude agents are markdown files. Codex agents are TOML files. The role prompt can be similar, but the wrapper and execution model are different.

✓

Bonus: keep shared context out of tool folders.

Put reusable knowledge in docs/, references/, and templates/. Then both tools can read the same source instead of drifting apart.

6

The Tool-Agnostic Setup

Split your project into three layers. Shared knowledge in one place, workflows in another, tool-specific config in their own folders.

The Three-Layer Rule

Separate content this way and you never write the same thing twice.

1
Shared Knowledge

Lives in references/, docs/, templates/. Any agent reads it. Don't duplicate.

2
Workflows (Skills)

Same basic SKILL.md shape in two folders: .claude/skills/ for Claude, .agents/skills/ for Codex. Sync the files, then adapt tool-specific details if needed.

3
Tool-Specific Config

Stays in .claude/ and .codex/. These don't overlap. Don't try to merge them.

7

The Fastest Way to Convert a Claude Project

Open the Claude-built project in Codex and paste this prompt. Codex can create the adapter files for you.

I built this project in Claude Code and want it to also work well in Codex.

Please inspect the project and create a Codex adapter setup.

Do these things:

  1. Create AGENTS.md at the project root.
    • Use CLAUDE.md as the source of project knowledge.
    • Do not duplicate long sections unnecessarily.
    • Explain that AGENTS.md is the Codex-facing adapter.
    • Include a clear project map.
  2. Create .codex/config.toml.
    • Start with a minimal safe config.
    • Do not add secrets.
  3. Create .agents/skills/.
    • Copy important Claude skills from .claude/skills/ into .agents/skills/.
    • Keep each SKILL.md and supporting files together.
    • Do not put skills in .codex/skills/.
  4. Create .codex/agents/ for any important Claude agents.
    • Claude agents are .md files in .claude/agents/.
    • Codex agents are .toml files in .codex/agents/.
    • Convert the agent instructions into developer_instructions.
  5. Update .gitignore if needed.
    • Keep local overrides and secrets out of git.

Before editing, show me the files you plan to create or change.

The whole conversion idea: do not rebuild the project. Add a Codex layer beside the Claude layer.

8

How to Maintain It

The setup only works if both tools stay in sync. These are the habits that matter.

When you update project instructions: keep CLAUDE.md and AGENTS.md aligned.

Do not maintain two full copies. Pick one as the source of truth and make the other an adapter.

When you create a Claude skill: also copy it to .agents/skills/ if Codex should use it.
When you create a Claude agent: also create a matching .codex/agents/<name>.toml if Codex should spawn it.
When you add shared knowledge: put it in docs/, references/, or templates/ so every tool can read the same source.

Global vs project: both tools support both Global files live in your home folder and apply everywhere. Project files live inside one repo. Claude mirrors .claude/ into .claude/, Codex splits global files: ~/.codex/ for config and agents, ~/.agents/skills/ for skills.

Tool-Agnostic Coding Agent Setup · AI Solopreneur