Based on OpenAI’s official docs, checked October 26, 2026

Codex skills: create, install and use SKILL.md skills in Codex

Skills are how you teach OpenAI Codex a repeatable workflow. A skill is a folder with a SKILL.md file of instructions, plus optional scripts, references and assets. Codex reads only each skill’s name and description at the start, then loads the full instructions when you call the skill or when your task matches its description. OpenAI says skills build on the open agent skills standard. This guide covers the Codex-specific parts: where Codex looks for skills, how to call them, the built-in creator and installer, how to switch a skill off, and the optional agents/openai.yaml file. Everything here comes from OpenAI’s “Build skills” documentation, checked October 26, 2026.

1. 1. Create a skill folder with SKILL.md

   Make a folder named after the skill and put a SKILL.md file inside it. OpenAI’s docs say SKILL.md must include name and description in its frontmatter; the body holds the instructions. scripts/, references/, assets/ and agents/openai.yaml are optional.

   ---
   name: skill-name
   description: Explain exactly when this skill should and should not trigger.
   ---
   
   Skill instructions for ChatGPT or Codex to follow.

2. 2. Or let Codex write it with $skill-creator

   Codex ships a system skill that drafts skills for you. It asks what the skill does, when it should trigger and whether it should stay instruction-only (the default) or include scripts.

   $skill-creator

3. 3. Put it where Codex looks

   For a repository, use .agents/skills/. Codex scans .agents/skills in every folder from where you launch it up to the repository root. For skills you want in every project, use ~/.agents/skills/.

   .agents/skills/
   └── release-notes/
       ├── SKILL.md
       └── references/

4. 4. Call the skill

   In Codex CLI or the IDE extension, run /skills to pick one, or type $ followed by the skill name in your prompt. Codex can also pick a skill on its own when your task matches the description.

   $release-notes draft notes for the changes since the last tag

5. 5. Check that Codex picked it up

   Codex detects skill changes automatically. If a new or edited skill doesn’t show up, restart Codex.

Where Codex loads skills from

Repository skills: .agents/skills in the current working directory, in each parent folder, and at the repository root. A skill at the root is available in every subfolder; a skill in a subfolder can hold skills only relevant to a microservice or a module.

User skills: ~/.agents/skills, for workflows you want in any repository.

Admin skills: /etc/codex/skills, a shared location on a machine or container, for SDK scripts, automation and default admin skills available to each user on the machine.

System skills: bundled by OpenAI, such as the skill creator and skill installer.

Codex follows symlinked skill folders. If two skills share the same name, Codex doesn’t merge them, and both can appear in the skill picker, so give each skill a unique name.

How Codex decides when to use a skill

Codex starts each session with a list of skills: name, description and file path. OpenAI’s docs say this list uses at most 2% of the model’s context window by default, or 8,000 characters when the window size is unknown. When many skills are installed, Codex shortens descriptions first and may leave some skills out of the list with a warning. You can change the budget with skills.max_context_tokens, up to 10,000 tokens.

The budget only covers the starting list. When Codex selects a skill, it still reads the whole SKILL.md.

Because automatic selection depends on the description, put the main use case and trigger words first, and say when the skill should not run. OpenAI recommends testing prompts against the description to confirm it triggers when you expect.

Turn a skill off without deleting it

Add a [[skills.config]] entry to ~/.codex/config.toml with the path to the skill’s SKILL.md and enabled = false, then restart Codex.

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Optional agents/openai.yaml

An agents/openai.yaml file inside the skill sets how it looks in the ChatGPT desktop app (display name, short description, icons, brand color and a default prompt), its invocation policy and its tool dependencies.

Set policy.allow_implicit_invocation to false to stop Codex choosing the skill on its own; calling it explicitly with $ still works. The default is true.

Under dependencies you can declare an MCP server the skill needs, such as OpenAI’s docs server, as in OpenAI’s example below.

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

Installing and sharing skills

To add curated skills for your own setup, use the built-in installer, for example $skill-installer linear. It installs from the openai/skills repository, and you can also ask it to fetch skills from other repositories.

To share skills with other people, OpenAI recommends packaging them as a plugin. A plugin can bundle several skills, plus MCP server configuration and connectors, and plugins work in Codex CLI, Codex in the ChatGPT desktop app and ChatGPT itself.

Standalone skills work in the ChatGPT desktop app, Codex CLI and the IDE extension; skills inside plugins also reach ChatGPT on the web and mobile.

Tips

• Keep one job per skill, as OpenAI advises; split a skill when its description lists unrelated tasks.
• Prefer plain instructions over scripts unless you need deterministic behavior or an external tool.
• Write imperative steps with explicit inputs and outputs.
• Check shared skills into .agents/skills/ in the repository; keep personal ones in ~/.agents/skills/, which OpenAI suggests for skills that apply to any repository.

Next steps

Sources

• https://developers.openai.com/codex/skills · checked 2026-10-26