Skills loader ignores symlinked SKILL.md files (breaks stow/dotfiles setups)

Resolved 💬 2 comments Opened Feb 10, 2026 by shpoont Closed Feb 10, 2026
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

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

  1. Create a skill file somewhere, e.g. /tmp/shared/demo/SKILL.md.
  2. Create a user skill folder and symlink the SKILL.md into it:
  • mkdir -p ~/.codex/skills/demo
  • ln -s /tmp/shared/demo/SKILL.md ~/.codex/skills/demo/SKILL.md
  1. 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_symlinks is true for user/admin/repo scopes, consider resolving symlinked SKILL.md files (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.

View original on GitHub ↗

2 Comments

github-actions[bot] contributor · 6 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #11314
  • #10976
  • #10470
  • #9365

Powered by Codex Action

vegerot · 4 months ago

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.md files directly instead of only following symlinked directories. If this approach looks acceptable, please merge the branch or cherry-pick the fix commit.