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.
2 Comments
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
I have already fixed this locally and pushed the fix to my fork.
Branch: https://github.com/vegerot/codex/tree/mchcopl/bugfixes-skills-symlink-source-build
Relevant commit in that branch:
a99d20f4a9c3(fix(skills): Load symlinked skill files)This branch contains a change that loads symlinked
SKILL.mdfiles directly instead of only following symlinked directories. If this approach looks acceptable, please merge the branch or cherry-pick the fix commit.