Your repository skill exists, but Codex Desktop cannot see it.

Separate a local catalog defect from a Desktop runtime defect.

1. Run from the intended repository root

   Run the audit in the same checkout opened by Codex Desktop. It reports every candidate .agents/skills scope from the current directory to the repository root, using repository-relative paths.

2. Resolve structural findings on disk

   Check metadata failures, BOM warnings, malformed frontmatter, scan errors, possible duplicate names, and the redacted symlinked-candidate count. A valid local candidate is necessary evidence, but not proof that a running Desktop session loaded it.

3. Keep repository skills repository-scoped

   Do not copy the skill into ~/.agents/skills as a workaround. That changes the scope under test and can expose project-specific instructions to unrelated repositories.

4. Collect the native result separately

   After correcting local findings, start a new Desktop session for that checkout and compare the native available-skills list with the audit. Do not use a resumed thread as the post-change check: current Codex reports show its model-visible skill list can remain stale after new skills are added. Record the Desktop version, operating system, project trust state, and exact count of valid local candidates.

Capture deterministic local evidence without dumping private paths.

$ instructree skills . --client codex --json

scopes: user shared · user legacy · repository local
repository candidates: 7
metadata failures: 0
scan errors: 0
possible duplicate names: 0

Use the JSON result to preserve logical paths, scope provenance, supported user-config state, and diagnostics. Pair it with the separate native observation: expected local candidates versus skills shown by the Desktop app.

The local scope is documented; native visibility still needs runtime proof.

• Official Codex skills documentation — user and repository skill locations.
• openai/codex#40458 — Windows Desktop report of valid repository-local .agents/skills candidates absent from the native list.
• openai/codex#16607 — report that resumed threads can retain a stale model-visible skill inventory after a skill is added.
• openai/codex#40070 — report that a standalone skill reached through a symlink can inherit a namespace from its target ancestors.
• Instructree user-root research — why shared and deprecated user roots are reported separately.