›_ Codex Issues
Codex Issues / #15136

Local skills under ~/.codex/skills are not injected into runtime "Available skills"

Resolved 💬 5 comments Opened Mar 19, 2026 by xhugoliu Closed Mar 19, 2026
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What version of the IDE extension are you using?

26.313.41514

What subscription do you have?

plus

Which IDE are you using?

VS Code

What platform is your computer?

Microsoft Windows NT 10.0.26200.0 x64

What issue are you seeing?

Local custom skills stored under ~/.codex/skills do not appear in the runtime "Available skills" list inside Codex sessions.

I can create valid local skills with SKILL.md and agents/openai.yaml, and VS Code can open those files normally, but new Codex threads still only expose built-in .system skills.

Even when I explicitly reference a local skill, for example:
[$example-skill](<HOME>/.codex/skills/example-skill/SKILL.md)

the session behaves as if the skill is not available in the current session.

What steps can reproduce the bug?

  1. Create a local skill at ~/.codex/skills/example-skill/
  2. Add a valid SKILL.md
  3. Add a valid agents/openai.yaml
  4. Fully restart VS Code
  5. Open any workspace
  6. Start a brand new Codex thread
  7. Explicitly reference the local skill, for example:

[$example-skill](<HOME>/.codex/skills/example-skill/SKILL.md)

I can reproduce the same issue with both of these locations:

  • ~/.codex/skills/example-skill
  • ~/.codex/skills/private/example-skill

What is the expected behavior?

The local skill should appear in the runtime "Available skills" list and be usable for explicit invocation in the session.

Additional information

This looks like a discovery/runtime injection issue rather than a problem with the individual skill files.

Notes:

  • The skill files exist on disk and have valid structure.
  • VS Code can open and index them as normal files.
  • Restarting VS Code after creating the skill does not fix it.
  • The issue reproduces for both root-level and private local skills under ~/.codex/skills.

View original on GitHub ↗

5 Comments

github-actions[bot] contributor · 5 months ago

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

  • ##14785
  • ##13918

Powered by Codex Action

xhugoliu · 5 months ago

Update: after re-testing in a brand new session, the issue looks more specific than my original description.

What I now observe is:

  • typing $ in the composer shows 5 skills total
  • the picker includes 2 personal/local skills and 3 system skills
  • but if I ask Codex in the conversation to list available skills, the response says only 3 skills are available and only lists the system skills

So the local skills are not completely undiscoverable: they are visible in the $ skill picker.

The inconsistency seems to be that:

  • the UI skill picker can see local/personal skills
  • but the runtime "Available skills" list exposed in the conversation only reports the 3 system skills

This now looks more like a mismatch between UI-discovered skills and runtime/model-visible skills, rather than a total failure to discover local skills.

I’m attaching a screenshot showing:

  • the conversation output saying there are 3 available skills
  • the $ picker showing 5 skills in the same session
xhugoliu · 5 months ago

<img width="1510" height="1768" alt="Image" src="https://github.com/user-attachments/assets/92341557-995d-4afc-a420-bb018a9cc791" />

xhugoliu · 5 months ago

Closing this issue because I was able to resolve it locally.

Root cause appears to be the policy block in agents/openai.yaml:

policy:
allow_implicit_invocation: false

After removing that block from my personal skills and starting a fresh session, the behavior became consistent again.

What I observed after the change:

  • my personal skills are shown correctly in the $ picker
  • the runtime available-skills behavior is now consistent in a new session

So in my case this was not a general local-skill discovery failure under ~/.codex/skills, but a behavior difference triggered by that policy setting.

Leaving this note here in case it helps others debug similar symptoms.

ganoipho6 · 4 months ago

Your idea is that it still cannot be used by using the / to call skills, instead, you should use $ to call skills. So is this a process that OpenAI intentionally changed regarding UX UI? I also experienced blank when I used @.

<img width="768" height="144" alt="Image" src="https://github.com/user-attachments/assets/98a5107f-f697-45b4-a225-dc726b613c3b" />

Anyway, thank you for the useful information - I will switch to calling skills using $.