If Codex Skills is installed but does not trigger, first check if it is located in the scan directory and whether the SKILL.md has complete name and description, then explicitly call to verify. Most issues are "skills not discovered" or "descriptions do not match tasks."
The directory must be set correctly, and the file name must not change
Warehouse-specific skills are located in:
$REPO_ROOT/.agents/skills/skill-name/SKILL.mdUniversal personal skills for all projects include:
~/.agents/skills/skill-name/SKILL.mdCodex scans .agents/skills from the current directory to the repository root directory. Skills placed in adjacent directories outside the warehouse or missing separate skill folders may be undetectable.
Description determines when to trigger
The minimum available file should include YAML header information:
---
name: release-checker
description: Use when checking whether a web project is ready to release, including build, tests and rollback verification.
---
Follow the project release checklist and report every failed check.name Be stable and avoid duplicate names; description Clearly state user goals, trigger conditions, and boundaries. Writing only "a very useful publishing skill" has no matching task signals; key scenarios should be placed at the beginning of the description.
Explicit calls can distinguish between two types of problems
Enter /skills in the CLI or IDE extension to view the list, or type $ to select skills. If $release-checker is selected and executed, it means the installation is working properly. What needs optimization is description; If it's not in the list, check the directory, file name, and YAML format.
Skill updates are usually discovered automatically; Restart Codex when there is no refresh. When there are too many skills, the initial list is limited by context budget, descriptions may be shortened, some skills may be omitted, and prompts may appear. At this point, unrelated skills should be disabled or required skills explicitly invoked.
Skills of the same name will not be automatically merged. First, confirm the path in /skills, keep the correct version, and then test.
