Shared context for coding agents — a setup guide

This is the version to keep open while you work. You open it mid-setup, check file names, and tick off steps. All the project knowledge stays in shared directories; each tool only gets the adapter files it expects, and those point back to the same source.

The rule in one sentence: don't duplicate project knowledge — give each tool the file it expects, and keep the content itself in one place.

The problem in one paragraph

Every coding agent needs three things: instructions, repeatable workflows, and tool settings. The problem is that each tool names these files differently.

• Claude Code looks for CLAUDE.md and a .claude/ directory.
• Codex looks for AGENTS.md, a .codex/ directory, and .agents/skills/.

The fix: give each tool the files it expects, but keep the real project knowledge in shared directories — docs/, references/, templates/. Both tools read the same source. Only the adapter files differ.

File map — what lives where

Claude Code (Anthropic's coding agent)

Everything lives in one directory: settings, agents, skills.

• Instructions — CLAUDE.md. Sits at the project root. Loads automatically.
• Config directory — .claude/. Holds skills, agents, rules, and settings.
• Skills — .claude/skills/<name>/SKILL.md. Slash commands you build yourself.
• Sub-agents — .claude/agents/<name>.md. Markdown with a short YAML header on top.
• Settings — .claude/settings.json. Hooks, permissions, environment variables.
• 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 separately, in .agents.

• Instructions — AGENTS.md. Sits at the project root. Loads automatically.
• Temporary override — AGENTS.override.md. A quick way to override AGENTS.md without editing it.
• Config directory — .codex/. Holds configuration and agent definitions.
• Skills directory — .agents/skills/<name>/SKILL.md. Codex scans upward from the current directory to the repo root.
• Sub-agents — .codex/agents/<name>.toml. TOML format, not markdown.
• Settings — .codex/config.toml. Sandbox, MCP servers, environment variables, profiles.
• Global config — ~/.codex/ and ~/.agents/skills/. Global config and agents live in ~/.codex; global skills live in ~/.agents/skills.

Global vs project-level

Both tools support both levels. Global files sit in your home directory and apply everywhere; project files sit inside a single repository.

• ~/.claude/ mirrors .claude/.
• Codex splits its global files: ~/.codex/ for config and agents, ~/.agents/skills/ for skills.

What it looks like on disk

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

One project supporting both tools

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

  .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 — every agent reads it
    project-context.md

Three colors of files worth keeping in mind: Claude Code files, Codex files, and shared files (either tool reads them).

Cheat sheet — where things live

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

Five things beginners trip on

Read this before you start. These are differences you can't route around.

1. Both tools have skills, but in different directories. Claude reads from .claude/skills/, Codex reads from .agents/skills/. The basic SKILL.md shape is the same, but Claude-specific tool names or hooks may need small adjustments for Codex.

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

3. Settings files aren't 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 subdirectory, scoped to that location. Codex chains them from the repo root down to your current directory. The closer file wins.

5. Sub-agents behave differently. Claude agents are markdown files, Codex agents are TOML files. The role prompt can be similar, but the wrapper and the execution model differ.

Bonus: keep shared context outside the tool directories. Put reusable knowledge in docs/, references/, and templates/. Then both tools read the same source instead of drifting apart.

The three-layer rule

Split the project into three layers. Divide content this way and you'll never write the same thing twice.

1. Shared knowledge. Lives in references/, docs/, templates/. Every agent reads it. Don't duplicate it.
2. Workflows (skills). The same basic SKILL.md shape in two directories: .claude/skills/ for Claude, .agents/skills/ for Codex. Keep the files in sync, then tune tool-specific details if you need to.
3. Tool-specific configuration. Stays in .claude/ and .codex/. These don't overlap. Don't try to merge them.

The fast path: converting a Claude project to Codex

Open a project built in Claude inside Codex and paste the prompt below. Codex creates the adapter files for you.

I built this project in Claude Code and I want it to also work well in Codex. Review the project and create the Codex adapter configuration. Do the following: 1. Create AGENTS.md at the project root. - Use CLAUDE.md as the source of project knowledge. - Don't duplicate unnecessarily long sections. - Explain that AGENTS.md is the Codex-side adapter. - Include a readable project map. 2. Create .codex/config.toml. - Start from a minimal, safe configuration. - Don't add secrets. 3. Create .agents/skills/. - Copy the important Claude skills from .claude/skills/ into .agents/skills/. - Keep each SKILL.md together with its companion files. - Don't put skills in .codex/skills/. 4. Create .codex/agents/ for the important Claude agents. - Claude agents are .md files in .claude/agents/. - Codex agents are .toml files in .codex/agents/. - Translate the agent's instructions into developer_instructions. 5. Update .gitignore if needed. - Keep local overrides and secrets out of git. Before you start editing, show me the files you plan to create or change.

The whole idea of the conversion: don't rebuild the project — add a Codex layer alongside the Claude layer.

Keeping it in sync over time

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. Don't maintain two full copies. Pick one file as the source of truth and make the other the adapter.
• When you create a Claude skill — copy it into .agents/skills/ too, if Codex should use it.
• When you create a Claude agent — create a matching .codex/agents/<name>.toml too, if Codex should run it.
• When you add shared knowledge — put it in docs/, references/, or templates/, so every tool reads the same source.

---

There's one pattern here: adapter files thin, knowledge thick and in one place. If a third coding agent ever joins, you add it another set of adapter files pointing at the same docs/, references/, and templates/ — and touch nothing else.