Skills loader ignores symlinked SKILL.md files (breaks stow/dotfiles setups)
Summary
When skills are installed as symlinked SKILL.md files (common with dotfiles managers like GNU Stow), Codex does not discover/load them.
Symlinked directories are followed for user/admin/repo scopes, but symlinked SKILL.md files are explicitly skipped. This makes it hard to manage ~/.codex/skills via dotfiles without copying files.
Steps to reproduce
- Create a skill file somewhere, e.g.
/tmp/shared/demo/SKILL.md. - Create a user skill folder and symlink the SKILL.md into it:
mkdir -p ~/.codex/skills/demoln -s /tmp/shared/demo/SKILL.md ~/.codex/skills/demo/SKILL.md
- Run Codex and list skills.
Expected behavior
The skill should be discovered/loaded (or at least there should be a clear error / documented limitation).
Actual behavior
No skill is loaded.
Code pointers
In codex-rs/core/src/skills/loader.rs, discover_skills_under_root checks entry.file_type().is_symlink() and only follows symlinks that resolve to directories; symlinks to files are skipped.
There is also an explicit test asserting this behavior: ignores_symlinked_skill_file_for_user_scope.
Why this matters
Tools like GNU Stow manage dotfiles by creating symlinks for the actual files, so ~/.codex/skills/**/SKILL.md ends up being symlinked. Today that means user skills silently disappear unless they’re copied into place as real files.
Possible fixes
- If
follow_symlinksis true for user/admin/repo scopes, consider resolving symlinkedSKILL.mdfiles (and parsing the resolved path) instead of skipping them. - Alternatively, document that only symlinked directories are supported (not symlinked SKILL.md files), and explain recommended dotfiles workflows.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