Markdown and SKILL.md

Big idea

Agent skills are usually plain Markdown files, because the reader is a language model that needs clear prose rather than a special format — and the short frontmatter description decides whether the skill ever gets used at all.

What a .md file actually is

Markdown is plain text with a small set of characters that mean something extra: # for a heading, **bold**, - for a bullet, ``` around code. There's no hidden formatting layer like a Word document has — anyone (or anything) can open a .md file and read it as-is, and it also renders into clean, formatted output wherever Markdown is supported (GitHub, this very page, most chat tools).

Think of it like

Picture a box of handwritten recipe cards. Each card has a title and a one-line note at the top, like "quick weeknight soup, uses leftover vegetables," with the full method written below. When deciding what to cook, you flip through reading only those top notes and pull out a card only when one matches your situation. A card labeled simply "good food" never gets chosen. A SKILL.md works like one of those cards: the frontmatter is the note you skim, the body is the method, and the whole thing is plain writing anyone can read.

Why agentic tools are configured in plain text

You might expect a "skill" for an AI agent to be some kind of compiled plugin or a JSON config file. Instead, most agent skills are just Markdown — because the thing reading the file is itself a language model. A model doesn't need a special binary format to understand instructions; it needs clear, well-structured prose, which is exactly what Markdown is good at. Plain text is also trivially easy for a human to read, edit, and version-control (in git, right alongside code) — no special editor or build step required.

Reading a real SKILL.md

A skill file typically has two parts:

• Frontmatter — a small metadata block at the top (name, a one-line description of when to use this skill) that a tool scans without loading the whole file, to decide if this skill is even relevant right now.
• Body — the actual instructions: what to do, in what order, with what constraints, written as if briefing a competent colleague who's never seen this task before.

The description in the frontmatter matters more than it looks — it's the only thing deciding whether the skill fires at all. A vague description ("helps with data") might never trigger, or might trigger on the wrong tasks; a specific one ("use when the user wants to clean a messy CSV or Excel file") triggers reliably.

Watch it

Watch an assistant choose a skill from its frontmatter, then load the body only when it is needed.

Markdown in 30 seconds

# Project notes            ← heading (one # per level)

**Bold**, *italic*, `inline code`

- a bullet list
- another item

1. a numbered list
2. second step

| Column | Another |      ← a table
| --- | --- |
| a | b |

A skill file

A skill is a folder with a SKILL.md inside. The frontmatter at the top tells the assistant when to use it; the body tells it how:

---
name: release-notes
description: Write release notes from a list of merged pull requests. Use when the user asks for release notes, a changelog, or "what's new".
---

# Writing release notes

1. Group changes under "New", "Improved", and "Fixed".
2. One line per change, written for users — no ticket numbers or file names.
3. Lead with the most visible change.

See `examples/v2.3.md` for the tone we use.

Only the name and description — a few dozen tokens — are loaded up front for every skill. The body, and any files it points to, are read only when the skill is actually used, so an assistant can have hundreds of skills installed without filling its context.

Key terms

• Markdown — Plain text that uses a few symbols, like # and **, to mark headings, bold text, and lists.
• SKILL.md — A Markdown file that gives an AI agent instructions for handling a particular kind of task.
• Frontmatter — A small metadata block at the top of a skill file that a tool scans to decide if the skill is relevant.
• Body — The main part of a skill file containing the actual step-by-step instructions.

Why it matters

Once you can read a SKILL.md, you can read any agent's configuration — there's no proprietary format to learn. It's also a preview of a pattern that shows up constantly in this track: giving a model good, plain-language instructions is usually a bigger lever than any amount of clever engineering around it.