# Codex Skills: Build Reusable Workflows with SKILL.md

> Create, install, and test Codex skills with SKILL.md — including trigger descriptions, repo and user paths, progressive disclosure, and distribution.

Codex skills package a repeatable workflow as a directory with SKILL.md plus optional scripts, references, templates, and assets. Codex sees compact metadata first and loads the full instructions only when the user invokes the skill or the task matches its description. Store team skills under .agents/skills, personal skills under ~/.agents/skills, and distribute mature bundles as plugins.

**Codex skills are reusable workflows packaged as directories.** Each skill has a `SKILL.md` file containing a name, a description that controls when it should be considered, and instructions for completing the job. The directory can also hold scripts, reference material, templates, and assets.

Skills build on the open [Agent Skills](/glossary/agent-skills) standard. The same core format can travel across compatible agents, while Codex adds discovery paths, built-in creation and installation helpers, and plugin distribution.

## Skill, AGENTS.md, MCP, or prompt?

These surfaces solve different problems:

| Need | Use |
| --- | --- |
| A requirement for this task only | Prompt |
| A rule that should shape almost every change in this repository | [`AGENTS.md`](/guides/configuration/codex-agents-md) |
| A repeatable procedure that applies to a recognizable class of tasks | **Skill** |
| Live data or an action in an external system | [MCP](/guides/mcp/codex-mcp-setup) |
| Installable packaging for multiple skills and integrations | Plugin |

A release-note workflow is a skill. “Run lint before finishing” is repository guidance. Pulling the current issues from Linear needs MCP; the skill can define how to turn those issues into the release notes.

## The minimum skill

Create a folder whose name matches the skill, then add `SKILL.md`:

```text
.agents/
└── skills/
    └── summarize-incident/
        └── SKILL.md
```

```md
---
name: summarize-incident
description: >-
  Turn incident notes, alerts, and timeline events into a concise post-incident
  summary. Use when the user asks for an incident recap, customer-facing impact
  statement, or timeline synthesis. Do not perform root-cause analysis without evidence.
---

# Summarize an incident

1. Collect the incident window, affected services, user impact, and timeline.
2. Separate observed facts from hypotheses; label missing evidence.
3. Normalize timestamps to one timezone and order events chronologically.
4. Draft impact, timeline, mitigation, current status, and follow-up sections.
5. Return the summary plus a short list of unresolved questions.
```

Only `name` and `description` are required in the core format. The body is an instruction manual for the model, so write direct actions, not marketing copy.

## The description is the router

Codex initially sees skill metadata and loads the full body when a skill is selected. That makes the description load-bearing: it must distinguish this workflow from every neighboring skill before Codex has read the instructions.

A useful description contains three things in this order:

1. **Job** — what transformation or outcome the skill produces.
2. **Triggers** — concrete requests, artifacts, or situations that should select it.
3. **Boundary** — a close neighbor or risky action it should not absorb.

Weak: `Helps with incidents.`

Strong: `Turn incident notes, alerts, and timeline events into a concise post-incident summary. Use when the user asks for an incident recap, impact statement, or timeline synthesis. Do not infer root cause without evidence.`

Front-load the job and best trigger terms. Codex budgets the initial skills list, and very large installations may have descriptions shortened or some metadata omitted before any selected skill body is read.

## Where Codex finds skills

For repository skills, Codex scans `.agents/skills` directories from the current working directory upward to the repository root. This supports both project-wide and subtree-specific workflows. It also reads:

- `$HOME/.agents/skills` for personal skills across repositories.
- `/etc/codex/skills` for administrator-provided skills.
- System skills bundled with Codex.

The folder can be symlinked. If two discovered skills share a name, Codex does not merge them, so use distinct names rather than relying on one silently replacing the other.

In Codex CLI or the IDE extension, use `/skills` to browse skills or type `$` to mention one explicitly. Codex can also activate a skill implicitly when the request matches its description. Newly edited skills are normally detected automatically; restart Codex if an update does not appear.

## Use progressive disclosure

Keep the main `SKILL.md` focused on routing and procedure. Put supporting material beside it and tell the workflow exactly when to open or run it:

```text
summarize-incident/
├── SKILL.md
├── references/
│   └── severity-policy.md
├── templates/
│   └── postmortem.md
└── scripts/
    └── normalize_timeline.py
```

- **References** hold long policies, schemas, or product-specific details needed only for some cases.
- **Templates** make the output shape deterministic without bloating the instructions.
- **Scripts** are appropriate when exact parsing or transformation matters more than model judgment.
- **Assets** can provide images or other files the workflow consumes or emits.

This is progressive disclosure: metadata is always cheap, `SKILL.md` loads on selection, and heavyweight resources load only when a step needs them.

## Test selection, not just output

A skill can produce excellent work when manually invoked and still fail in daily use because its description never routes correctly. Test three layers:

1. **Explicit invocation** — mention the skill directly and confirm the workflow is internally sound.
2. **Positive routing** — try two or three natural user prompts that should select it automatically.
3. **Negative routing** — try near misses that belong to another skill or ordinary reasoning and confirm this skill stays out.

Then inspect the artifact: did it read the right inputs, respect its boundary, handle missing data, and return the promised output? Improve from observed misses, not imagined completeness.

> [!NOTE]
> Local folders are ideal while a workflow is evolving. Once it is stable and meant for other people — especially when it bundles multiple skills or MCP integration — package it as a plugin instead of asking users to copy directories by hand.

Official reference: [Build skills for ChatGPT and Codex](https://learn.chatgpt.com/docs/build-skills).

---

_Source: https://agentscamp.com/guides/skills/codex-skills-guide — Guide on AgentsCamp._