Skills

A prompt you keep retyping is a procedure. A skill is that procedure in a folder, which Codex reads only when it is relevant.

A skill is a directory with a SKILL.md in it, plus optional scripts and references. The file must carry a name and a description. It follows the open agent skills standard, so the same folder works in more than one product.

---
name: release-notes
description: Write release notes from the commits since the last tag. Use when preparing a release or when asked what changed.
---

1. Find the last tag with `git describe --tags --abbrev=0`.
2. Read `git log <tag>..HEAD --oneline`.
3. Group the commits into Added, Fixed and Changed.
4. Write one line per entry, in plain language, no commit hashes.
5. Leave out anything that only touched tests or formatting.

The description is the part that decides whether the skill is ever used, because it is what Codex reads when choosing. The body is a numbered procedure: instructions to somebody capable but new, in the order the work happens.

Why the description has to earn its place

Codex shows the model a list of the skills available, and that list is budgeted: at most two per cent of the context window, or eight thousand characters when the window is unknown. With many skills installed it shortens descriptions first, and can leave some out with a warning.

• Say when to use it, not only what it is. The trigger is what gets matched.
• Keep it short. A long description is a description that gets truncated.
• One job per skill. Two jobs in one skill is a description that matches neither well.

Progressive disclosure

Only the name, description and path are loaded up front. When a skill is chosen, the full SKILL.md is read. That is why a skill can hold a long procedure without costing you anything on the sessions where it is not used, and why AGENTS.md from lesson 6 should stay short: that one is read every time.