Codex cli doesn't see symlinked SKILL.md file in ~/.codex/skills/$skillName/

[erikhuizinga]

What version of Codex is running?

0.86.0

What subscription do you have?

Business/Enterprise (not sure)

Which model were you using?

gpt-5.2-codex

What platform is your computer?

Darwin 24.6.0 arm64 arm

What terminal emulator and version are you using (if applicable)?

iTerm2 Build 3.6.6

What issue are you seeing?

I'm facing an issue with skills and Codex CLI. I created my first skill in a SKILL.md file outside of ~/.codex/skills/. From ~/.codex/skills/$skill-name/ I symlinked to the actual SKILL.md file. Codex doesn't seem to see the skill.

• I tried starting a new Codex session in a fresh terminal: /skills doesn't list the skill. And asking for something that should trigger the skill doesn't trigger it.
• I validated the skill and it is valid. (I ran (let Codex cli run) https://github.com/agentskills/agentskills/tree/main/skills-ref to validate the skill in ~/.codex/skills/$skill-name/SKILL.md, which prints Valid skill: $pathToSkillDir.)
• Codex cli does see skills installed from the default skills repo it can install skills from.
• Codex cli does see my custom skills if I copy instead of symlink it.

What steps can reproduce the bug?

Uploaded thread: 019bbd15-f127-7c92-a814-4341dd91b1f5

What is the expected behavior?

Symlinked skills are supported.

Additional information

No response

[etraut-openai]

We support symlinks to a skill directory, not the SKILL.md file itself. The SKILL.md file is generally associated with other files like scripts, and the directory acts as the "package" for the skill.

Is there a reason you want to link to the SKILL.md file?

[xl-openai]

I removed support for symlinking directly to SKILL.md in my recent PR.
A skill is more than just the SKILL.md file—it also includes scripts and other assets—so pointing to the parent folder is clearer.
That said, I’m open to adding SKILL.md symlink support back if there’s a strong reason.

[erikhuizinga]

If linking to a skill dir works, I'm happy with that possibility. Thanks!