Tool-Agnostic Coding Agent Setup

A plain-English guide to setting up your project so Claude Code and Codex can both work from the same context. The same pattern can support other coding agents too.

1 · The Problem in 30 Seconds

Every AI coding agent needs instructions, reusable workflows, and tool settings. Each tool names those files differently.

Claude Code looks for CLAUDE.md and .claude/.

Codex looks for AGENTS.md, .codex/, and .agents/skills/.

The fix: give each tool the files it expects, but keep your real project knowledge in shared folders like docs/, references/, and templates/.

Both tools can use the same project knowledge. They just need different adapter files.

2 · How Each Tool Organizes a Project

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

Claude Code · Anthropic’s coding agent

One folder holds settings, agents, and skills.

Codex · OpenAI’s coding agent

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

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

Combined tool-agnostic folder structure

your-project/
  CLAUDE.md                # Claude instructions
  AGENTS.md                # Codex instructions
  README.md                # Human overview

  .claude/                 # Claude settings, agents, skills
    settings.json
    agents/my-agent.md
    skills/my-skill/SKILL.md

  .codex/                  # Codex settings and agents
    config.toml
    agents/my-agent.toml

  .agents/                 # Codex skills
    skills/my-skill/SKILL.md

  references/              # Shared knowledge any agent can read
    project-context.md

Claude Code files · Codex files · Shared (any tool)

4 · The Cheat Sheet

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

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 Project

Pick your direction. Open the project in the target tool and paste the prompt. It creates all the adapter files for you.

Claude Code → Codex

Open your Claude Code project in Codex and paste this prompt.

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 in TOML format.

5. Update .gitignore if needed.
   - Keep local overrides and secrets out of git.
   - Add AGENTS.override.md to .gitignore.

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

Codex → Claude Code

Open your Codex project in Claude Code and paste this prompt.

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

Please inspect the project and create a Claude Code adapter setup.

Do these things:

1. Create CLAUDE.md at the project root.
   - Use AGENTS.md as the source of project knowledge.
   - Do not duplicate long sections unnecessarily.
   - Explain that CLAUDE.md is the Claude-facing adapter.
   - Include a clear project map showing where everything lives.

2. Create .claude/settings.json.
   - Start with a minimal safe config: empty permissions, hooks, and env objects.
   - Do not copy secrets or API keys from .codex/config.toml.

3. Create .claude/skills/ from .agents/skills/.
   - Copy each skill folder from .agents/skills/ into .claude/skills/.
   - Keep each SKILL.md and any supporting files together.
   - Claude skills are triggered as slash commands. Note this in each SKILL.md if it isn't already.

4. Create .claude/agents/ from .codex/agents/.
   - Codex agents are .toml files in .codex/agents/.
   - Claude agents are .md files in .claude/agents/.
   - Each Claude agent needs a small YAML front matter block at the top:
       ---
       name: Agent Name
       description: One-line description of what this agent does
       ---
   - Move the developer_instructions content into the markdown body below the front matter.

5. Update .gitignore if needed.
   - Add CLAUDE.local.md so personal overrides stay out of git.
   - Keep .env and any credential files gitignored.

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

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.