Use Case
Teams keep reusable automation in .claude/skills, .claude/agents, and .claude/commands, but Codex does not ingest these by default.
This forces manual duplication into AGENTS.md, causes drift, and makes /plan workflows non-portable across Claude Code and Codex.
Proposed Solution
Add an opt-in Claude-compatibility layer in Codex CLI:
- Add config flag:
features.claude_compat = true in codex.toml.
- On session start, scan workspace-local:
.claude/skills/**/SKILL.md
.claude/agents/**/*.md
.claude/commands/**/*.md
- Register discovered entries in Codex runtime as first-class skills/agents/commands.
- Support command alias mapping so
.claude/commands/plan.md can invoke Codex plan workflow (/plan).
- Enforce precedence: system/developer instructions >
AGENTS.md > .claude/*.
Alternatives Considered
- Manual mirroring from
.claude/* into AGENTS.md (high maintenance, drift risk).
- External conversion script per repo (extra tooling burden, inconsistent behavior).
- Keep current behavior (no compatibility) and require explicit prompts each session.
Implementation Notes
- Discovery must be workspace-scoped only (no parent directory traversal).
- Loaded
.claude entries must remain instruction-only unless normal tool permissions allow execution.
- Feature must be disabled by default.
- Reuse existing single-source sync pattern already used in templates (
AGENTS.md -> other agent files via scripts/agent_rules.py + CI check), so Claude-compat discovery does not create a second unsynced source of truth.
- If a better model is introduced, prefer one canonical machine-readable manifest (agent-neutral) and generate
.claude/* + AGENTS.md views from it in CI.
- Acceptance criteria:
- New session auto-lists
.claude skills/agents/commands when enabled.
- Referencing discovered skill/agent uses normal loading behavior.
/plan alias works via mapped command template when enabled.
- No change in behavior when
features.claude_compat is absent or false.
Use Case
Teams keep reusable automation in
.claude/skills,.claude/agents, and.claude/commands, but Codex does not ingest these by default.This forces manual duplication into
AGENTS.md, causes drift, and makes/planworkflows non-portable across Claude Code and Codex.Proposed Solution
Add an opt-in Claude-compatibility layer in Codex CLI:
features.claude_compat = trueincodex.toml..claude/skills/**/SKILL.md.claude/agents/**/*.md.claude/commands/**/*.md.claude/commands/plan.mdcan invoke Codex plan workflow (/plan).AGENTS.md>.claude/*.Alternatives Considered
.claude/*intoAGENTS.md(high maintenance, drift risk).Implementation Notes
.claudeentries must remain instruction-only unless normal tool permissions allow execution.AGENTS.md-> other agent files viascripts/agent_rules.py+ CI check), so Claude-compat discovery does not create a second unsynced source of truth..claude/*+AGENTS.mdviews from it in CI..claudeskills/agents/commands when enabled./planalias works via mapped command template when enabled.features.claude_compatis absent orfalse.