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

Resolved 💬 3 comments Opened Jan 16, 2026 by erikhuizinga Closed Jan 16, 2026

💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

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_

View original on GitHub ↗

3 Comments

etraut-openai contributor · 7 months ago

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 contributor · 7 months ago

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 · 7 months ago

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