Writing and calling Codex skills

Who this is for and what you will be able to do

This guide is for people who want a repeatable workflow that Codex follows the same way each time. After reading it you should be able to write a minimal skill, know which directory Codex scans for it, invoke it either explicitly or by automatic matching, and turn a skill off without deleting it.^[1]

What a skill is, and how it differs from a plugin

A skill extends ChatGPT and Codex with capabilities for a particular kind of task. It packages instructions, resources and optional scripts so the product can follow a workflow reliably. Skills build on the open agent skills standard.^[1]

Skills are the authoring format for reusable workflows. Plugins distribute them. Plugins deliver reusable skills and connectors through a plugin directory shared by ChatGPT and Codex.^[1] For local use in one repository, a plain skill folder is enough. To share a skill with other people, bundle several skills together, or ship a skill alongside a connector, package it as a plugin.^[1]

The structure of a skill

A skill is a directory with a SKILL.md file. That file must include name and description fields. The directory can also contain optional parts:^[1]

scripts/ for executable code.
references/ for documentation.
assets/ for templates and other resources.
agents/openai.yaml for appearance and dependency settings.^[1]

To write one by hand, begin SKILL.md with a front matter block like this:^[1]

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for ChatGPT or Codex to follow.

The instructions for the model come after the front matter.

Writing a good description

Implicit matching depends on the description. Keep it concise, state the scope and the boundaries, and put the main use case and trigger words first, so the skill can still be matched if the text is shortened.^[1]

Keep each skill focused on one job. The docs recommend instructions over scripts, unless you need deterministic behavior or external tooling. Write imperative steps with explicit inputs and outputs, then test the skill with real prompts to confirm that it triggers when it should.^[1]

To have Codex draft one, invoke the built-in creator as $skill-creator. It asks what the skill does, when it should trigger, and whether it should be instruction-only or include scripts. Instruction-only is the default.^[1]

How to invoke a skill

There are two ways to activate a skill:^[1]

Explicit: mention it in your prompt. In the Codex CLI or the IDE extension, run /skills or type $ to mention a skill.
Implicit: ChatGPT or Codex can choose the skill when the task matches its description.

To stop a skill from being invoked implicitly, set allow_implicit_invocation to false in agents/openai.yaml. The default is true. With it set to false, Codex does not invoke the skill from the user prompt, but an explicit $skill mention still works.^[1]

Where Codex looks for skills

Codex reads skills from repository, user, admin and system locations.^[1]

Repository: Codex scans .agents/skills in every directory from the current working directory up to the repository root.
User: $HOME/.agents/skills.
Admin: /etc/codex/skills.
System: the skills bundled with Codex, including skill-creator and skill-installer, which are enabled by default.^[1]

Two details matter here. If two skills share the same name, Codex does not merge them, and both can appear in the skill selector. Codex also supports symlinked skill folders and follows the link target.^[1] After you change skills, Codex detects the change automatically. If an update does not appear, restart Codex.^[1]

Installing a curated skill

To add curated skills to your local Codex setup, use $skill-installer. For example, to install the linear skill:^[1]

$skill-installer linear

The installer can also download skills from other repositories. The docs present local installs as a way to set up and experiment, and prefer plugins for reusable distribution of your own skills.^[1]

Disabling a skill without deleting it

Add a [[skills.config]] entry to ~/.codex/config.toml:^[1]

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

Each entry takes exactly one selector. An absolute path matches one SKILL.md file, and a name matches every skill with that name. When more than one entry matches, the last one wins.^[1]

To turn off all bundled system skills in a single project, set enabled = false under [skills.bundled] in that project's trusted .codex/config.toml, then restart Codex.^[1]

Common problems

A change does not take effect. Restart Codex. Codex normally detects changes on its own, and the docs name a restart as the fix when an update does not show up.^[1]

Two skills have the same name. They are not merged, so both appear in the selector. Rename one of them, or disable one with [[skills.config]].^[1]

Limits

The initial skills list uses at most 2% of the model's context window by default, or 8,000 characters when the window is unknown. When there are many skills, Codex shortens the descriptions first, and it may leave some skills out of the list and show a warning. The skills.max_context_tokens setting raises the budget, up to 10,000 tokens.^[1]

Slash commands and shortcuts

In the desktop app, keyboard shortcuts mostly open the command menu. The command menu opens with ⌘+⇧+P or ⌘+K on macOS, and with Ctrl+Shift+P or Ctrl+K on Windows and Linux. Actions that start with / are documented on a separate page, which this guide does not cover.^[2]

In the ChatGPT desktop app, the codex://skills link opens the Skills page directly.^[2]