Feature request: configurable additional skill directories with precedence/fallback for user skills

Resolved 💬 2 comments Opened Mar 19, 2026 by woongaro Closed Apr 19, 2026

What feature would you like to see?

Add support for configurable additional user skill directories with deterministic precedence/fallback.

Problem

Codex currently appears to load user skills from a single path ($CODEX_HOME/skills, default ~/.codex/skills). That makes it awkward to combine:

  • Codex-only skills installed and managed in ~/.codex/skills
  • shared skills maintained in another user-owned directory, such as ~/.claude/skills

Today the workable workaround is to materialize shared skills back into ~/.codex/skills via symlinks and keep a manual sync script for new shared skills.

AGENTS.md can document the policy, but it cannot change skill discovery or precedence.

Requested behavior

Please support multiple user skill roots in Codex configuration, with deterministic precedence/fallback.

Example shape:

[skills]
paths = ["~/.codex/skills", "~/.claude/skills"]
precedence = "first-match"

Desired capabilities:

  • configure multiple user skill directories in config.toml
  • define deterministic precedence/fallback across those directories
  • display the origin/path of each resolved skill
  • make duplicate-name resolution explicit and predictable
  • optionally allow explicit selection by origin/path

Example use case

I want this resolution model:

  1. Check ~/.codex/skills first for Codex-only skills and locally installed skills
  2. If a skill is not there, fall back to ~/.claude/skills

That would let me:

  • keep Codex-native installs in their expected location
  • share a second skill library across agents
  • avoid symlink farms and manual sync scripts
  • avoid trying to misuse AGENTS.md for something that should be loader/config behavior

Why this matters

This would make skill management much simpler for users who:

  • have both agent-specific and shared skill libraries
  • want predictable duplicate resolution
  • need to preserve the default install path for Codex-managed skills
  • want less filesystem workaround logic

Acceptance criteria

  • Codex can load skills from more than one configured user path
  • precedence/fallback order is configurable and deterministic
  • skill origin is visible in CLI/app surfaces
  • duplicate name handling is explicit
  • documentation explains how shared skill libraries should be configured

Related issue

This is related to #12194, but is broader: the request here is not just origin visibility or collision handling, but first-class support for multiple configured skill roots with precedence/fallback.

View original on GitHub ↗

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