What Skills Are: the SKILL.md Spec, Directory Layout, and Three-Stage Progressive Disclosure

Today's Goals

1. State a skill's minimal makeup, and explain what each of the optional scripts, references, and assets directories holds
2. Recite SKILL.md frontmatter's two required fields and their hard constraints
3. Explain three-stage progressive disclosure in your own words, and work out how much context it saves versus loading everything

This course's positioning in one line: MCP handles the wiring, Skills handle the experience, and context engineering handles the trade-offs. Today lays the foundation of the experience half — what a skill actually is, and how it manages to show up on its own exactly when it should. Once you have read the walkthrough and finished the lab, scroll back to the top and tick off the three goals.

Plain-Language Walkthrough

The work instructions in the filing cabinet

Imagine joining a company that has been running for ten years. A colleague walks you to a row of metal filing cabinets at the end of the corridor and says: "From now on, before you do anything, come look in here." Inside are dozens of folders, each with one line on its cover — "when a customer complaint has gone two days without a reply, open me," "before quarterly reports go to finance, open me." You do not have to memorize the contents of every folder, only those dozens of cover lines; when the situation actually arrives, you pull out the matching one and read it.

That is the whole intuition behind Agent Skills. A large model is plenty clever, but it does not know how things are done around here: what format commit messages take, which columns of a report have to line up, which endpoint's return value has a well-known trap in it. None of that is in its training data; it lives in your head and in your team's unspoken agreements.

One thing often conflated needs separating first. A tool solves can it be done — the model cannot read your database, and giving it a query tool means it can. A skill solves how should it be done — the model can already write a commit message, but what it writes does not match your conventions. Capability gaps are filled by tools and experience gaps by skills, and those are two different things. On day six we put function calling, MCP, and Skills into one table and compare them cell by cell; today, just remember the division.

So why not simply write all the experience into the system prompt? Because you pay for it twice. The first payment is cash: the system prompt is resent on every turn, so twenty team conventions filling, say, six thousand tokens means a fifty-turn session is billed three hundred thousand tokens for repetition. The second is dearer — a model's attention is finite, and a system prompt stuffed with twenty unrelated matters will let rule seventeen interfere while it works on the third of them. The value of a filing cabinet is not how much it holds but that it stays closed until it is needed.

A skill is a folder

The spec defines this with extreme plainness: a skill is a directory containing a SKILL.md file. Nothing else is required — no registration, no manifest file, no compilation.

A skill using every available convention looks like this:

commit-message/
├── SKILL.md          # required: metadata plus the instruction body
├── scripts/          # optional: executable code
│   └── check_scope.py
├── references/       # optional: documents consulted on demand
│   └── REFERENCE.md
└── assets/           # optional: templates and static resources
    └── template.md

Those three optional directories are not arbitrary names; they correspond to three entirely different kinds of thing, and telling them apart is what makes tomorrow's layering work.

scripts/ holds executable code. The criterion is "this logic should give exactly the same result every run" — validating that a JSON payload has all its fields, converting one table format into another. Having the model rewrite that each time is both slow and unstable, so write it as a script and call it once. Day four spends the whole day on this directory.

references/ holds documents consulted on demand. The criterion is "this material is long but unneeded most of the time" — the complete error code table of an endpoint, the field dictionary of a format. The spec advises cutting each reference file small and keeping it focused, because the model loads them one file at a time, and the smaller the file the less is wasted.

assets/ holds static resources. Output templates, configuration boilerplate, lookup data files, diagrams. The difference from references/ is that references are knowledge for the model to read while assets are material for the model to use.

Beyond those three you can put any file or directory you like; the spec does not care. But those three names are a community convention, and people opening your skill will look for things by that instinct, so it is best not to invent your own scheme.

Reading the frontmatter field by field

SKILL.md is structured as YAML frontmatter plus a Markdown body — the same pattern as this course's own chapter files. The smallest possible skill needs only two fields:

---
name: commit-message
description: Write Git commit messages to the team's convention. Use when the user is committing code, writing a commit message, or asking how to describe a change.
---

