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

Resolved 💬 2 comments Opened Apr 2, 2026 by sdi2200262 Closed Apr 2, 2026

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 ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