🟣 Anatomy of Codex

Markdown file in the project root that Codex injects into the system prompt at the start of the session. It serves the same purpose as CLAUDE.md—the name is the only difference.

People migrating from Claude Code copy CLAUDE.md and rename it. That works in 90% of cases. The remaining 10% have gotchas: backtick-bang syntax (dynamic injection) won't work, and very long descriptions may be truncated.

Global hierarchy (~/.codex/AGENTS.md) vs. project, no native dynamic injection, ideal size more conservative than Claude.

Codex separates what’s specific to you (.codex/ — config.toml, agents/) than open spec (.agents/skills/ — follows the Agent Skills standard). A convention that respects the separation between config and extension.

People expecting "everything in one folder" like in Claude get confused. Skills in Codex are stored in ~/.agents/skills/ globally and in ./.agents/skills/ per project.

“Config in .codex, extensions in .agents” standard, interoperability with other tools that use .agents/, separation of responsibilities.

File in ~/.codex/config.toml or ./.codex/config.toml: default model, approval profile, sandbox mode, MCP servers, model providers, network access.

Codex uses TOML instead of JSON. Different syntax — keys in [section], arrays in [[array.section]]. It’s not harder, but it’s DIFFERENT.

Basic TOML syntax, profiles ([profiles.work]), sandbox levels, model provider override, env interpolation.

Sub-agents in Codex are files .toml in .codex/agents/. They have fields such as name, description, model, tools e instructions (multiline string with the system prompt).

People coming from Claude expect markdown. The Codex agent is structure — you don't write a "system prompt in prose"; you fill in the fields of a struct.

Multiline string in TOML ("""..."""), EXPLICIT invocation (no auto-dispatch), namespace by file, manual parallelism.

In Codex, sub-agents are NOT automatically triggered by the description. You need to call them by name: "use o agent code-reviewer para revisar X". Without this, the agent simply won’t run.

It’s the #1 mistake when migrating. “Why isn’t my agent being called?” — because you didn’t call it. You write the description thinking it will trigger, but it won’t. Trade-off: predictability vs. convenience.

Invocation by name, with the advantage of control (no surprises) and the disadvantage of less convenience; the pattern is "I mention the agent in the prompt".

Codex has a configurable sandbox in config.toml: read-only (only reads), workspace-write (writes to the project), full (freeform). And approval modes that control when to ask for confirmation.

It's Codex's security granularity. More explicit than Claude Code's, and configured via toml. Confusing at first, but robust once you understand it.

Per-session vs. global sandbox, filesystem write scope, network gating, profiles that combine (danger-full-access, safe-readonly).

Codex also supports custom slash commands, usually as files in .codex/commands/ or via prefixed skills. Argument syntax and namespacing differ from Claude.

To port your favorite slash commands. Most convert 1:1; some need adapting (especially if they use Claude’s dynamic injection).

Folder convention, minimal frontmatter, no backtick-bang, alternatives for dynamic injection (script + prompt).

Codex skills live in ~/.agents/skills/<nome>/ (global) or ./.agents/skills/<nome>/ (project). Why? Because .agents/ is the convention used by the open spec — it works with any compatible tool.

Who expects .codex/skills/ put the skill there and it doesn’t work. Small detail, big consequence: the skill is invisible to the agent.

Open vs. proprietary conventions, automatic portability to other tools, manual reload (Plugins → refresh).

The SKILL.md file itself is almost identical: YAML frontmatter with name e description, Markdown body. The Agent Skills spec defines exactly these 4 elements as common.

Knowing EXACTLY what’s shared lets you write most of the skill once. Everything outside these 4 elements requires an adapter.

The 4 pillars (SKILL.md, name, description, body + scripts/references/assets); everything outside these is runtime-specific.

Optional file agents/openai.yaml inside the skill folder. Loads UI-specific metadata (branding, icon), declarations for required MCP servers, and behavior flags.

Without the sidecar, your skill works, but misses refinements: it appears without an icon or branding, and MCP dependencies have to be installed manually. With the sidecar, installation is turn-key.

Sidecar YAML structure, supported fields (mcp_servers, branding, hidden), opt-in (doesn't block basic functionality).

Codex has an undocumented limit (~8K characters) on the length of a skill's description when it's indexed in the catalog. Anything longer gets truncated, and the skill loses its triggers.

A large skill imported from Claude may have a long description that works well there but fails in Codex. Polyskill anticipates this and rewrites it.

Hidden limit, silent behavior (no error), "front-loading" technique (move triggers to the top), polyskill as an automatic solution.

Codex doesn’t interpret backtick-bang as pre-prompt shell execution. Claude skills that depend on this need to be adapted: turn it into a prose instruction ("run `git status` and analyze") or a called script.

It's the difference that most often breaks portability for Claude skills. Polyskill automatically translates it into fallback prose.

Build-time vs. runtime injection, fallback prose, delegated script, idempotency.

MCP servers declared in [mcp_servers.<nome>] within the config.toml, or in a sidecar openai.yaml of the skill. Same MCP spec, same protocol, different declaration.

To connect Slack, Gmail, GitHub, etc. to Codex. The command, args, and env vars are the same as in Claude—only the file format changes (TOML/YAML instead of JSON).

JSON↔TOML mapping for MCP, sidecar as the recommended location for skill dependencies, env interpolation in TOML.

Codex uses $nome-skill instead of /nome-skill to invoke a skill explicitly. Same idea, different abbreviation. Slash commands still exist for built-in commands.

Typing reflex / in Codex, it becomes an internal command, not a skill. A small source of friction that goes away after 1 day of use.

Separate slash (built-in) × dollar (skill), kebab-case naming, auto-complete available, aliases supported.