What Is SKILL.md? The AI Agent Skill Format Explained
In a matter of months, SKILL.md went from an obscure feature to the standard way of giving AI agents specialised capabilities — adopted by Claude Code, Cursor, Codex CLI, Gemini CLI and more. If you have heard the term and want to actually understand it, this is the plain-language explanation.
What a Skill Actually Is
A skill is a folder containing a SKILL.md file that teaches an AI agent to do a specific task well. Instead of re-explaining your conventions, your workflow or your standards every single session, you package that knowledge once. The agent then loads it automatically whenever it is relevant.
Why It Exists
Before skills, every AI agent started from zero each session. You re-explained your code review standards, your documentation style, your project's quirks — over and over. A skill captures that knowledge permanently. And because SKILL.md is now a shared standard, the same skill works across every agent that supports it: write once, use everywhere.
The Anatomy of a SKILL.md
Every SKILL.md has two parts. First, YAML frontmatter — the metadata, including a name and a description. Second, a markdown body — the actual instructions: the steps, the conventions, the things to check. The frontmatter tells the agent when to use the skill; the body tells it how.
The Three Types of Skill
Skills span a spectrum. Markdown-only skills are pure instructions — conventions and checklists, no code. Skills with scripts add shell or Python the agent can run for tasks needing real execution. API-calling skills reach external services. Most people start with markdown-only, which already covers an enormous range of useful tasks.
Why One Field Matters Most
Of the two required fields, the description is by far the most important — and the most misunderstood. It tells the agent when to load the skill, by matching what you ask against how the skill describes itself. Get it too narrow and the skill never fires, no matter how good the instructions inside are. That single field is where most skills succeed or fail.
Where to Go From Here
Understanding what SKILL.md is gets you started. Writing skills that reliably trigger, building ones with scripts and APIs, and auditing third-party skills for safety is where the real value compounds.