Anatomy of a Skill: Field-by-Field Reference for SKILL.md

A skill is a folder with a SKILL.md file at the top. This guide walks every field of the frontmatter, why it matters, and how to write descriptions that actually trigger reliably.

A skill is a self-contained folder with a SKILL.md file at the top, plus any supporting scripts, templates, or reference docs. The folder name becomes the skill’s identifier. The SKILL.md file is the only thing the agent reads at discovery time — everything else is loaded on demand, when the skill is actually invoked.

This guide is the field-by-field reference for that file: what each piece does, what makes it fire, and how to avoid the mistakes that cause a skill to sit in your repo never getting triggered.

Overview

Every skill lives in its own folder under skills/. Inside that folder, you’ll typically have:

  • SKILL.md — the manifest + body, read at discovery
  • scripts/ — optional Python/Node helpers loaded on invocation
  • templates/ — optional templates referenced from the body
  • reference/ — optional deep-dive docs the agent can read on demand

Rule of thumb. If you can’t tell from the description alone whether the skill should fire, neither can the model. Treat the description as a routing signal, not a summary.

The frontmatter

YAML frontmatter at the top of SKILL.md declares the skill’s metadata. The two fields you’ll spend the most time on are name and description.

markdown
---
name: pdf
description: Use this skill whenever a PDF file is involved — extracting text, merging, splitting, filling forms, or generating new PDFs. Trigger on mentions of .pdf, "the pdf", forms, or merge/split.
version: 1.2.0
---

# PDF Skill

Detailed instructions go below the frontmatter.

name

Lowercase, hyphenated, matches the folder name. No spaces, no underscores. This is what shows up when the agent invokes the skill, e.g. skill: "pdf".

description

This is the most consequential field in the whole file. The model sees only the name + description when deciding whether to invoke a skill. It does not read the body unless the skill is actually invoked.

Common mistake. Writing the description as a feature list (“supports PDF reading, writing, merging…”). Write it as a trigger statement: “Use this skill when the user…”.

version

Optional but recommended. Semver. Lets you reason about behaviour changes when a skill is updated.

Writing the body

Below the frontmatter, write instructions the way you’d brief a smart contractor: assume they’ve never seen this codebase, give them the conventions, and tell them which files to read for which jobs.

  1. Open with the goal. One paragraph stating what this skill does and when it applies. No marketing copy.
  2. List the assets. Reference any scripts, templates, or reference docs in the folder, with one-line descriptions of each.
  3. Give a worked example. Concrete is better than abstract — show one full invocation end-to-end.
  4. Close with edge cases. A short “Don’t use this when…” section saves the model from misfires.

If your skill bundles executable scripts, document the exact python or node command in the body so the agent doesn’t have to guess.

Final checklist

  • Folder name matches name: exactly
  • Description begins with “Use when…” or “Use whenever…”
  • Description names concrete triggers (file extensions, phrases, verbs)
  • Body is under ~400 lines — anything bigger should move to a reference/ doc
  • You’ve tested at least three trigger phrases against the real model

Once the anatomy is clear, the real craft is in the description copy — that single paragraph decides whether your skill ever runs. After that, see the deeper dive on how trigger matching actually works.

#claude #frontmatter #skill.md #skills