Document name-based selectors for skills.config
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 125k
- Forks
- 19.4k
- PR merge metrics
- PR metrics pending
Description
What is the type of issue?
Documentation is missing.
What is the issue?
The Codex configuration reference documents skills.config, skills.config.<index>.enabled, and the path-based skills.config.<index>.path, but it omits the supported name-based skills.config.<index>.name selector.
This omission matters particularly for plugin-contributed skills. A path selector can contain a versioned plugin-cache directory and become stale when the plugin version changes, while a qualified name selector continues matching the same logical plugin skill:
[[skills.config]]
name = "aws-core:aws-storage"
enabled = false
Please document:
skills.config.<index>.nameas a string selector for an effective skill name.- Plugin-contributed skills use qualified names such as
plugin-name:skill-name. - An entry should set exactly one of
nameorpath; the current implementation ignores entries with both or neither. - Name selectors survive plugin cache/version path changes, but must be updated if the plugin or skill itself is renamed.
This behavior is present in the tagged Codex 0.151.0 source:
- SkillConfig supports both path and name selectors
- Plugin tests disable a skill with a qualified name
The underlying per-plugin-skill use case was previously described in #19268.
Where did you find it?
https://learn.chatgpt.com/docs/config-file/config-reference
The reference currently ends the per-skill selector documentation at skills.config.<index>.path.
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 with the Codex configuration reference at learn.chatgpt.com/docs/config-file/config-reference, then verify the supported fields in codex-rs/config/src/skills_config.rs and the qualified-name example in codex-rs/core-plugins/src/manager_tests.rs. Done means the reference documents the name selector, qualified plugin names, the exclusive name-or-path rule, and rename/cache-version behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 85/100