Lesson 2: Anatomy of a Skill: The SKILL.md File

Learning goals:

• Understand the two-part structure of SKILL.md
• Know the required fields in the YAML frontmatter
• Learn to write a description that actually works
• See how to organize the instructions section

Prerequisites: << Lesson 1 | Next: Lesson 3 >>

What a Skill file looks like

Open any Skill and you'll find the same shape:¹

There are two parts to this file:

1. YAML frontmatter (everything between the --- markers): metadata that tells Claude the basics about this Skill
2. Markdown instructions (everything after): the actual directions that tell Claude what to do

YAML frontmatter: how Claude finds your Skill

The frontmatter is the block at the very top wrapped in ---. It tells Claude the two things that matter most:^{2 3}

name: the Skill's unique identifier

• Rules: lowercase letters, digits, and hyphens. No spaces.
• What it does: the name becomes the command, like /task-organizer
• Advice: make it descriptive, short, and obvious at a glance

Good names:

• meeting-notes
• code-review
• changelog-generator

Bad names:

• my-skill-1 (says nothing)
• super_amazing_task_helper (too long, and underscores aren't allowed)
• taskOrganizer (camelCase — it has to be lowercase with hyphens)

description: the field that matters most

This one sentence decides three things:⁴

1. When Claude loads this Skill on its own
2. What users see in the Skills list
3. What Claude understands this Skill to be for

That's why it deserves more care than anything else in the file:⁴

"The description is the single most important field in your frontmatter. A bad description means your skill either never triggers or triggers on everything. The formula: What it does + When to use it + Key capabilities."

A good description:

Bad descriptions:

Optional fields (covered in Lesson 6, not here)

• model: pick which model to use
• allowed-tools: restrict which tools this Skill can touch
• version: a version number

For your first Skill, name and description are all you need.³

Markdown instructions: telling Claude how to do it

Everything after the frontmatter is written for Claude to read and follow.¹

Good instructions share three traits:

1. Clear sections

Use headings to separate the parts:

2. Concrete steps

Weak:

Strong:

3. Examples

If the output format matters, show one:

Once Claude has an example, it knows exactly how to lay things out. Showing beats describing — a sample output does more work than three paragraphs about formatting.

How the two parts work together

The frontmatter is the discovery mechanism; the instructions are the execution guide.^{5 6}

1. You type /task-organizer, or just say "help me sort out these tasks"
2. Claude reads the name and description in the frontmatter and decides whether to load this Skill
3. If it loads, Claude reads the full instructions
4. Claude works through the steps as written
5. The output matches the format the instructions specified

This is why the description has to be good: it's the only evidence Claude has when deciding whether to use this Skill at all.⁴

Write "helps with tasks" and Claude has no idea which situations call for it. Write "sorts a messy to-do list into groups by priority and due date" and the words "sort", "to-do", and "tasks" in a request are enough to bring it in.

A real example: taking apart a code review Skill

Here's a Skill that gets real use:

Breaking it down:

• The description in the frontmatter: says what it does (reviews code) and what it checks for (conventions, bugs, performance)
• The instructions split into three checklists: conventions, bugs, performance, each with specific items to look at
• The output format is explicit: every issue must carry a location, a problem, and a suggestion

A Skill written like this gets it right on the first try.

Recap

• SKILL.md has two parts: YAML frontmatter (metadata) and Markdown instructions (directions)
• Required frontmatter fields: name (lowercase, hyphens, unique) and description (what drives automatic triggering)
• The description formula: what it does + when to use it + key capabilities
• Three traits of good instructions: clear sections, concrete steps, worked examples
• How the parts fit: the frontmatter lets Claude find the Skill; the instructions let Claude run it

Next lesson, we start from nothing and write a complete Skill end to end.

>> Lesson 3: Hands-On: Writing Your First Skill