Skill discovery ignores symlinked SKILL.md files

Open 💬 1 comment Opened Jul 8, 2026 by pmarreck

What happened?

Codex discovers a user skill when SKILL.md is a regular file, but skips the same skill when SKILL.md is a symlink to a valid file.

This makes it awkward to maintain one canonical skill document and expose it from multiple agent-specific skill directories. A hardlink works as a workaround, but a symlink is the more normal Unix layout for this kind of shared file.

Steps to reproduce

mkdir -p /tmp/codex-skill-source/demo
cat > /tmp/codex-skill-source/demo/SKILL.md <<'SKILL'
---
name: demo
description: Demo skill.
---

# Demo
SKILL

mkdir -p ~/.codex/skills/demo
ln -s /tmp/codex-skill-source/demo/SKILL.md ~/.codex/skills/demo/SKILL.md

Restart Codex or force a skill reload, then inspect the available skills. The demo skill is not listed. Replacing the symlink with a regular file or hardlink makes the skill appear.

Expected behavior

For user, repo, and admin skill roots, Codex should accept a symlinked SKILL.md when the symlink target is a regular file.

System-bundled skills can keep their stricter no-symlink behavior.

Actual behavior

The scanner follows directory symlinks for user/repo/admin skills, but skips file symlinks before checking whether the basename is SKILL.md.

Environment

  • OS: Linux
  • Reproduced with user-scoped skills under ~/.codex/skills

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