A SKILL.md file is the heart of every Claude Skill — a Markdown file that starts with a short YAML header (a name and a description) and is followed by the instructions Claude should follow. The description is what tells Claude when to use the skill; the body tells it how.
If you've seen the term and wondered what's actually inside one, here's the anatomy of a SKILL.md, why each part matters, and how to write one that works.
What SKILL.md is
A Claude Skill is a folder, and SKILL.md is the required file at its root. It's plain Markdown, so it opens in any text editor. Claude reads it to learn a capability — the steps, rules, and best practices for one kind of task. Optional extras (templates, scripts, reference files) can sit alongside it in the same folder, but the SKILL.md is the one file every skill must have.
The two parts of a SKILL.md
1. The frontmatter (metadata)
At the very top sits a small YAML block between --- markers. It carries the essential metadata — at minimum a name and a description:
---
name: weekly-report
description: Formats raw notes into our standard weekly report. Use when the user asks for a weekly update, status report, or to "write up the week."
---This block is special: when a session starts, Claude pre-loads only the name and description of every installed skill — not the whole file. That keeps the context window light and is why the description does so much heavy lifting.
2. The body (instructions)
Below the frontmatter, in normal Markdown, you write what Claude should actually do — ideally as clear, numbered steps with any rules or examples:
## Steps
1. Group the notes under Wins, In Progress, and Blockers.
2. Keep each bullet to one sentence, past tense.
3. End with a one-line "Next week" summary.
4. Never invent metrics that aren't in the notes.Why the description is the most important line
Triggering depends entirely on the description. As you work, Claude compares your request against each skill's description and loads the full file only when it matches. A vague description ("helps with reports") rarely fires. A specific one ("use when the user asks for a weekly update or status report") fires reliably. If you remember one rule, make it this: write the description for when to use the skill, not just what it is.
How Claude uses the file
- At startup: Claude reads every skill's name + description.
-
During the task: if your request matches a description, Claude loads that skill's full
SKILL.md(and any attached resources). - Then: Claude follows the body's instructions to complete the work.
This "load it only when needed" approach is called progressive disclosure, and it's what lets you keep many skills installed without bloating the model's context.
Writing a good SKILL.md
- Nail the description. State plainly when the skill should trigger.
- Keep the first version small. Five to ten lines of clear steps beats a sprawling doc.
- Be concrete. Numbered steps, explicit rules, a short example.
- Test on real tasks. Expand only where Claude misses.
Do you have to write one yourself?
No. Writing your own is great for workflows unique to you, but if you just want the result, ready-made skills come with their SKILL.md already crafted and tested. Browse the KissMySkills library of 300+ skills, prompt packs, and agents, or the Claude Code skills collection. Want to see one in action first? Try a free generator or grab a free skill.
Frequently asked questions
Is SKILL.md just Markdown?
Yes — it's a standard Markdown file with a YAML frontmatter block at the top. It opens in any text editor, no special software required.
What's required in a SKILL.md?
At minimum, a frontmatter block with a name and a description. The body with instructions is what makes the skill useful, but the metadata is what makes it discoverable and triggerable.
Where does the SKILL.md file go?
At the root of the skill's folder. In Claude Code, skills live in ~/.claude/skills/<name>/ for personal use or .claude/skills/<name>/ inside a project, with the SKILL.md at the folder root.
Can I use a SKILL.md's content in ChatGPT or Gemini?
Yes. The instructions are portable — paste the body into ChatGPT or Gemini custom instructions for the same behavior. The automatic triggering via frontmatter is a Claude feature.
Start with a working example
The fastest way to understand SKILL.md is to read a good one. Grab a free skill, open the file, and see the frontmatter-plus-steps structure in action — then read how to install it in three minutes.