Skills in Codex: what they are and how to write your own

If you give Codex the same order of actions again and again ("find the failing test, reproduce it, fix the cause, run everything again"), that order is worth turning into a skill. Skills in Codex are folders of instructions that the agent loads when a task fits the description or when you name the skill yourself. Below: what they are, how to write your own scenario and how skills relate to plugins and hooks.

The structure and paths come from OpenAI's Codex documentation as of October 18, 2026. The format is evolving, so check details against the current documentation.

What a skill is

A skill is a directory that must contain a SKILL.md file, with optional scripts, reference materials and templates beside it. The format builds on the open agent skills standard.

my-skill/
  SKILL.md        required: metadata and instructions
  scripts/        optional: executable code
  references/     optional: reference documents
  assets/         optional: templates and resources
  agents/openai.yaml   optional: appearance and dependencies

SKILL.md must have the name and description fields in the header, followed by the instruction text.

The key feature is progressive loading. At first Codex sees only the name and description of each skill (and the file path). The full SKILL.md text is pulled in when Codex decides to apply the skill. Per the documentation, the initial skill list takes at most 2% of the model's context window (or 8,000 characters if the window is unknown); with many skills the descriptions are shortened and some skills may not reach the list, in which case Codex warns you. The budget is changed with the skills.max_context_tokens setting (up to 10,000 tokens).

How Codex picks a skill

There are two ways:

1. Explicit call. In the CLI and the IDE extension type /skills or start a message with $ and the skill name.
2. Implicit call. Codex applies a skill itself if the task matches the description. So the description must be written very clearly.

A practical rule follows: put the main use case and trigger words at the start of the description so the skill is found even if the description gets shortened. State the boundaries too: when the skill should not be used.

Where skills live

For a repository Codex scans .agents/skills directories from the current folder up to the repository root. Other locations:

If two skills share a name, Codex does not merge them, and both may appear in the list. New and changed skills are picked up automatically; if a change is not visible, restart Codex.

Example: a skill for triaging failing tests

Let us create a skill in the repository: .agents/skills/fix-failing-tests/SKILL.md.

---
name: fix-failing-tests
description: Triage and fix failing pytest tests. Use when the user asks to repair tests, investigate a red CI, or find why a test fails. Do not use for writing new tests.
---

## Fixing failing tests

1. Run `scripts/run_tests.sh` and read the output. Do not rerun the whole suite without need.
2. Pick one failure. Reproduce it with a separate command `pytest <path>::<name> -x -q`.
3. Find the cause in the code, not in the test. Change a test only if it is clearly outdated, and explain why.
4. Make the smallest edit.
5. Run the failing test, then the whole suite through `scripts/run_tests.sh`.
6. At the end report briefly: what failed, the cause, what changed, which checks are green.

Prohibitions: do not disable or mark tests as skip to get green; do not touch the migrations/ directory.

And a simple script .agents/skills/fix-failing-tests/scripts/run_tests.sh:

#!/usr/bin/env bash
set -euo pipefail
pytest -q --maxfail=5 2>&1 | tail -n 60

The script trims output to the last lines so miles of logs do not enter the context: that saves tokens and helps the model see the main thing. The pytest commands are an example, use your own.

You can call the skill like this:

$fix-failing-tests investigate the failures in tests/api

If the skill does not trigger by itself, check the description: it should echo the wording you usually ask with. Test several phrasings of a request and see which ones the skill picks up.

Helpers for creating skills

• $skill-creator asks what the skill does, when it should trigger and whether scripts are needed, and creates a draft. By default it creates an instruction-only skill.
• $skill-installer installs ready-made skills, for example $skill-installer linear. Note: install only what you trust, because a skill may include scripts.

To disable a skill without deleting it, add this to ~/.codex/config.toml:

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

And if a skill should not trigger by itself, agents/openai.yaml accepts allow_implicit_invocation: false in its policy block, after which it runs only on an explicit $skill.

Skills, plugins and hooks: the differences

Searches near skills often mention codex plugins and codex hooks. These are three different mechanisms.

• Skills are instructions (and optional scripts) for solving a task; the model decides when to apply them, or you call them by name.
• Plugins package skills (one or several) and, per the documentation, may include MCP server connections, so that they can be handed to other people. For one repository the .agents/skills directory is enough; plugins are needed when a skill must be distributed.
• Hooks are scripts that run at certain points of the agent loop (for example before a tool call or when a turn stops) and can, say, check prompts or log the chat. Hooks run regardless of the model's decision. Non-managed hooks must be reviewed and trusted before they run.

If you need "the model should do it this way", take a skill. If you need "the system will definitely check this", look toward hooks. For the analogous project instructions file see the article AGENTS.md for Codex CLI↗.

What running a skill costs

A skill is ordinary agent work, and you pay for model tokens. Assume (a hypothetical example) a scenario of 15 requests, on average 25,000 input tokens and 600 output tokens each. Input 15 × 25,000 = 375,000, output 15 × 600 = 9,000 tokens. On gpt-6.1-sol (input $0.27, output $1.32 per 1M, prices as of October 18, 2026), ignoring cache: 0.375 × 0.27 + 0.009 × 1.32 = 0.10125 + 0.01188 = $0.1131.

For GPT models the gateway sees cache reads; the cached part of the input is billed at the read price of $0.013 per 1M, which lowers the sum on long sessions. Cache writes are not billed separately for GPT. A short SKILL.md and trimmed script output save tokens on every request. Skills themselves are a client-side Codex feature and do not depend on the provider.

Connecting Codex to Zukko

A minimal ~/.codex/config.toml:

model = "gpt-6.1-sol"
model_provider = "zukko"

[model_providers.zukko]
name = "zukko"
base_url = "https://api.zukko.pro/v1"
env_key = "ZUKKO_API_KEY"
wire_api = "responses"

Create the fetch_... key in the dashboard↗ and put it in the ZUKKO_API_KEY variable. Details and the second method via auth.json are in the Codex documentation↗. According to the Zukko documentation, GPT and Claude models work in Codex and GLM models do not.

FAQ

The skill does not trigger by itself, what to do?

Refine the description: add words from your usual requests, put the main scenario first, list the boundaries. Or call it explicitly with $name. After editing, restart Codex if the change is not visible.

How many skills can I install?

The limit is tied to the budget of the skill list in the context: with many skills Codex shortens descriptions and may not show some. Keep skills narrow and disable the unneeded ones.

Can I share a skill with a team?

Yes, put it in the repository's .agents/skills and commit it. To distribute beyond one repository, package skills into plugins.

Do skills work with Zukko models?

A skill is client-side instruction text, so it works with any model available in Codex. How closely a model follows the instructions, check on your own tasks.

Create a key in the Zukko dashboard, connect Codex and write your first five-step skill.