Skip to content

ChatGPT skills: turning repeated work into a reusable workflow

The skill directory layout, how progressive disclosure shapes the way you write a description, where Codex loads skills from, creating one with skill-creator, and when to package it as a plugin instead.

CurrentLast verified

Platforms

  • ChatGPT desktop app
  • Codex CLI
  • Codex IDE extension
  • ChatGPT web and mobile (skills bundled in plugins)

What the official documentation says

  • Skills build on the open agent skills standard.

    Build skills

  • 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.

    Build skills

  • A skill is a directory with a SKILL.md file plus optional scripts, references, assets and agents directories; SKILL.md must include name and description.

    Build skills

  • Skills use progressive disclosure — ChatGPT and Codex start with each skill's name and description, then load the full SKILL.md instructions when they decide to use that skill.

    Build skills

  • In Codex the initial skills list uses at most 2% of the model's context window, or 8,000 characters when the context window is unknown; Codex shortens descriptions first and may omit some skills with a warning for large skill sets.

    Build skills

  • Explicit invocation is @ in ChatGPT, and /skills or $ in Codex CLI and the IDE extension.

    Build skills

  • Implicit matching depends on description, so the documented advice is to write concise descriptions with clear scope and boundaries and front-load the key use case and trigger words.

    Build skills

  • The built-in creator is invoked as @skill-creator in ChatGPT Work and $skill-creator in Codex, and instruction-only is the default.

    Build skills

  • Codex reads skills from repository, user, admin and system locations, scanning .agents/skills in every directory from the current working directory up to the repository root.

    Build skills

  • If two skills share the same name, Codex does not merge them and both can appear in skill selectors.

    Build skills

  • A skill can be disabled without deleting it using [[skills.config]] entries in ~/.codex/config.toml, and Codex must be restarted after the change.

    Build skills

  • allow_implicit_invocation in agents/openai.yaml defaults to true; when false, Codex will not implicitly invoke the skill from a user prompt, but explicit $skill invocation still works.

    Build skills

  • A skill packages instructions and supporting resources for a specific task or workflow, while a plugin is an installable bundle that can include skills and MCP servers.

    Skills & Plugins

A skill is your own process, written down

The documented definition: a skill packages instructions, resources and optional scripts so ChatGPT or Codex can follow a workflow reliably. It builds on the open agent skills standard.

There is a more useful sentence elsewhere in the docs: a skill can capture the way you already perform recurring work, so either product follows the same process whenever that task comes up.

So the test for "is this worth a skill" is not difficulty. It is repetition plus a consistency requirement. The documented examples: preparing a daily brief, reviewing documentation, creating a presentation, applying a team writing standard, or gathering information from the same connected tools each week.

The directory layout

A skill is a directory containing a SKILL.md, plus optional parts:

my-skill/
  SKILL.md      Required: instructions + metadata
  scripts/      Optional: executable code
  references/   Optional: documentation
  assets/       Optional: templates, resources
  agents/
    openai.yaml Optional: appearance and dependencies

SKILL.md must include name and description. The minimum viable form is:

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

Skill instructions for ChatGPT or Codex to follow.

Notice that the placeholder text the documentation puts in that template is itself the advice: say exactly when this skill should and should not trigger. The next section explains why that matters so much.

Progressive disclosure: why the description decides everything

Skills use progressive disclosure to manage context. ChatGPT and Codex start with only each skill's name and description, and load the full SKILL.md instructions when they decide to use that skill.

Two consequences follow directly.

First, implicit invocation depends entirely on description matching. Hence the documented instruction: write concise descriptions with clear scope and boundaries, and front-load the key use case and trigger words — the stated reason being that a host can still match the skill if descriptions get shortened.

Second, skills compete for a budget. In Codex the initial list also includes each skill's file path, and it uses at most 2% of the model's context window, or 8,000 characters when the context window is unknown. With many skills installed, Codex shortens descriptions first; for large skill sets it may omit some skills and show a warning.

The reassuring part: that budget applies only to the initial list. Once a skill is selected, Codex still reads its full SKILL.md.

Two ways to invoke

  • Explicit — type @ in ChatGPT to select a skill; run /skills or type $ in Codex CLI or the IDE extension.
  • Implicit — ChatGPT or Codex chooses a skill when your task matches its description.

Three ways to create one

Use the creator (recommended) — @skill-creator in ChatGPT Work, $skill-creator in Codex. It asks what the skill does, when it should trigger, and whether it should stay instruction-only or include scripts. Instruction-only is the default.

Record it — if you already know the workflow and it is easier to show than describe, Record & Replay captures the workflow, inspects the steps, and drafts a reusable skill from the demonstration.

Write it by hand — create the folder and the SKILL.md. Codex detects skill changes automatically; if an update does not appear, restart Codex.

The documented "good first skill" list: a weekly update, a campaign brief, a meeting follow-up, or any task where the steps and format should stay consistent.

Where Codex looks for local skills

| Scope | Location | Suggested use | |---|---|---| | REPO | $CWD/.agents/skills | Skills relevant to one working folder — a microservice or module | | REPO | $CWD/../.agents/skills | A folder above CWD when launched inside a Git repository, for a shared area | | REPO | $REPO_ROOT/.agents/skills | Root skills available to any subfolder in the repository | | USER | $HOME/.agents/skills | Personal skills that apply to any repository | | ADMIN | /etc/codex/skills | A shared machine or container location — SDK scripts, automation, default admin skills | | SYSTEM | Bundled with Codex by OpenAI | Broadly useful skills such as skill-creator and plan |

