Sub-agent `[[skills.config]]` in agent TOML is ignored for both disable and enable overrides

Resolved 💬 0 comments Opened Mar 10, 2026 by ImJamesBarrett Closed Mar 16, 2026

Summary

The Codex multi-agents docs say sub-agents can enable or disable skills in their TOML file. In practice, agent-local [[skills.config]] does not appear to be respected in either direction:

  • disabling a skill for a specific agent does not remove it for that agent
  • enabling a skill for a specific agent when it is disabled globally does not make it available to that agent

Docs referenced

The Multi-agents docs include an example like:

[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false

which implies per-agent skill scoping is supported.

Expected behaviour

Agent-local [[skills.config]] should allow sub-agents to override skill availability on a per-agent basis.

Two cases should work:

  1. Disable a default-available skill for one agent:
[[skills.config]]
path = "/absolute/path/to/SKILL.md"
enabled = false

Expected result: that skill is not available to that sub-agent.

  1. Enable a globally disabled skill for one agent:

Global ~/.codex/config.toml:

[[skills.config]]
path = "/absolute/path/to/SKILL.md"
enabled = false

Agent TOML:

[[skills.config]]
path = "/absolute/path/to/SKILL.md"
enabled = true

Expected result: that skill is available to that sub-agent only.

Actual behaviour

Neither direction appears to work:

  • agent-local enabled = false does not disable the skill for that agent
  • agent-local enabled = true does not re-enable a globally disabled skill for that agent

This makes the agent-local skills.config setting appear to have no effect.

Minimal repros

Case 1: disable per agent

  1. Create exactly one skill under $HOME/.agents/skills/.../SKILL.md.
  2. Do not define any global [[skills.config]] in ~/.codex/config.toml.
  3. Define one custom sub-agent in an agent TOML with:
[[skills.config]]
path = "/absolute/path/to/the/skill/SKILL.md"
enabled = false
  1. Spawn that sub-agent.

Result: the agent-local disable does not appear to be honoured.

Case 2: enable only for one agent

  1. Create exactly one skill under $HOME/.agents/skills/.../SKILL.md.
  2. Disable it globally in ~/.codex/config.toml:
[[skills.config]]
path = "/absolute/path/to/the/skill/SKILL.md"
enabled = false
  1. Define one custom sub-agent in an agent TOML with:
[[skills.config]]
path = "/absolute/path/to/the/skill/SKILL.md"
enabled = true
  1. Spawn that sub-agent.

Result: the agent-local enable does not appear to override the global disable.

What was verified

  • The agent TOML parses correctly as valid TOML.
  • [[skills.config]] is a top-level table and is not nested incorrectly.
  • The skill path is correct.
  • Both override directions were tested:
  • default available -> disabled per agent
  • disabled globally -> enabled per agent
  • The observed behaviour still does not match the docs.

Environment

  • Codex desktop
  • Codex CLI

Impact

This breaks the expected role specialisation model for sub-agents. If agent-local skill enable/disable is ignored, skills cannot be scoped cleanly to only the agents that need them.

That defeats a core use case for specialised sub-agents:

  • globally available skills cannot be excluded from agents that should not use them
  • globally disabled skills cannot be selectively enabled for the agents that do need them

View original on GitHub ↗