Lesson 5 / 25

Anatomy of a Skill

Read and write a SKILL.md file with a name, a description and step-by-step instructions.

A folder with a SKILL.md

A skill is a folder whose main file SKILL.md starts with YAML frontmatter holding a name and a description, followed by Markdown instructions. The folder may also hold scripts, templates and reference documents the instructions point to.

Small folder, loaded on demand

A skill packages instructions and helper files. The agent sees a short description first and loads the rest only when needed.

Three layers: description, instructions, resources.
Figure 2.1 — Description, instructions and resources.

A small SKILL.md

The description tells the agent when to use the skill. The body is the procedure. In Claude Code, project skills live in .claude/skills/<name>/SKILL.md.

---
name: release-notes
description: Write release notes from merged pull requests. Use when the user asks for a changelog or release summary.
---

# Release notes

1. List merged PRs since the last tag with `git log`.
2. Group them under Features, Fixes and Chores.
3. Write one plain-language line per PR.
4. Save the result to `RELEASE_NOTES.md`.

One skill, one job

Keep each skill focused on a single repeatable task. A skill that tries to cover reviews, deployments and docs gets triggered at the wrong times and is hard to maintain.

Quick check: Which part of SKILL.md tells the agent when to use the skill?

  • The last line of the file
  • The folder size
  • The file extension
  • The description in the frontmatter
Answer

The description in the frontmatter — The description is what the agent reads to decide whether the skill applies.