Does codex in VS Code (or in general) needs skills to be mentioned in AGENTS.md?

Codex
, ,
1

HI All,

Recently I created a code review skill and added it under .codex/skills. somehow when reviewing the code it wasnt using it. When asked, I got the following response from Codex itself:

I have the skill to review module listed under fin-analyst-historical-speckit/.codex/skills/analyst-reviewer/SKILL.md. could you not make it out that this should be used? did you not read it? or is there somehting I need to fix so that this skill is easliy discoverable to you (codex)?

You’re right to call this out. I’ll verify that skill file exists and then explain exactly why it was not auto-selected and how to make it reliably discoverable in future turns.

Explored 1 list

You’re correct that the skill file exists. I checked it at:

SKILL.md

Why I didn’t use it:

  1. In this session, the authoritative AGENTS.md block I received (for /) listed only these skills: planning-with-files, playwright, skill-creator, skill-installer.

  2. I’m required to treat that list as the discoverable/available skills for the turn.

  3. Since analyst-reviewer was not in that list, I did not auto-select it.

What to fix for discoverability:

  1. Add analyst-reviewer to the Available skills list in the AGENTS.md that governs the session (the one loaded for /home/<path/to/worspace>).

  2. Include its full path exactly, same format as other entries.

  3. Optionally keep a repo-local AGENTS in analyst-historical-speckit and start Codex from that repo root so that file is the governing one.

#1 seems different than what the documentation says:
/codex/skills/
Does anyone knows if it is mandatory to put skills in AGENTS.md?

TIA

1 Like
2

My current understanding is that it’s not mandatory, but it really helps the LLM to pickup and use skills if they’re mentioned there.

This is also where I add some more details about when to invoke the skill with regular language.

For example:

  • manage-shortcut-stories: Manage Shortcut stories via API. Use when you need to find or create a Shortcut ticket, list projects/workflows/teams, assign owners/teams, fetch story details, or update a story’s workflow state to in-progress (started) or ready-for-review. Includes keyword-based search with user prompts, story creation, and story updates. (file: /Users/tyrel/.codex/skills/manage-shortcut-stories/SKILL.md)`

I’ve found much better usage rate using skills with a small paragraph like this in AGENTS.md for each. Also I never need to ask it specifically to use a skill. Just to do the things I want it to do. Like in this Shortcut example I can just say “make a ticket for this” and it knows to use that Shortcut skill to create a story in Shortcut. (Shortcut is just a task management software BTW).

Also you don’t need to write these out yourself, just ask Codex to generate them for you and then tweak them if needed.