Codex Skills: Creating a Skill for Repetitive Tasks

If you explain the same thing to Codex five times a week—how to format a report, sort through email, or prepare copy in your style—you can write those instructions down once in a skill. After that, the agent can find it by its description when the description matches the task, or you can invoke it explicitly. A skill is an ordinary folder with a text file named SKILL.md; no programming is needed for a basic use case.

Below, we cover how a skill is structured, where Codex looks for it, how to create one step by step, and how to choose a model based on cost. Commands and prices are based on official OpenAI documentation as of September 20, 2026. We do not repeat the Codex installation instructions here; they are in the guide Codex by OpenAI: What It Is, How to Install and Run It.

Practical information about using Ailoot is available in the documentation.

What Is a Skill in Codex?#

The format is called Agent Skills. It is an open standard originally developed by Anthropic and published at agentskills.io. It is supported by various agents, including Codex, Claude Code, and other compatible clients. A simple skill consisting only of text instructions can be transferred between them by copying the folder. If it contains scripts, dependencies, or an agents/openai.yaml file, check the skill after transferring it: some settings are specific to a particular client.

This loading method is called progressive disclosure. The agent uses a skill’s name and description to determine when it is relevant. When a task matches the description, the agent reads the full SKILL.md and follows it. This means you can keep dozens of skills in Codex without loading every instruction into context: the initial list takes up no more than 2% of the context window (or 8,000 characters if the window size is unknown). If there are many skills, Codex first shortens their descriptions; with a very large set, it may omit some from the list and notify you.

It is easy to confuse a skill with AGENTS.md. Codex reads this file in every project session. It contains standing rules: the tech stack, conventions, and coding style. A skill loads on demand when a task matches it. So put standing rules in AGENTS.md, and put a repetitive process with steps in a skill.

Hermes Agent skills work similarly, but are stored in different folders and installed differently. They are covered in a separate guide: Hermes Agent Skills: Installation and Creation. This article is about Codex only.

What Does a Skill Consist Of?#

A skill folder has this structure:

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

The SKILL.md file itself starts with a metadata block between three hyphens, followed by the instruction text in Markdown:

---
name: weekly-sales-report
description: Compile a weekly sales report from a CSV export. Use when asked for a weekly sales report or a summary by manager.
---

1. Read the export file at the path provided by the user.
2. Group the rows by manager and calculate the total and number of deals.
3. Compare with the previous week if the file for the previous week is nearby. If it is not there, say so directly in the report.
4. Save the result to report.md: a table by manager, the total, and up to three key changes with figures, as many as the data supports.

Three rules from OpenAI’s official recommendations:

• One skill, one task. Instead of “Handle all my marketing,” choose a specific task: “compile a sales report from this export.” Break a larger process into separate skills that can be invoked in sequence.
• Write steps directly, with explicit inputs and outputs: what to use, what to do, and where to put the result.
• Start with text instructions. Use scripts in scripts/ when a step must run exactly the same way each time—for example, to convert a file or call an external system.

Codex selects a skill for a task based on the description field, so start the description with the task and the words you typically use to describe it.

Where Does Codex Look for Skills?#

Project skills are convenient to store in git with the code so the whole team gets the same set. Personal skills work well for your own processes, such as your email style. If two skills at different levels have the same name, Codex does not merge them: both appear in the list, making it harder to choose. Keep their names unique.

For comparison, Claude Code skills are stored in .claude/skills, each with its own SKILL.md, and use the same open standard. A simple skill can be transferred there by copying its folder, after which you should run it and check that it is invoked. For a comparison of Claude Code extensions, see Skills, Subagents, MCP, or Plugins.

How Does Codex Decide Which Skill to Invoke?#

Explicit invocation is more reliable at first: in the Codex CLI, enter $weekly-sales-report to select that specific process. Implicit invocation is more convenient for everyday work. After writing a skill, test it with ordinary wording: ask Codex to do the task in your own words, without $, and see whether it selects the skill. If it does not, first check whether Codex can see the skill in /skills, whether the skill is in one of the loading folders, and whether the skill or its automatic invocation is disabled. If it is available and the settings are correct, refine the description: state the task and typical ways of phrasing the request.

If you want a skill to be available only through an explicit command, you can configure that too: in agents/openai.yaml, the allow_implicit_invocation: false parameter disables automatic invocation, while $name continues to work. You can disable a skill completely without deleting it through ~/.codex/config.toml:

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

After editing config.toml, restart Codex. Codex picks up changes to skill folders automatically, but if a new skill does not appear, restart Codex.

How to Create Your Own Skill: Step by Step#

1. Choose one task

   Pick a process you repeat regularly that has a clear result: a report, table, letter, or analysis. If you have never received that kind of result, first complete the task manually with an agent. Use the result you get as the benchmark for the instructions.

