Title: Clarify skill discovery roots and install targets
The current Codex skills docs are more explicit than codex-portable about where skills live and how they are discovered.
Current official guidance:
- repo skills are discovered from
.agents/skills while scanning from the current working directory up to the repo root
- personal skills live in
$HOME/.agents/skills
- admin skills live in
/etc/codex/skills
- plugins are the distribution unit when reusable skills should be shared beyond one repo or bundled with app integrations
Current repo posture that looks drifted or at least under-explained:
README.md:18 presents codex/skills/ as the portable skill source treescripts/common.ps1:59-79 maps those repo skills to live paths under $CODEX_HOME/skillsmanifests/portable-files.toml:13-27 also models portable skills through the repo's skills list and the %USERPROFILE%\\.codex home baselinescripts/doctor.ps1:94-106 validates repo codex/skills descriptions but not the current official discovery locations or whether the install target is still the right one
Why this matters:
The repo can reasonably keep an internal source layout that is different from the live discovery layout, but it needs to say that explicitly if it does. Right now the docs are teaching .agents/skills and user or admin layering, while the portable repo still behaves like $CODEX_HOME/skills is the reviewed destination model. That may be stale, or it may be a deliberate mirror of current runtime behavior that simply is not documented.
OpenAI guidance that surfaced this:
Scope:
- verify the current live skill discovery roots on a current Codex install before changing scripts
- decide whether
codex-portable should keep codex/skills/ only as a repo-internal source tree, migrate any live install mapping, or document a deliberate divergence
- update nearby README and maintenance guidance so repo-global skills, project
.agents/skills, and plugin distribution are not blurred together
- keep issue
#28 focused on global versus project skill ownership; this issue is about discovery paths and install targets
Repo references:
README.md:18manifests/portable-files.toml:13-27scripts/common.ps1:47-79scripts/doctor.ps1:94-106local-docs/maintenance-learnings.md:38
Title: Clarify skill discovery roots and install targets
The current Codex skills docs are more explicit than
codex-portableabout where skills live and how they are discovered.Current official guidance:
.agents/skillswhile scanning from the current working directory up to the repo root$HOME/.agents/skills/etc/codex/skillsCurrent repo posture that looks drifted or at least under-explained:
README.md:18presentscodex/skills/as the portable skill source treescripts/common.ps1:59-79maps those repo skills to live paths under$CODEX_HOME/skillsmanifests/portable-files.toml:13-27also models portable skills through the repo'sskillslist and the%USERPROFILE%\\.codexhome baselinescripts/doctor.ps1:94-106validates repocodex/skillsdescriptions but not the current official discovery locations or whether the install target is still the right oneWhy this matters:
The repo can reasonably keep an internal source layout that is different from the live discovery layout, but it needs to say that explicitly if it does. Right now the docs are teaching
.agents/skillsand user or admin layering, while the portable repo still behaves like$CODEX_HOME/skillsis the reviewed destination model. That may be stale, or it may be a deliberate mirror of current runtime behavior that simply is not documented.OpenAI guidance that surfaced this:
Scope:
codex-portableshould keepcodex/skills/only as a repo-internal source tree, migrate any live install mapping, or document a deliberate divergence.agents/skills, and plugin distribution are not blurred together#28focused on global versus project skill ownership; this issue is about discovery paths and install targetsRepo references:
README.md:18manifests/portable-files.toml:13-27scripts/common.ps1:47-79scripts/doctor.ps1:94-106local-docs/maintenance-learnings.md:38