How to write a Codex skill description

What each thing is

1. Skill: a folder with instructions that teaches Codex to do a task the way you want. The SKILL.md file lives inside it.
2. SKILL.md: the main file of the skill. It needs two fields at the top: name (the skill name) and description (the description). Those two fields sit between two lines with ---.
3. Description: a sentence saying what the skill is for and when to use it. Codex uses it to decide whether the skill matches your request.
4. SQL query: a request written in the SQL language to fetch data from a table, such as "add up the sales value for each customer".
5. Automatic invocation: Codex picks the skill by itself when your request matches the description.
6. Direct invocation: you call the skill by name. In the Codex CLI and in the IDE extension, type $ and the skill name.
7. Codex CLI and IDE extension: the Codex CLI is Codex used from the terminal, the program where you type commands. The IDE extension is Codex inside a code editor, such as VS Code.
8. Repository and $HOME: a repository is the folder of a code project. $HOME is your user folder on the computer; the ~ in the commands means the same thing.

How Codex picks

Codex first reads only the name and the description of each skill. The whole SKILL.md, with the step by step, only comes in once it decides to use that skill. That is why the description needs a clear scope: say what the skill does and when it should stay out. If you have many skills installed, Codex may shorten the descriptions. Put the main case and the important words right at the start.

• Vague description: ajuda com dados ("helps with data"). It fits almost any request about data: a chart, a spreadsheet, a report or SQL.
• Clear description: Use para revisar consultas SQL, procurar erros e sugerir melhorias. ("Use to review SQL queries, look for errors and suggest improvements.") It says the subject and what the skill does.

The ready-made example

1. Create the skill folder. The $HOME/.agents/skills folder applies to all your projects. For a skill in a single project, use .agents/skills inside the repository. In the Mac or Linux terminal, the mkdir -p command creates the folder (and the folders above it, if they are missing):

mkdir -p ~/.agents/skills/revisar-sql

2. Inside that folder, create the SKILL.md file with this content:

---
name: revisar-sql
description: Use para revisar consultas SQL, procurar erros e sugerir melhorias. Não use para criar gráficos nem para escrever consultas novas do zero.
---

# Revisar consulta SQL

1. Leia a consulta que a pessoa enviou.
2. Procure erros: comandos escritos errado, tabelas ligadas de um jeito que duplica linhas, filtros de data incompletos e colunas que não existem.
3. Explique cada problema em linguagem simples.
4. Mostre a consulta corrigida e diga o que mudou.

3. Codex notices the new skill by itself. If it does not show up, restart Codex.

How to test

1. Ask for a query review. This request matches the description, so the skill has a good chance of stepping in:

revisa esta consulta:
SELECT cliente, SUM(valor)
FROM pedidos
WHERE data >= '2026-01-01'
GROUP BY cliente;

2. Then ask for something outside the scope. The description says the skill is not for charts, so it probably stays out:

faz um gráfico com esses dados

3. Compare the two answers. In the first one, look for signs that Codex followed the steps of the skill (read it, looked for errors, explained, corrected). That is an indication, not a confirmation. If the result is not what you expected, adjust the description and test again.
4. To call the skill directly, without depending on the automatic choice, in the Codex CLI or in the IDE extension:

$revisar-sql revisa esta consulta

Optional: direct invocation only

If you want the skill to step in only when it is called by name, create the agents/openai.yaml file (a plain text configuration file) inside the skill folder (revisar-sql/agents/openai.yaml) with:

policy:
  allow_implicit_invocation: false

The default is true (on: Codex may pick the skill by itself). With false (off), it does not pick the skill by itself, and calling it with $revisar-sql keeps working.

Summary to keep

1. The description is what Codex reads to pick the skill.
2. Say the subject, what the skill does and when it should stay out.
3. Put the main case at the start of the sentence.
4. Test with a request that should trigger the skill and one that should not.
5. To call it directly: $skill-name in the CLI or in the IDE.

Source

OpenAI, Build skills, Codex documentation, read on November 13, 2026: learn.chatgpt.com/codex/build-skills.

Educational and independent content, not affiliated with OpenAI.