Cannot read a symlinked SKILL.md file
What version of Codex is running?
0.94.0
What subscription do you have?
Enterprise & Edu
Which model were you using?
_No response_
What platform is your computer?
Darwin 24.6.0 arm64 arm
What terminal emulator and version are you using (if applicable)?
_No response_
What issue are you seeing?
Relates to: https://github.com/openai/codex/issues/8369
The symbolic link for SKILL.md is not being recognized by the codex-cli. Below is the current state of the file in my environment:
❯ ls -la /Users/tttol/.codex/skills/code-review
total 0
drwxr-xr-x@ 3 tttol staff 96 Feb 3 10:49 .
drwxr-xr-x@ 11 tttol staff 352 Feb 3 06:26 ..
lrwxr-xr-x@ 1 tttol staff 97 Feb 3 10:49 SKILL.md -> /nix/store/a4ikyxv2q0pxn26zrgfc9cwyz00ypx5a-home-manager-files/.codex/skills/code-review/SKILL.mdWhile PR #8801 was supposed to have addressed this, the issue persists in the latest version (v0.94.0); symbolic links are still not being loaded correctly.
I noticed const MAX_SCAN_DEPTH: usize = 6; in the source code(https://github.com/openai/codex/blob/3a53f802f7bcafaa2cb8dd5c9b725a4650d9abf0/codex-rs/core/src/skills/loader.rs#L40). Does this depth limit include the path resolved via symbolic links? In my case, the path SKILL.md -> /nix/store/.../SKILL.md reaches a depth of 7. Could this directory depth be the reason why the file isn't being detected?
What steps can reproduce the bug?
Run codex in CLI and press $.
What is the expected behavior?
_No response_
Additional information
_No response_
6 Comments
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
We don't support symlinks for individual SKILL.md files. We do support symlinks for the folder that contains the SKILL.md files. A skill consists of a folder and the files within it, so it doesn't make sense to alias only the SKILL.md file.
@etraut-openai I understand you argument about skills being a unit inside a directory but I am not sure if this has to be directly linked to being able to symlink files _or_ directories.
Symlink managers like GNU Stow can alias files directly instead of directories (using the --no-folding flag) . This is useful if you do not want Stow to manage full directories. For example I have public skills which I dynamically link using Stow to the
~/.codex/skillsdirectory but it also contains other skills.I saw some other recent issues being closed related to symlinking I people are trying to work across multiple coding agents. Being able to symlinks is a more clean way of managing this.
Not sure if this is relevant but this type of symlinking does work in Claude Code, Opencode and Mistral Vibe.
@lhohan @etraut-openai For what it's worth I ran into this issue too. I'd prefer to allow the
--no-folding-style stow runs to work with the purely symlinked files, but alternatively you can structure your dotfiles to _not_ use--no-foldingand use a gitinclude strategy. This lets you symlink directly to the source directory for the skill as mentioned without risking messing with public/private skill concerns.For example my skills repo makes it so when I symlink to the directory directly from here I can add additional skills there without messing with the git state. Takes some effort to setup though and requires the use submodules to maintain a synced state.
@etraut-openai @lhohan @collinmurch
Thanks for comments.
The motivation behind this issue is to bring "skills" file management into the Nix ecosystem. Under a Nix build, SKILL.md is handled as a symlink to the Nix store, for example:
/nix/store/a4ikyxv2q0pxn26zrgfc9cwyz00ypx5a-home-manager-files/.codex/skills/code-review/SKILL.mdSince Nix manages files by symlinking them, I’d love to see Codex support symbolic links as well. As others have pointed out, Claude Code already supports symlinks, so it would be a very welcome addition here.
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.