skills.md Codex Docs, 2026-04-29 00:50 UTC → 2026-05-07 20:02 UTC

14 14 

15A skill is a directory with a `SKILL.md` file plus optional scripts and references. The `SKILL.md` file must include `name` and `description`.15A skill is a directory with a `SKILL.md` file plus optional scripts and references. The `SKILL.md` file must include `name` and `description`.

16 16 

17- my-skill/17<FileTree

18 18 class="mt-4"

19 - SKILL.md Required: instructions + metadata19 tree={[

20 - scripts/ Optional: executable code20 {

21 - references/ Optional: documentation21 name: "my-skill/",

22 - assets/ Optional: templates, resources22 open: true,

23 - agents/23 children: [

24 24 {

25 - openai.yaml Optional: appearance and dependencies25 name: "SKILL.md",

26 comment: "Required: instructions + metadata",

27 },

28 {

29 name: "scripts/",

30 comment: "Optional: executable code",

31 },

32 {

33 name: "references/",

34 comment: "Optional: documentation",

35 },

36 {

37 name: "assets/",

38 comment: "Optional: templates, resources",

39 },

40 {

41 name: "agents/",

42 open: true,

43 children: [

44 {

45 name: "openai.yaml",

46 comment: "Optional: appearance and dependencies",

47 },

48 ],

49 },

50 ],

51 },

52 

53]}

54/>

26 55 

27## How Codex uses skills56## How Codex uses skills

28 57 

62 91 

63| Skill Scope | Location | Suggested use |92| Skill Scope | Location | Suggested use |

64| :---------- | :-------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |93| :---------- | :-------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

65| `REPO` | `$CWD/.agents/skills` Current working directory: where you launch Codex. | If you’re in a repository or code environment, teams can check in skills relevant to a working folder. For example, skills only relevant to a microservice or a module. |94| `REPO` | `$CWD/.agents/skills` <br /> Current working directory: where you launch Codex. | If you're in a repository or code environment, teams can check in skills relevant to a working folder. For example, skills only relevant to a microservice or a module. |

66| `REPO` | `$CWD/../.agents/skills` A folder above CWD when you launch Codex inside a Git repository. | If you’re in a repository with nested folders, organizations can check in skills relevant to a shared area in a parent folder. |95| `REPO` | `$CWD/../.agents/skills` <br /> A folder above CWD when you launch Codex inside a Git repository. | If you're in a repository with nested folders, organizations can check in skills relevant to a shared area in a parent folder. |

67| `REPO` | `$REPO_ROOT/.agents/skills` The topmost root folder when you launch Codex inside a Git repository. | If you’re in a repository with nested folders, organizations can check in skills relevant to everyone using the repository. These serve as root skills available to any subfolder in the repository. |96| `REPO` | `$REPO_ROOT/.agents/skills` <br /> The topmost root folder when you launch Codex inside a Git repository. | If you're in a repository with nested folders, organizations can check in skills relevant to everyone using the repository. These serve as root skills available to any subfolder in the repository. |

68| `USER` | `$HOME/.agents/skills` Any skills checked into the user’s personal folder. | Use to curate skills relevant to a user that apply to any repository the user may work in. |97| `USER` | `$HOME/.agents/skills` <br /> Any skills checked into the user's personal folder. | Use to curate skills relevant to a user that apply to any repository the user may work in. |

69| `ADMIN` | `/etc/codex/skills` Any skills checked into the machine or container in a shared, system location. | Use for SDK scripts, automation, and for checking in default admin skills available to each user on the machine. |98| `ADMIN` | `/etc/codex/skills` <br /> Any skills checked into the machine or container in a shared, system location. | Use for SDK scripts, automation, and for checking in default admin skills available to each user on the machine. |

70| `SYSTEM` | Bundled with Codex by OpenAI. | Useful skills relevant to a broad audience such as the skill-creator and plan skills. Available to everyone when they start Codex. |99| `SYSTEM` | Bundled with Codex by OpenAI. | Useful skills relevant to a broad audience such as the skill-creator and plan skills. Available to everyone when they start Codex. |

71 100 

72Codex supports symlinked skill folders and follows the symlink target when scanning these locations.101Codex supports symlinked skill folders and follows the symlink target when scanning these locations.