SKILL.md Fundamentals

Two Parts, One File

Every skill centers on one file: SKILL.md. It has exactly two parts — YAML frontmatter, then a Markdown body:

---
name: skill-name
description: A description of what this skill does and when to use it.
---

Markdown instructions go here.

This lesson covers the frontmatter — the metadata block between the --- lines. What goes in the body, and how the surrounding folder is organized, is the next lesson, Skill Anatomy. For now: two fields are required, and everything else is optional.

The Frontmatter Fields

Only two fields are required. Here’s the minimum valid skill:

---
name: skill-name
description: A description of what this skill does and when to use it.
---

And a more complete example using the optional fields:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

The name Field, in Detail

This is the field most likely to trip up a first skill, because it’s more constrained than a typical Markdown title:

• 1–64 characters
• Only unicode lowercase alphanumeric characters (a-z, 0-9) and hyphens (-)
• Must not start or end with a hyphen
• Must not contain consecutive hyphens (--)
• Must match the parent directory name — a skill at pdf-processing/SKILL.md must have name: pdf-processing

Valid:

name: pdf-processing
name: data-analysis
name: code-review

Invalid, and why:

name: PDF-Processing    # uppercase not allowed
name: -pdf                # cannot start with a hyphen
name: pdf--processing    # consecutive hyphens not allowed

The description Field Matters More Than Any Other

Here’s the fact that makes description worth slowing down for: it’s the only thing an agent reads before deciding whether to use your skill at all. At session start, an agent scans every installed skill and loads just its name and description — not the body, not the scripts, nothing else. If a user’s request doesn’t match what the description says, the skill never activates, no matter how good the instructions inside it are.

That gives description two jobs at once, and good ones do both:

• What the skill does
• When to use it

# Good — covers both what and when
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

# Poor — technically valid, practically useless
description: Helps with PDFs.

The poor version doesn’t tell the agent when to reach for it. “Helps with PDFs” could mean anything from OCR to form-filling to page rotation — an agent matching against it has no real signal to go on. Some rules of thumb:

• 1–1024 characters (the format’s hard limit)
• Include specific keywords a user might actually type — the exact nouns and verbs of the task, not a vague summary
• Say when to use the skill, not just what it does

You’ll get real practice at this in the testing lesson later in the course, where you’ll check whether a description actually triggers on the prompts it should.

Optional Fields, Briefly

Most skills you write early on won’t need these — they exist for cases that come up as skills get more sophisticated.

license — keep it short: either a license identifier or a pointer to a bundled file.

license: Apache-2.0
license: Proprietary. LICENSE.txt has complete terms

compatibility — only include this if your skill has real environment requirements. Most skills don’t need it.

compatibility: Designed for Claude Code (or similar products)
compatibility: Requires git, docker, jq, and access to the internet
compatibility: Requires Python 3.14+ and uv

metadata — a free-form string-to-string map for anything a specific client wants to track that isn’t part of the core spec.

metadata:
  author: example-org
  version: "1.0"

allowed-tools — experimental, and support varies by client. Pre-approves specific tools so the agent doesn’t need to ask permission for each one during execution.

allowed-tools: Bash(git:*) Bash(jq:*) Read

Validating a Skill

The skills-ref reference library checks that your frontmatter is valid and follows the naming conventions above:

skills-ref validate ./my-skill

Run this before you consider a skill finished — it catches the kind of naming mistake (uppercase in name, a missing description) that’s invisible until an agent silently fails to load the skill.

Summary

• SKILL.md is YAML frontmatter, then a Markdown body — this lesson covered the frontmatter
• name and description are the only required fields, but name has strict formatting rules and must match the directory name
• description is the single most important field in the whole file — it’s the only thing an agent sees before deciding to use your skill, so it needs to say both what the skill does and when to reach for it
• Optional fields (license, compatibility, metadata, allowed-tools) exist for cases most early skills won’t need
• skills-ref validate catches formatting mistakes before they cause silent failures

Next, you’ll zoom out from the frontmatter to the whole skill folder — what goes in it, and how the pieces work together.