›_ Codex Issues
Codex Issues / #32679

Valid repo skills are partially omitted from fresh session catalogs, including explicit skill invocation

Resolved 💬 2 comments Opened Jul 13, 2026 by justinclagg-epa Closed Jul 13, 2026
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Summary

Fresh Codex CLI 0.144.1 sessions partially omit valid repository skills from the model-visible Available skills catalog. An explicitly named $delegate skill was then reported unavailable, even though its valid repo symlink and SKILL.md were readable and the skill worked immediately after direct filesystem discovery.

Environment

  • macOS
  • Codex CLI 0.144.1
  • ChatGPT authentication
  • Fresh interactive TUI sessions launched at a trusted repository root
  • Repo skills exposed as valid relative symlinked directories under .agents/skills/

Reproduction

  1. Create ten repo skill directory symlinks under .agents/skills/, each pointing to an in-repository skill directory containing valid SKILL.md frontmatter.
  2. Verify every symlink with realpath and parse each name and description.
  3. Start a fresh Codex TUI session from the repository root.
  4. Inspect the injected Available skills catalog.
  5. Prompt: Use the $delegate skill to give work to Codex subagents.

Actual behavior

Only two of the ten repo skills appeared in the injected catalog (linter and morning-brief). The catalog also contained several system/plugin skills, but omitted delegate and seven other valid repo skills. No skill-omission warning appeared.

The agent responded that $delegate was unavailable. After a follow-up instructed it to inspect local skill exposure, it found .agents/skills/delegate/SKILL.md, read it successfully, and used the workflow successfully. Multiple fresh sessions received the same partial repo-skill subset.

This is not a broken-symlink case: every repo skill target resolves inside the repository, metadata parses, and two sibling symlinked skills are discovered from the same directory.

Expected behavior

At least one of the following should occur:

  1. All valid repo skills in this small repo-scoped set appear in the initial catalog.
  2. An explicit $skill-name prompt resolves and loads that discovered skill even if the initial catalog was trimmed.
  3. If skills are omitted due to a context budget or loader error, the session emits the documented warning and provides a reliable lookup path.

The model should not confidently report an explicitly named, valid repo skill as unavailable solely because the injected catalog omitted it.

Impact

Repository workflows and safety fallbacks can silently disappear from fresh sessions. In this case, omission of the delegation skill also hid required same-provider escalation guidance, causing a predictable failed nested Codex launch before the model eventually found the skill manually.

Related issues

  • #16012 was closed after its reporter found an invalid nested symlink; this reproduction uses valid symlinks and partial discovery from the same directory.
  • #11314 primarily concerns broken symlink diagnostics and does not cover valid sibling skills being selectively omitted.

No private paths, prompts, credentials, or full session logs are included in this report.

View original on GitHub ↗

2 Comments

github-actions[bot] contributor · 1 month ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #31592

Powered by Codex Action

rpelevin · 1 month ago

The useful distinction here is between four states: discovered, enabled, included in the model-visible catalog, and explicitly resolvable. They should not collapse into one available/unavailable bit.

In the 0.144.1 source, the skills renderer can omit even minimum catalog lines after the 2% metadata budget is exhausted, with system and admin entries ordered ahead of repo and user entries. Separately, explicit $name resolution scans the loaded skill inventory, and catalog omission creates a warning event. This report suggests the end-to-end join can still fail: a valid repo skill is absent from the catalog, the exact explicit mention does not inject it, and no warning reaches the user.

I would make that join observable with one per-session/turn catalog receipt containing:

  • discovery completion state plus discovered and enabled inventory digests;
  • catalog-included skill refs and omitted refs with reason codes such as metadata_budget, disabled, product_restricted, scan_incomplete, or load_error;
  • warning emitted and warning delivered state;
  • exact explicit mention, name-count result, qualified path if required, and resolution state;
  • injected skill path and content digest, or a typed terminal reason.

The regression anchors I would add are:

  • a low metadata budget omits a repo skill, delivers the warning, and $delegate still resolves against the full enabled inventory;
  • duplicate enabled names require a qualified path rather than arbitrary selection;
  • incomplete discovery is reported differently from a budget omission;
  • an explicit mention cannot re-enable a disabled skill;
  • the model cannot report an exact enabled skill as unavailable while the resolver can still bind it.

That keeps prompt-budget degradation from silently becoming capability denial and gives the TUI, app server, and model context one inspectable truth about what happened.

Boundary: source and conformance feedback only. I have not reproduced the reporter's repository or Codex session, and I have not validated a fix.