2. Create a skill

   To create a skill with the built-in assistant, enter $skill-creator in a Codex session. It will ask what the skill does, when it should be invoked, and whether scripts are needed, then assemble the framework for you. To create one manually, make a .agents/skills folder in the project with a subfolder for the skill, such as .agents/skills/weekly-sales-report, and put a SKILL.md file inside using the example above.

3. Write the instructions

   Write the steps as a numbered list with explicit input and output. If the process requires precision (transferring data, renaming, calculating), spell out every step in detail. For creative tasks (writing copy, choosing arguments), set boundaries and criteria for a good result, while leaving the model room to work.

4. Test invocation

   Ask Codex to do the task in your own words, without naming the skill. If it selects the right skill, the description worked for that phrasing. Then test explicit invocation with $name. If the skill is not invoked, check the folder, whether it appears in /skills, and the disable settings described above. If a new skill does not appear in the list, restart Codex. If explicit invocation works and automatic invocation is allowed, but Codex does not respond to a request in your own words, refine the beginning of the description: put the task first, followed by typical ways of phrasing it. Test again.

5. Refine after runs

   After each run, review the result and tell the agent what to change in the skill: “Next time, add a column showing the share to the summary table.” Refine a skill for creative work based on feedback if the first version does not produce the result you need.

Ready-made skills from OpenAI and the community are installed with $skill-installer and the skill’s name. To share your own skills with other people, distribute them as plugins—this is a separate packaging method that is not needed for personal use.

How to Check an Agent’s Result#

Checks can be objective or subjective. Objective checks are measurable: “the report includes all 12 managers from the export,” or “the table sum matches the CSV total.” Record these as firm requirements. Subjective checks concern quality: “the text reads like mine,” or “the conclusions are brief.” You can formalize these too: include an example of a good passage in the skill and ask the agent to compare its result with the example.

A useful technique is a review cycle: after preparing the result, the agent goes through a list of criteria, fixes anything it finds, and only then shows it to you. Anthropic has a similar pattern called evaluator-optimizer: one agent does the work, a separate evaluator reviews it and returns feedback, and the process repeats until acceptance. Within a single skill, this is usually a simplified version—a final self-check against a list. Keep its limitation in mind: it is weaker than an independent evaluator because the agent doing the work may not notice its own mistake.

Example of a check block for our report:

## Before submitting, check
- Every manager from the export is present in the table; no one was left out.
- The total matches the CSV sum down to the last cent.
- Every key change is supported by a figure; if there is no data for comparison, the report says so directly.
- The file is saved at report.md, and the path has been shared with the user.

Which Model Should You Choose for a Skill?#

The rightmost column suggests tasks for initial checks. It is not a ranking or the result of a comparison: you can identify the right model for your skill only after running it and comparing it with the benchmark result.

The prices in the table are API rates from the model pages as of September 20, 2026, not ChatGPT subscription prices. When using a subscription, usage comes from its limits. As of this date, Sol has a promotional rate of $4/$20 through at least November 21, 2026; the standard price is $5/$30. Before a large recurring run, check the pricing page: OpenAI promotions change.

Run the same skill on the next less expensive model and compare the result with the benchmark. If quality holds, try the next, even less expensive model. If quality drops, go back to the previous one. Models also have effort levels: Astra ranges from low to max, and the 5.6 family ranges from none to max. Test those against the same benchmark too: first choose the model, then the effort level.

Running a skill regularly means recurring costs. Astra’s input price is 50 times Luna’s, so using different models for the same recurring skill can lead to noticeably different costs. For a skill that analyzes screenshots and documents, a weaker model may cost more because of rework.

Common Mistakes When Creating and Using a Skill#

• A skill “for everything.” One process, one skill—that is also OpenAI’s recommendation. It is hard to describe a universal, ten-page skill precisely, and Codex selects a skill for a task based on its description.
• A vague description. “Helps with reports” does not make clear what kind of reports the skill is for. Put the task and typical ways of phrasing it at the beginning of description.
• Instructions with no defined result. If you do not specify what should be produced and where to put it, results may vary from run to run.
• No checks at all. Without a final step with criteria, the result may be an unfinished draft that you will have to review in full yourself.
• The most capable model by default. First check whether a less expensive model can handle the task: run the same skill and compare the result with the benchmark. Switch only if quality holds.
• The same names in different folders. Codex does not merge skills with the same name, making it harder to choose the right one.

How to Get Started and Transfer a Skill to Claude Code#

If you work with multiple agents, you can transfer a folder containing only text instructions and a SKILL.md file to Claude Code. There, skills are stored in .claude/skills and invoked with /name. Check a skill after transferring it if it contains scripts, dependencies, or agents/openai.yaml. For a guide to the Claude Code skill library, see Claude Code Skills: How to Build Your Own Set; for a comparison of Codex and Claude Code, see Codex vs Claude Code.

Open Ailoot.