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

Resolved 💬 2 comments Opened Feb 10, 2026 by shpoont Closed Feb 10, 2026

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 ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