skills.md Codex Docs, 2026-03-07 18:10 UTC → 2026-05-07 17:08 UTC

1# Agent Skills1# Agent Skills

2 2 

3Use agent skills to extend Codex with task-specific capabilities. A skill packages instructions, resources, and optional scripts so Codex can follow a workflow reliably. You can share skills across teams or with the community. Skills build on the [open agent skills standard](https://agentskills.io).3Use agent skills to extend Codex with task-specific capabilities. A skill packages instructions, resources, and optional scripts so Codex can follow a workflow reliably. Skills build on the [open agent skills standard](https://agentskills.io).

4 

5Skills are the authoring format for reusable workflows. Plugins are the installable distribution unit for reusable skills and apps in Codex. Use skills to design the workflow itself, then package it as a [plugin](https://developers.openai.com/codex/plugins/build) when you want other developers to install it.

4 6 

5Skills are available in the Codex CLI, IDE extension, and Codex app.7Skills are available in the Codex CLI, IDE extension, and Codex app.

6 8 

7Skills use **progressive disclosure** to manage context efficiently: Codex starts with each skill’s metadata (`name`, `description`, file path, and optional metadata from `agents/openai.yaml`). Codex loads the full `SKILL.md` instructions only when it decides to use a skill.9Skills use **progressive disclosure** to manage context efficiently: Codex starts with each skill's name, description, and file path. Codex loads the full `SKILL.md` instructions only when it decides to use a skill.

8 10 

9A skill is a directory with a `SKILL.md` file plus optional scripts and references. The `SKILL.md` file must include `name` and `description`.11Codex includes an initial list of available skills in context so it can choose the right skill for a task. To avoid crowding out the rest of the prompt, this list is capped at roughly 2% of the model’s context window, or 8,000 characters when the context window is unknown. If many skills are installed, Codex shortens skill descriptions first. For very large skill sets, some skills may be omitted from the initial list, and Codex will show a warning.

10 12 

11- my-skill/13This budget applies only to the initial skills list. When Codex selects a skill, it still reads the full SKILL.md instructions for that skill.

12 14 

13 - SKILL.md Required: instructions + metadata15A skill is a directory with a `SKILL.md` file plus optional scripts and references. The `SKILL.md` file must include `name` and `description`.

14 - scripts/ Optional: executable code

15 - references/ Optional: documentation

16 - assets/ Optional: templates, resources

17 - agents/

18 16 

19 - openai.yaml Optional: appearance and dependencies17<FileTree

18 class="mt-4"

19 tree={[

20 {

21 name: "my-skill/",

22 open: true,

23 children: [

24 {

25 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/>

20 55 

21## How Codex uses skills56## How Codex uses skills

22 57 

251. **Explicit invocation:** Include the skill directly in your prompt. In CLI/IDE, run `/skills` or type `$` to mention a skill.601. **Explicit invocation:** Include the skill directly in your prompt. In CLI/IDE, run `/skills` or type `$` to mention a skill.

262. **Implicit invocation:** Codex can choose a skill when your task matches the skill `description`.612. **Implicit invocation:** Codex can choose a skill when your task matches the skill `description`.

27 62 

28Because implicit matching depends on `description`, write descriptions with clear scope and boundaries.63Because implicit matching depends on `description`, write concise descriptions with clear scope and boundaries. Front-load the key use case and trigger words so Codex can still match the skill if descriptions are shortened.

29 64 

30## Create a skill65## Create a skill

31 66 

56 91 

57| Skill Scope | Location | Suggested use |92| Skill Scope | Location | Suggested use |

58| :---------- | :-------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |93| :---------- | :-------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

59| `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. |

60| `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. |

61| `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. |

62| `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. |

63| `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. |

64| `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. |

65 100 

66Codex 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.

67 102 

68## Install skills103These locations are for authoring and local discovery. When you want to

104distribute reusable skills beyond a single repo, or optionally bundle them with

105app integrations, use [plugins](https://developers.openai.com/codex/plugins/build).

106 

107## Distribute skills with plugins

69 108 

70To install skills beyond the built-ins, use `$skill-installer`. For example, to install the `$linear` skill:109Direct skill folders are best for local authoring and repo-scoped workflows. If

110you want to distribute a reusable skill, bundle two or more skills together, or

111ship a skill alongside an app integration, package them as a

112[plugin](https://developers.openai.com/codex/plugins/build).

113 

114Plugins can include one or more skills. They can also optionally bundle app

115mappings, MCP server configuration, and presentation assets in a single

116package.

117 

118## Install curated skills for local use

119 

120To add curated skills beyond the built-ins for your own local Codex setup, use `$skill-installer`. For example, to install the `$linear` skill:

71 121 

72```bash122```bash

73$skill-installer linear123$skill-installer linear

74```124```

75 125 

76You can also prompt the installer to download skills from other repositories. Codex detects newly installed skills automatically; if one doesn’t appear, restart Codex.126You can also prompt the installer to download skills from other repositories.

127Codex detects newly installed skills automatically; if one doesn't appear,

128restart Codex.

129 

130Use this for local setup and experimentation. For reusable distribution of your

131own skills, prefer plugins.

77 132 

78## Enable or disable skills133## Enable or disable skills

79 134