name is required and tightly constrained; note each constraint. Length 1 to 64 characters; lowercase letters, digits, and hyphens only; no leading or trailing hyphen; no two consecutive hyphens; and it must match the parent directory name. So PDF-Processing, -pdf, and pdf--processing are all non-conforming.

Why so tight? Because the name is this skill's unique identity across the whole ecosystem: it goes into the directory name, into namespaces, into the slash command a user types, and it decides precedence when two skills collide. Any inconsistency of case anywhere becomes a very hard-to-diagnose "it is clearly installed and I cannot invoke it."

description is the other required field, 1 to 1,024 characters. It has to answer two questions at once: what this skill does, and when it should be used. The spec's good-and-bad comparison is bluntly clear — "Helps with PDFs" is the bad example, and "Extract text and tables from PDFs, fill in forms, merge multiple PDFs. Use when the user is working with PDF documents or mentions PDFs, forms, or document extraction" is the good one. Tomorrow spends a whole day on this one field; today, just remember: it is the skill's only trigger surface, and get it wrong and nobody will ever open the body no matter how well written it is.

Four optional fields each have a use, and knowing they exist is enough. license states the license, and a license name or a pointer to the license file in the package is advised. compatibility states environment requirements, up to 500 characters, and only skills genuinely picky about their environment should have it — "requires git, docker, jq, and network access," say. metadata is a string-to-string map into which a client can stuff attributes outside the spec, and keys are best made distinctive to avoid collisions. allowed-tools is a space-separated string listing pre-approved tools, and this field is still experimental, with support varying between implementations.

The spec places no constraint on the body's format; write what you like. The structure it suggests is step-by-step instructions, input and output examples, and common edge cases. Days two and three expand on those three parts.

Three-stage progressive disclosure

Now to today's most important mechanism. Progressive disclosure has three stages, and each loads something entirely different.

flowchart LR
  A[Session starts] --> B[Stage one: discovery<br/>reads only name and description<br/>about 50 to 100 tokens each]
  B --> C{Does the task match<br/>a description?}
  C -- No --> B
  C -- Yes --> D[Stage two: activation<br/>reads the full SKILL.md<br/>ideally under 5000 tokens]
  D --> E{Does the body name<br/>an attachment?}
  E -- No --> F[Execute per the instructions]
  E -- Yes --> G[Stage three: execution<br/>read scripts, references, assets on demand]
  G --> F

Stage one is discovery. As soon as a session starts, the client scans the skill directories, extracts each skill's name and description, assembles a catalog, and puts it into the context. Note that it reads only those two fields and not one word of any body. The official figure is roughly 50 to 100 tokens per skill.

Stage two is activation. The model reads that catalog, judges which entry the current task matches, and reads that one skill's full body into the context. The spec advises keeping a body under 5,000 tokens and 500 lines, and anything beyond that should move into references/.

Stage three is execution. If the body says "when validation fails, read references/api-errors.md," only then does the model read that file; if it says "run scripts/validate.py," only then does it run it. This stage triggers per file, on demand, rather than dumping the whole directory in.

There is one lesson here that is most easily overlooked and most reveals the author's skill: write explicitly in the body when to read which file. Writing "details are in the references directory" is nearly the same as writing nothing, since the model does not know when to look; writing "if the endpoint returned a non-200 status code, read references/api-errors.md" genuinely puts the loading moment in the model's hands.

Working out the context bill

Saying "it saves" is not enough; the numbers make the case. Suppose you have 20 skills installed, each SKILL.md body written up to the spec's 3,000-token limit, with accompanying reference files averaging 5,000 tokens.

Without progressive disclosure, everything in the system prompt: 20 times 3,000 is 60,000 tokens, plus 100,000 for the reference files, or 160,000 tokens in all. That already exceeds many models' windows, and it is resent on every single turn.

With progressive disclosure: stage one at 80 tokens each is 1,600 tokens for 20 skills; a session matches 1 or 2 skills on average, so stage two spends 3,000 to 6,000; stage three reads one or two reference files for another 5,000 to 10,000. The total lands between 10,000 and 18,000 — about a tenth of the load-everything approach.

