Codex Skills: Build Reusable Workflows with SKILL.md

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 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:

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:

.agents/
└── skills/
    └── summarize-incident/
        └── SKILL.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:

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.

Official reference: Build skills for ChatGPT and Codex.