What is a SKILL.md file? The agent skill file explained

A skill is a folder. The one file it must contain is called SKILL.md. It has two parts: a short header at the top that says what the skill is called and when to use it, and a body below with the actual instructions, written in ordinary Markdown. Markdown is just text with simple marks for headings and lists.

The format was created by Anthropic and is now an open standard, which is why the same skill file works in Claude, Codex, Cursor and many other tools. Some tools add extra features of their own, so a skill written for one may need small changes for another.

The header sits between two lines of three dashes. The standard defines these fields.

Your AI app reads only the name and description of every installed skill at the start. The rest of the file loads only when your request matches. So the description is how the app decides to use the skill at all. A vague description means the skill gets used at the wrong time, or never.

This is also the first thing to check when you pick a skill. A good description names the job and the trigger, for instance when someone asks to rewrite a draft so it sounds natural. Try it on Humanizer to see the idea in practice.

Beyond SKILL.md, a skill folder can hold optional parts.

• scripts/ for small programs the skill can run.
• references/ for longer documents the AI reads only when needed.
• assets/ for templates, images or data files.

Here is a made-up skill, written by us only to show the shape. It is not one of the skills in our list.

---
name: meeting-notes
description: Turns messy meeting notes into a short summary with decisions and next steps. Use when someone pastes notes or a transcript.
---

# Meeting notes

1. Read the notes and find every decision made.
2. List action items with an owner and a date if one is given.
3. Write a summary of no more than five lines.
4. If an owner or date is missing, say so instead of guessing.

That is a complete skill. Real ones are longer, but the idea is the same: a clear trigger and clear steps. If you want help writing one, the skill-creator skill drafts them from a description of your workflow.

In the Claude app, you zip the folder and upload it under Settings > Features. In developer tools, you put the folder in the tool's skills folder, such as the shared .agents/skills folder or the Claude Code skills folder. npx skills automates that copy step.

Skills can run scripts, so read a folder before installing it. Our find skills guide lists checks worth doing.

The best skill files are short and specific. They say what the skill is for in the description, then give numbered steps and a few rules for edge cases. They avoid vague advice like be thorough and instead say what thorough means: check each claim, list sources, flag anything you could not verify.

They also tell the AI what not to do. Skills that only describe the happy path tend to wander. A line such as do not guess missing data, ask instead, can make the difference between a helpful result and a confident mistake.

Longer material belongs in the references folder, which the AI opens only when it needs it. This keeps the main file light, so the skill is quick to load and cheap to run. If you open a skill you like, such as Copywriting, you can see how a well-built one splits instructions from reference material.