What is saved is not only money. The window is finite, and going from 160,000 to 16,000 frees room for the code and data of the thing you are actually doing. What belongs in the window and what does not is a craft in itself, and our sister course Context Engineering in 5 Days is devoted to that trade-off.

Part of this bill can be verified by hand: stage one's cost is the only fixed overhead you pay every single time, so it is worth measuring how large your own skills' catalog really is. The code below scans a directory, extracts each skill's name and description, and estimates the catalog's token cost.

import { readdir, readFile } from 'node:fs/promises'
import { join } from 'node:path'
 
// A rough estimate: about 4 characters per token for English prose. Use a real tokenizer when precision matters.
const estimateTokens = (text: string) => Math.ceil(text.length / 4)
 
async function catalogCost(skillsDir: string) {
  const entries = await readdir(skillsDir, { withFileTypes: true })
  let total = 0
  for (const entry of entries) {
    if (!entry.isDirectory()) continue
    const raw = await readFile(join(skillsDir, entry.name, 'SKILL.md'), 'utf8').catch(() => null)
    if (raw === null) continue // a directory without SKILL.md is not a skill; skip it
    const name = /^name:\s*(.+)$/m.exec(raw)?.[1]?.trim() ?? entry.name
    const description = /^description:\s*(.+)$/m.exec(raw)?.[1]?.trim() ?? ''
    const cost = estimateTokens(name + description)
    total += cost
    console.log(`${name.padEnd(24)} ${String(cost).padStart(4)} tokens`)
  }
  console.log(`catalog costs roughly ${total} tokens, paid once on every turn`)
}
 
await catalogCost(process.argv[2] ?? '.agents/skills')

import math
import re
import sys
from pathlib import Path
 
 
# A rough estimate: about 4 characters per token for English prose. Use a real tokenizer when precision matters.
def estimate_tokens(text: str) -> int:
    return math.ceil(len(text) / 4)
 
 
def catalog_cost(skills_dir: Path) -> None:
    total = 0
    for entry in sorted(p for p in skills_dir.iterdir() if p.is_dir()):
        skill_file = entry / "SKILL.md"
        if not skill_file.exists():  # a directory without SKILL.md is not a skill; skip it
            continue
        raw = skill_file.read_text(encoding="utf-8")
        name = m.group(1).strip() if (m := re.search(r"^name:\s*(.+)$", raw, re.M)) else entry.name
        desc = m.group(1).strip() if (m := re.search(r"^description:\s*(.+)$", raw, re.M)) else ""
        cost = estimate_tokens(name + desc)
        total += cost
        print(f"{name:<24} {cost:>4} tokens")
    print(f"catalog costs roughly {total} tokens, paid once on every turn")
 
 
catalog_cost(Path(sys.argv[1] if len(sys.argv) > 1 else ".agents/skills"))

Run it once and you will find that a catalog of two or three skills is only a couple of hundred tokens, essentially free; but if every description is written to the 1,024-character limit, a catalog of twenty skills costs eight thousand tokens — and at that point the fix is not deleting skills but writing shorter descriptions.

How it differs from the instruction files you already use

The first reaction is often: is this not just cutting AGENTS.md or the convention file in the project root into small pieces? It looks similar in form and is a different mechanism.

A resident instruction file is a sticky note left open on the desk. It enters the context in full on every session, whether or not today's work has anything to do with it. So it suits only things true regardless of what you are doing: code style, language preference, directories nobody may touch. Once past a hundred or two hundred lines it starts diluting attention.

A skill is a closed filing cabinet. Only one cover line shows, and it opens on a match. So it suits things true only in a specific situation: the full procedure for a class of task, the traps of a format, how a particular report is filled in.

A prompt template is the folder you pull out yourself. It also lives in a file, but you are choosing it, not the model. The key difference between a skill and a template is exactly that choosing: with a good description, the model decides which folder to open. That is why tomorrow spends an entire day on that one field.

The criterion boils down to one sentence: is this piece of experience useful every time? If yes, put it in the resident instruction file; if not, make it a skill.

