Issue Station
Sign In
Tools hereToolbox

codex - 💡(How to fix) Fix Bug: symlinked SKILL.md files are not discovered as skills [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openai/codex#22506•Fetched 2026-05-14 03:34:58
View on GitHub
Comments
0
Participants
1
Timeline
2
Reactions
0
Author
johnrichardrinehartjohnrichardrinehart
Participants
johnrichardrinehartjohnrichardrinehart
Timeline (top)
closed ×1renamed ×1

Codex currently skips skills where SKILL.md itself is a symlink, even when the skill directory is in a valid root (for example ~/.codex/skills/<name>/SKILL.md).

This breaks common Nix/Home Manager-style installs where skill files are symlinked into home paths.

Root Cause

I cannot open a PR directly because openai/codex is currently collaborators_only for PR creation, but I’m happy to update the branch if maintainers want changes.

Fix Action

Fix / Workaround

Current workaround

Proposed fix (ready patch)

I prepared a patch that treats symlinked SKILL.md as a discoverable skill file (for User/Admin/Repo scopes) and updates regression coverage:

RAW_BUFFERClick to expand / collapse

Summary

Codex currently skips skills where SKILL.md itself is a symlink, even when the skill directory is in a valid root (for example ~/.codex/skills/<name>/SKILL.md).

This breaks common Nix/Home Manager-style installs where skill files are symlinked into home paths.

Repro

  1. Create a normal skill file outside the skills root (or in a shared directory).
  2. Symlink it to ~/.codex/skills/usage-status/SKILL.md.
  3. Start/restart Codex and open skills list / mention picker.

Observed: skill is not listed/discovered.
Expected: skill should be discovered the same way as a non-symlinked SKILL.md.

Scope note

I cannot confirm a released version where this exact file-symlink case worked end-to-end, so this is filed as a bug/behavior gap rather than a confirmed regression.

Current workaround

Symlink the skill directory (or keep directory+SKILL.md as real files) instead of symlinking SKILL.md directly.

Proposed fix (ready patch)

I prepared a patch that treats symlinked SKILL.md as a discoverable skill file (for User/Admin/Repo scopes) and updates regression coverage:

I cannot open a PR directly because openai/codex is currently collaborators_only for PR creation, but I’m happy to update the branch if maintainers want changes.

Thanks!

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#API middleware#SSR setup#ISR setup#authentication setup#request error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

codex - 💡(How to fix) Fix Bug: symlinked SKILL.md files are not discovered as skills [1 participants]