How to create a skill for Codex

A skill is a directory with a SKILL.md file, plus optional scripts and references. It packages instructions, resources, and optional scripts so ChatGPT or Codex can follow a workflow reliably. Standalone skills are available in the ChatGPT desktop app, Codex CLI, and the IDE extension. Skills bundled in plugins are also available in Chat and Work across ChatGPT on the web, desktop, and mobile.

Skills are the authoring format for the workflow itself. Plugins are the later step, when you want other people to install that workflow or bundle it with connectors. The steps below stop once the skill exists and Codex can see it.

Why name and description come first

ChatGPT and Codex use progressive disclosure. They start with each skill’s name and description, then load the full SKILL.md instructions when they decide to use that skill. In Codex, the initial list also includes each skill’s file path.

That list is small on purpose. By default it uses at most 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 large skill sets, Codex may omit some skills from the initial list and show a warning. skills.max_context_tokens sets a different budget, up to 10,000 tokens. The budget applies only to the initial skills list. When Codex selects a skill, it still reads the full SKILL.md.

Implicit invocation depends on description. Write a concise description with clear scope and boundaries, and front-load the key use case and trigger words so a host can still match the skill if the description is shortened.

You can also call a skill directly. In ChatGPT, type @ to select a skill. In Codex CLI or the IDE extension, run /skills or type $ to mention a skill. A host can also choose a skill on its own when the task matches the description.

What the skill directory holds

The create-skill docs describe this layout. SKILL.md is required. It holds instructions and metadata, and it must include name and description. The same directory can also hold optional executable code, optional documentation, and optional templates or resources. agents/openai.yaml is optional appearance and dependency metadata.

A folder and SKILL.md are enough to create and load a skill. Prefer instructions over scripts unless you need deterministic behavior or external tooling.

Create the skill with the built-in creator

If you already know the workflow and it is easier to show than describe, the same page points to Record & Replay. The recorder captures the workflow, inspects the steps, and drafts a reusable skill from the demonstration.

If you want to describe the skill instead, use the built-in creator. In ChatGPT Work, invoke it as @skill-creator. In Codex, invoke it as:

$skill-creator

The creator asks what the skill does, when it should trigger, and whether it should stay instruction-only or include scripts. Instruction-only is the default. skill-creator is a system skill bundled with Codex and enabled by default, alongside skill-installer.

Keep the result focused on one job. Write imperative steps with explicit inputs and outputs, and test prompts against the skill description to confirm the right trigger. Those checks are the best practices listed on the create-skill page.

Write SKILL.md by hand

You can also create a skill manually by creating a folder with a SKILL.md file. The docs show this file:

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

Skill instructions for ChatGPT or Codex to follow.

Required front matter is name and description. In the example, each is a single line. A character limit for either field is not stated on the create-skill page, so that cap is unknown here. Replace skill-name with the skill’s name. Rewrite the description so it says exactly when the skill should and should not trigger. Put the instructions ChatGPT or Codex should follow in the body.

Put the folder where Codex scans

Codex reads skills from repository, user, admin, and system locations. For repositories, it scans .agents/skills in every directory from your current working directory up to the repository root.

Codex supports symlinked skill folders and follows the symlink target when scanning these locations. If two skills share the same name, Codex does not merge them; both can appear in skill selectors.

For a skill that should follow you across repositories, put the skill directory under $HOME/.agents/skills. For a skill that belongs to one codebase, use .agents/skills in the current working directory, a parent directory, or the repository root. These locations are for authoring and local discovery.

See whether it loaded

Codex detects skill changes automatically. If an update does not appear, restart Codex.

In the ChatGPT desktop app, open Skills in the sidebar to view and explore skills created across your projects. In Codex CLI or the IDE extension, run /skills or type $ to mention the skill. A task that matches the description can also select it without an explicit mention.

What to do next

Create the skill, then confirm it is visible before you add metadata or packaging. In Codex, run $skill-creator and answer what the skill does, when it should trigger, and whether it stays instruction-only. In ChatGPT Work, the same creator is @skill-creator. Or skip the creator and add the SKILL.md file above to a skill folder under $HOME/.agents/skills or a repository .agents/skills path from the table. Then run /skills or mention the skill with $. If it does not appear, restart Codex. When it shows up, return to the create-skill documentation for optional agents/openai.yaml metadata and for packaging the skill as a plugin.

Sources

• Create a skill