Two details worth remembering: Codex supports symlinked skill folders and follows the symlink target when scanning; and if two skills share the same name, Codex does not merge them — both can appear in skill selectors.

Turning a skill off without deleting it

Two mechanisms, with different effects:

Disable it entirely — in ~/.codex/config.toml:

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

Then restart Codex.

Disable only implicit invocation — set policy.allow_implicit_invocation = false in agents/openai.yaml (the default is true). Codex will not invoke the skill from your prompt, but explicit $skill invocation still works. This is the right setting for a skill that is useful when chosen deliberately and expensive when chosen by accident.

agents/openai.yaml also configures UI metadata for the desktop app — display name, short description, icons, brand colour, a default prompt — and declares tool dependencies for a smoother experience.

Best practices, and when to switch to a plugin

The four documented best practices:

  • Keep each skill focused on one job.
  • Prefer instructions over scripts unless you need deterministic behaviour or external tooling.
  • Write imperative steps with explicit inputs and outputs.
  • Test prompts against the skill description to confirm the right trigger behaviour.

On distribution the line is clear: direct skill folders are best for local authoring and repo-scoped workflows. If you want to distribute a reusable skill, bundle two or more together, or ship one alongside a connector, package them as a plugin.

How to do it

  1. Choose one focused task you already repeat, and note what you normally start with — files, links, notes — and what a finished result looks like.
  2. Describe the workflow with @skill-creator in ChatGPT or $skill-creator in Codex, explaining the goal, the steps, the expected format, and anything it should always include or avoid. Add a template or good example if you have one.
  3. Review the draft, test it with a realistic request, and refine it if the result misses a step or drifts from the format.
  4. Install and reuse it, and share it with teammates when your workspace settings allow.
  5. Or create one by hand — a folder with a SKILL.md containing name and description.
  6. Add agents/openai.yaml when you need UI metadata, an invocation policy, or declared tool dependencies.

On Windows

  1. The Windows desktop app supports skills, with Skills in the sidebar showing skills created across your projects.
  2. The skill load locations follow the same rules on Windows; the user-scope location is $HOME/.agents/skills and configuration lives in ~/.codex/config.toml, which resolves under %USERPROFILE% on Windows.
  3. The documented preference for instructions over scripts, unless you need deterministic behaviour or external tooling, is worth heeding especially here, since cross-platform scripts are the fragile part.

On mobile

  1. You cannot author skills on a phone, but you can use them — the documentation states that skills bundled in plugins are available in Chat and Work across ChatGPT on the web, desktop and mobile.
  2. Standalone skills (skill folders on a filesystem) are not available on mobile; they are limited to the desktop app, Codex CLI and the IDE extension.

Use cases

  • Locking in a weekly update, a campaign brief, or meeting follow-up where the steps and format should stay consistent.
  • Turning a team writing standard or review checklist into a process ChatGPT follows every time.
  • Pairing with scheduled tasks — the skill defines the action and supplies tools and context; the schedule decides when.

Common mistakes

  • Writing a vague description. Implicit invocation depends entirely on description matching, so a fuzzy one means the skill only ever fires when invoked by hand.
  • Packing several jobs into one skill. The first documented best practice is keeping each skill focused on one job.
  • Reaching for scripts first. The documented preference is instructions unless you need deterministic behaviour or external tooling.
  • Installing many skills and then wondering why some are never chosen. The initial skills list has a context budget; Codex shortens descriptions first and may omit skills with a warning.
  • Editing ~/.codex/config.toml without restarting Codex.

FAQ

What separates a skill from a plugin?
The documented split is that a skill packages instructions and supporting resources for a specific task or workflow, while a plugin is an installable bundle that can include skills and MCP servers. The choice follows from that — use a skill when you need reusable instructions for a focused task, and a plugin when you want an installable package that combines instructions with connected services or other tools.
How does progressive disclosure work in practice?
ChatGPT and Codex start with each skill's name and description, then read the full SKILL.md when they decide to use that skill. In Codex the initial list also includes each skill's file path, and that list uses at most 2% of the model's context window, or 8,000 characters when the window is unknown. The budget applies only to the initial list — once a skill is selected, its full SKILL.md is still read.
Where does Codex load local skills from?
Four scopes. REPO: $CWD/.agents/skills, a directory above CWD when launched inside a Git repository, and $REPO_ROOT/.agents/skills. USER: $HOME/.agents/skills. ADMIN: /etc/codex/skills. SYSTEM: bundled with Codex by OpenAI. Codex supports symlinked skill folders and follows the symlink target when scanning.
How do I turn a skill off without deleting it?
Add a [[skills.config]] entry in ~/.codex/config.toml with the path to that skill's SKILL.md and enabled = false, then restart Codex. Alternatively set policy.allow_implicit_invocation to false in agents/openai.yaml — Codex will not invoke it from your prompt, but explicit $skill invocation still works.
What if I know the workflow but do not want to write it out?
Use Record & Replay. The documentation describes it as capturing the workflow, inspecting the steps, and drafting a reusable skill from the demonstration.

Official sources

These are the pages this tutorial is checked against. Follow them if you need the vendor's exact wording.

Source status