If you work with AI coding agents, you have probably seen SKILL.md mentioned and wondered what it actually is. In a matter of months it went from one company's feature to a standard adopted across Claude Code, Cursor, Codex CLI, Gemini CLI and more. Here is the plain explanation, with no hype.
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 write them down once. The agent reads them automatically whenever they are relevant.
Think of it as the onboarding note you would give a capable colleague taking over a task — except you write it once, and every agent that supports the standard reads it.
Why it caught on
Before skills, every agent started from zero each session. You re-explained your code review standards, your documentation style, the quirks of your project — over and over. A skill captures that knowledge permanently. And because SKILL.md is a shared format, the same skill works across every agent that supports it. Write once, use everywhere. That combination — solving a real shared problem, simply — is why it spread so fast.
The anatomy of a SKILL.md
Every SKILL.md has two parts.
The frontmatter is YAML metadata between two lines of three dashes. It has two required fields: a name (short, lowercase, hyphenated) and a description (what the skill does and, crucially, when to use it).
The body is plain markdown — the actual instructions. The steps, the order, 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 range from simple to powerful:
- Markdown-only skills are pure instructions — conventions and checklists, no code. This is where most people start, and it already covers a huge range of useful tasks.
- Skills with scripts add shell or Python the agent can run, for tasks that need real execution rather than guidance.
- API-calling skills reach external services — fetching data, posting updates, integrating tools into the workflow.
You do not need to start complex. A markdown-only skill that encodes how you like code reviewed, or commits written, or docs formatted, is genuinely useful on day one.
The field that decides everything
Of the two required fields, the description matters far more than people expect. The agent decides whether to load a skill by reading its description and matching it against what you asked. Write the description too narrowly and the skill never fires — no matter how good the instructions inside are.
The fix is to write the description around the words you would actually type, including the synonyms. Not "Reviews pull requests" but "Reviews code for bugs, style and security. Use when the user asks to review, check, audit or look over code, a pull request, a diff or a file." That one habit prevents most "my skill does not work" problems.
The bottom line
A skill is a small, durable investment: a markdown file that teaches your agent something, once, and applies it consistently across every agent you use. Start with whatever you explain most often, get the description right, and you will wonder how you worked without it.
Free starter: The format, a working template, and the description technique are all on a free cheat sheet: AI Agent Skills Quick-Start Cheat Sheet
Go deeper: The full guide covers the complete specification, five build walkthroughs, ten production-ready templates, security, and a 30-day plan: AI Agent Skills: The Complete SKILL.md Standard Guide
What is the first skill you would write — the thing you explain to your AI most often? Curious to hear in the comments.
Top comments (0)