Config option to skip the ~/.agents/skills root for an isolated CODEX_HOME
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 125k
- Forks
- 19.4k
- PR merge metrics
- PR metrics pending
Description
What version of Codex CLI is running?
codex-cli 0.154.0
What platform is your computer?
macOS arm64
What issue are you seeing?
We run Codex from isolated homes: each run sets CODEX_HOME to a generated
directory that carries its own curated skills/, config.toml and MCP servers.
Everything in that home is respected, except one skill root. Codex always adds
$HOME/.agents/skills to the catalog, and no configuration can remove it.
In codex-rs/ext/skills/src/host_roots.rs, roots_from_layer_stack pushes
home_dir().join(".agents").join("skills") for the User config layer
unconditionally. home_dir() reads $HOME, so the root is independent of
CODEX_HOME.
The existing controls cannot express "not this root":
[[skills.config]]selects one skill by exactnameor exactSKILL.md
path. It has no directory or prefix match, so disabling the root means
enumerating the operator's skills, which an isolated home cannot know in
advance and which drifts as skills are installed.skills.bundled.enabledcovers bundled skills only.skills.include_instructions = falseremoves every skill, including the
home's own.
The only working lever is launching with HOME pointed at an empty directory,
which also hides git identity, SSH keys and other tools' credentials from the
agent's shell.
The same root leaks into Codex's own test suite (#38906).
What steps can reproduce the bug?
-
Put any skill in
~/.agents/skills/<name>/SKILL.md. -
Create an isolated home with no skills of its own:
mkdir -p /tmp/iso-home /tmp/work cd /tmp/work -
Render the prompt with and without the real
HOME:CODEX_HOME=/tmp/iso-home codex debug prompt-input "hi" | grep -o 'SKILL\.md)' | wc -l HOME=$(mktemp -d) CODEX_HOME=/tmp/iso-home codex debug prompt-input "hi" | grep -o 'SKILL\.md)' | wc -l
With 38 skills in ~/.agents/skills, the first catalog lists 43 skills (38
from ~/.agents/skills, 5 bundled). The second lists the 5 bundled skills.
The skill roots table in the first render names ~/.agents/skills as r0.
What is the expected behavior?
A user-layer option that stops Codex from adding the $HOME/.agents/skills
root, for example:
[skills]
include_agents_dir = false # default true: current behaviour
Honoured from the user and session layers, consistent with how
skills.config is scoped today (see the discussion in #24237 and #20210), so
-c skills.include_agents_dir=false also works for a single launch. Repository
.agents/skills discovery and $CODEX_HOME/skills stay unchanged.
The change is local to roots_from_layer_stack: guard the
home_dir.join(AGENTS_DIR_NAME) push on the resolved option.
Additional information
Related but distinct: #24237 asks for project-scoped per-skill filtering. This
request is a root-level switch in user config, so an isolated CODEX_HOME can
be fully isolated without changing HOME.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in codex-rs/ext/skills/src/host_roots.rs at roots_from_layer_stack and trace how skills options are resolved from the user and session layers. Reproduce with the provided codex debug prompt-input commands, then verify the option removes only $HOME/.agents/skills while CODEX_HOME/skills, repository .agents/skills, and bundled skills remain available.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 84/100