Agent skill
A folder of instructions and optional supporting files that teaches an agent how to carry out a specific, repeatable task.
- Published
- Sep 27, 2026
- Checked
- Sep 27, 2026
How far we checked this page
Signed by Ravalika Korthiwada, Sep 27, 2026. Passing one check says nothing about the next.
- FormatNot checkedThe file format was not checked for this page.
- InstallsNot checkedInstallation was not checked for this page.
- LoadsNot checkedLive loading was not checked for this page.
- HelpsNot checkedA with/without task comparison was not run.
An agent skill is a folder of reusable instructions (and, optionally, supporting scripts, reference files and assets) that teaches a compatible agent how to carry out a specific, repeatable workflow. The Agent Skills specification requires one file, SKILL.md, with YAML frontmatter naming the skill and describing when to use it; the body holds the actual instructions. A host loads the metadata first and only pulls in the full instructions, and any files they reference, once the skill is activated. See progressive disclosure.
For example, our explain-error skill is a folder with SKILL.md (frontmatter: name: explain-error, plus a description of when to use it) and references/checklist.md. On Codex CLI 0.157.1, we confirmed hands-on that it’s discovered from a project’s .agents/skills/ folder and, on a matching prompt, both files are read before it answers.
A skill is instructions, not access: it doesn’t by itself connect to external systems (that’s what an MCP server does) or run in an isolated context (that’s what a subagent does).
Related: Agent skill vs MCP server, Agent skill vs plugin, SKILL.md.