›_ Codex Issues
Codex Issues / #20637

Codex skill discovery silently misses global skill when entry file is SKILL.MD

Open 💬 2 comments Opened May 1, 2026 by KingPsychopath

What version of the Codex App are you using (From “About Codex” dialog)?

Version 26.422.62136 (2180)

What subscription do you have?

Pro

What platform is your computer?

Darwin 25.4.0 arm64 arm

What issue are you seeing?

Codex appeared not to discover a globally installed skill when the skill entry file was named SKILL.MD instead of exactly SKILL.md.

The skill was listed by the generic skills CLI using npx skills ls -g --json. It included better-auth-security-best-practices.

But the skill did not appear in Codex’s available skills for the session, while neighboring skills in the same directory did.

The global skill existed at ~/.agents/skills/better-auth-security-best-practices/SKILL.MD.

Other discovered skills used ~/.agents/skills/<skill-name>/SKILL.md.

After renaming SKILL.MD to SKILL.md, the skill became discoverable by exact SKILL.md scans.

What steps can reproduce the bug?

  1. Install or create a global skill under ~/.agents/skills, for example ~/.agents/skills/example-skill/SKILL.MD.
  2. Ensure the file is named SKILL.MD, not SKILL.md.
  3. Confirm the skill is registered/listed by running npx skills ls -g --json.
  4. Start or use Codex and check the available skills list for the session.
  5. Observe that the skill may be absent from Codex’s available skills, while other skills with exact SKILL.md files are present.
  6. Rename the file from SKILL.MD to SKILL.md.
  7. Check discovery again after refresh/restart.

In my case, the affected path was ~/.agents/skills/better-auth-security-best-practices/SKILL.MD.

I did not prove whether a fresh Codex restart would have loaded SKILL.MD; the observed issue was that the current Codex session did not list the skill while the skills CLI did.

What is the expected behavior?

Codex should either discover skill entry files case-insensitively, at least on macOS, or show a warning when a registered skill folder exists but does not contain an exact SKILL.md.

A registered skill should not be silently absent from Codex’s available skills when the only apparent issue is filename casing.

Additional information

Environment details:

OS: macOS
Platform: Darwin 25.4.0 arm64 arm
Global skills location: ~/.agents/skills
Codex native skills location: ~/.codex/skills
Workaround used:

Renamed SKILL.MD to SKILL.md
Symlinked the global skill folders into ~/.codex/skills
After that, exact scans using find -L ~/.codex/skills -maxdepth 2 -type f -name SKILL.md resolved the skill correctly.

View original on GitHub ↗

2 Comments

mitre88 · 3 months ago

I validated this against the current public core-skills loader.

Root cause I found:

  • codex-rs/core-skills/src/loader.rs discovers skill entry files only when file_name == "SKILL.md".
  • Other paths in the repo already treat skill entry names case-insensitively for mention/config handling, but discovery itself does not.

I prepared a narrow patch on my fork in case maintainers want this route:

Branch: https://github.com/mitre88/codex/tree/fix/skill-md-case-discovery-20637
Compare: https://github.com/openai/codex/compare/main...mitre88:codex:fix/skill-md-case-discovery-20637

Patch scope:

  • make core skill discovery match SKILL.md case-insensitively, so SKILL.MD is discovered;
  • keep exact SKILL.md preferred if a case-sensitive filesystem contains both variants;
  • add regression coverage for both cases.

Validation:

  • cargo fmt --package codex-core-skills --check
  • cargo test -p codex-core-skills skill_file -- --nocapture
  • cargo test -p codex-core-skills
  • git diff --check

No app/runtime behavior outside skill discovery should change. Happy to open the PR if maintainers want external help on this one.

mitre88 · 3 months ago

I refreshed the branch against current main and revalidated the focused regression tests.

Updated branch: https://github.com/mitre88/codex/tree/fix/skill-md-case-discovery-20637
Compare: https://github.com/openai/codex/compare/main...mitre88:codex:fix/skill-md-case-discovery-20637

Validation after rebase:

  • cargo fmt --package codex-core-skills --check
  • cargo test -p codex-core-skills skill_file -- --nocapture
  • git diff --check

This keeps exact SKILL.md preferred when both variants exist, while allowing uppercase SKILL.MD to be discovered. This also looks relevant to #21758.