skills.md Codex Docs, 2026-03-27 00:39 UTC → 2026-05-01 18:29 UTC

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. 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 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) when you want other developers to install it.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.

6 6 

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

8 8 

9Skills 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.

10 

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.

12 

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.

10 14 

11A 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`.

12 16 

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

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

29 33 

30Because implicit matching depends on `description`, write descriptions with clear scope and boundaries.34Because 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.

31 35 

32## Create a skill36## Create a skill

33 37 

69 73 

70These locations are for authoring and local discovery. When you want to74These locations are for authoring and local discovery. When you want to

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

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

73 77 

74## Distribute skills with plugins78## Distribute skills with plugins

75 79 

76Direct skill folders are best for local authoring and repo-scoped workflows. If80Direct skill folders are best for local authoring and repo-scoped workflows. If

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

78ship a skill alongside an app integration, package them as a82ship a skill alongside an app integration, package them as a

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

80 84 

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

82mappings, MCP server configuration, and presentation assets in a single86mappings, MCP server configuration, and presentation assets in a single