While we are here, let me fill in the basics. A skill does not change how an agent runs; it only puts an extra piece of material into the context of the thinking step — the loop is still the think, act, observe loop. If you have never hand-written that loop and lack a feel for it, read day 2 of the 30-day course: how tool calling works and hand-writing an agent loop, which takes an hour to fill in and gets used on day five when we write a skill runtime ourselves.

The code below is the minimal illustration: a skill catalog is a passage of text composed into the system prompt, and activation is appending one skill's body as a message. Fifty lines shows the whole picture.

type Skill = { name: string; description: string; location: string; body: string }
 
function buildCatalog(skills: Skill[]): string {
  if (skills.length === 0) return '' // omit the section entirely when there are none; never hand the model an empty list
  const items = skills
    .map((s) => `  - name: ${s.name}\n    description: ${s.description}\n    location: ${s.location}`)
    .join('\n')
  return [
    'The following skills provide specialized instructions for particular tasks.',
    'When a task matches a description, read the file at its location before continuing.',
    'available_skills:',
    items,
  ].join('\n')
}
 
function activate(messages: Array<{ role: string; content: string }>, skill: Skill) {
  // Stage two: the whole body enters the context as one message and stays; do not let compaction clear it
  messages.push({ role: 'user', content: `skill_content name=${skill.name}\n${skill.body}` })
}

from dataclasses import dataclass
 
 
@dataclass
class Skill:
    name: str
    description: str
    location: str
    body: str
 
 
def build_catalog(skills: list[Skill]) -> str:
    if not skills:  # omit the section entirely when there are none; never hand the model an empty list
        return ""
    items = "\n".join(
        f"  - name: {s.name}\n    description: {s.description}\n    location: {s.location}"
        for s in skills
    )
    return "\n".join(
        [
            "The following skills provide specialized instructions for particular tasks.",
            "When a task matches a description, read the file at its location before continuing.",
            "available_skills:",
            items,
        ]
    )
 
 
def activate(messages: list[dict[str, str]], skill: Skill) -> None:
    # Stage two: the whole body enters the context as one message and stays; do not let compaction clear it
    messages.append({"role": "user", "content": f"skill_content name={skill.name}\n{skill.body}"})

Understand those two functions and you have understood the same thing every client is doing. Day five completes them into a runtime that genuinely runs: adding the scan, lenient parsing, and precedence for name collisions.

Source Reading

Hands-On Lab

There is no code to write today; the deliverable is a worksheet for reading existing skills — learn to read first and you will be able to write tomorrow. Before starting, leave the "reading the frontmatter field by field" section open in a tab, because you will keep coming back to it while filling in the table. Pick the material from the example repository, choosing skills whose purpose you can grasp at a glance rather than the most complex ones.

1. Open the already-filled row in the solution and read it against the SKILL.md of the skill it cites, working out where in the file each column's content was taken from.
2. Pick three skills from the example repository and fill one row each in the starter's table: name, trigger surface, body layering, accompanying directories.
3. For each skill write one sentence that triggers it and one similar-looking sentence that should not, marking which word makes the difference.
4. Count the description character count and SKILL.md line count for all three, judging each against the spec's two budget lines.
5. Write the summary paragraph, then self-check against the acceptance criteria one by one; all four passing means done.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward a skill's makeup and the spec's constraints, the three stages of progressive disclosure, and the boundary between a skill and a prompt file. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• State a skill's minimal makeup, and explain what each of the optional scripts, references, and assets directories holds
• Recite SKILL.md frontmatter's two required fields and their hard constraints
• Explain three-stage progressive disclosure in your own words, and work out how much context it saves versus loading everything
• State the division of "tools fill capability gaps, skills fill experience gaps," with an example of each
• All 4 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D2) we write the first real skill. The order is deliberate: today you learned that the description is the only trigger surface, so tomorrow spends the whole session on that one field — how to pick trigger words, how to draw the boundary, how to layer the body, and how to verify after installing into a client that it really did get opened. Understand the mechanism before building, and your first skill will not be an ornament that is installed and never triggered.