Consolidate config under .codex/ and document .codex/skills/ discovery

Resolved 💬 2 comments Opened Apr 2, 2026 by sdi2200262 Closed Apr 2, 2026
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Skills live in .agents/skills/ per the docs but agent definitions live in .codex/agents/ and config lives in .codex/config.toml. Two unrelated dotfile directories at the project root for the same tool. Claude Code, Cursor, Gemini CLI, and OpenCode all keep everything under one directory (.claude/, .cursor/, etc).

Per #14337, .codex/skills/ already works as a discovery path but isn't documented. Documenting it and making .codex/ the primary location would align with how every other tool in this space works. Projects that ship skills, agent definitions, and config together shouldn't need to split across two directory trees.

Separately, the 28 built-in slash commands are hardcoded with no mechanism for user-defined commands. #13893 covers this — skills with the $ prefix are useful but user-defined /commands are how teams ship named workflows. Both should exist.

Reading all this from the official docs at https://developers.openai.com/codex/skills and https://developers.openai.com/codex/cli/slash-commands.

View original on GitHub ↗

2 Comments

github-actions[bot] contributor · 4 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #14941
  • #15167
  • #15939

Powered by Codex Action

etraut-openai contributor · 4 months ago

There's a good reason these are separate. The .agents directory is an emerging industry standard and is not specific to codex whereas .codex contains codex-specific settings and configuration files.