Technical reference· Learn
SKILL.md Structure Explained
A reference for SKILL.md metadata, descriptions, instructions, and optional skill folders.
beginner7 min readUpdated May 4, 2026
Short answer
A skill is a directory. SKILL.md is the required file inside it. The file needs a name, a description, and the instructions Codex should follow when the skill is selected.
Minimum viable skill
---
name: focused-skill
description: Use when this exact repeatable workflow is needed. Explain when not to use it.
---
Instructions for the agent to follow.
The metadata helps the agent decide whether to load the full skill. The instructions tell the agent what to do after it has chosen the skill.
The description is the matching contract
- Lead with the task that should trigger the skill.
- Name the expected output.
- Include common trigger words users naturally type.
- State exclusions when adjacent skills or prompts are a better fit.
Progressive disclosure keeps context small
Codex initially sees the available skill names, descriptions, and paths. It reads the full SKILL.md only when the task matches. This is why the description should be concise and front-loaded.
Keep SKILL.md lean
Put the high-signal workflow in SKILL.md. Put long examples, policies, and bulky references in references/ so they load only when needed.
Optional folders
| Folder | Purpose |
|---|---|
| scripts/ | Executable helpers for deterministic checks or transformations. |
| references/ | Long-form documentation, examples, policies, or domain notes. |
| assets/ | Templates, starter files, images, or reusable resources. |
| agents/ | Optional OpenAI metadata such as display information and tool dependencies. |