Bug: symlinked SKILL.md files are not discovered as skills
Summary
Codex currently skips skills where SKILL.md itself is a symlink, even when the skill directory is in a valid root (for example ~/.codex/skills/<name>/SKILL.md).
This breaks common Nix/Home Manager-style installs where skill files are symlinked into home paths.
Repro
- Create a normal skill file outside the skills root (or in a shared directory).
- Symlink it to
~/.codex/skills/usage-status/SKILL.md. - Start/restart Codex and open skills list / mention picker.
Observed: skill is not listed/discovered.
Expected: skill should be discovered the same way as a non-symlinked SKILL.md.
Scope note
I cannot confirm a released version where this exact file-symlink case worked end-to-end, so this is filed as a bug/behavior gap rather than a confirmed regression.
Current workaround
Symlink the skill directory (or keep directory+SKILL.md as real files) instead of symlinking SKILL.md directly.
Proposed fix (ready patch)
I prepared a patch that treats symlinked SKILL.md as a discoverable skill file (for User/Admin/Repo scopes) and updates regression coverage:
- Compare: https://github.com/openai/codex/compare/main...johnrichardrinehart:fix/skills-follow-symlinked-skill-md
- Branch:
johnrichardrinehart/codex:fix/skills-follow-symlinked-skill-md - Commit:
f2580693ea
I cannot open a PR directly because openai/codex is currently collaborators_only for PR creation, but I’m happy to update the branch if maintainers want changes.
Thanks!