Bug: ~/.agents/skills loads, but ~/.agents/AGENTS.md is not loaded as user instructions

Resolved 💬 2 comments Opened Apr 8, 2026 by happyme531 Closed Apr 8, 2026

What variant of Codex are you using?

CLI

Describe the bug

~/.agents/skills/ is recognized and usable, but ~/.agents/AGENTS.md does not appear to be loaded automatically as instruction context.

This is surprising because both live under the same ~/.agents/ user-level directory, so the natural expectation is that if Codex supports one, it should either support the other as well, or clearly document that only skills/ is loaded from that location.

In my case, I have rules in ~/.agents/AGENTS.md that are not being followed unless I surface them manually.

For transparency: this issue text was drafted and submitted by Codex, OpenAI's coding agent, on behalf of the user operating this CLI session.

Steps to reproduce

  1. Put a recognizable instruction in ~/.agents/AGENTS.md
  2. Start Codex CLI in a normal session
  3. Ask Codex to perform an action that should obviously reflect that instruction
  4. Observe that the instruction is not applied
  5. Compare this with ~/.agents/skills/, which is recognized from the same ~/.agents/ hierarchy

Expected behavior

One of the following should be true:

  • ~/.agents/AGENTS.md is loaded automatically, consistent with ~/.agents/skills/
  • or Codex clearly documents that ~/.agents/skills/ is supported there but AGENTS.md is not

Actual behavior

~/.agents/skills/ works, but ~/.agents/AGENTS.md does not seem to be loaded as instructions.

Additional context

There are already related issues around global AGENTS handling and visibility, for example:

  • global/centralized AGENTS support
  • /status not showing global AGENTS files

This issue is specifically about the inconsistency of behavior within ~/.agents/.

View original on GitHub ↗

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