Agent Skills Explained: Packaging Procedures in a SKILL.md Folder

The agent forgets steps, the copies drift apart, and every chat pays for instructions it may not need. Agent skills fix this by putting one procedure in one folder that the agent loads only when the task calls for it.

Picture a common setup. A small backend team in Pune ships every Friday, and someone asks an AI agent to write the release notes. The setup is made up, but the pain is real.

Each person keeps their own copy of the steps in a notes file. One copy says to skip housekeeping commits. Another copy forgets that breaking changes go first. The agent does a different job depending on who pasted what.

Pasting the full procedure into a standing system prompt does not help much either. Those words then ride along with every request, even when someone only asks the agent to fix a typo. The team needs the procedure packaged once, versioned like code and loaded only when release notes are the job.

You need six words. Each one is short, and the rest of the guide uses them the same way every time.

• Agent: a program in which a language model decides the next step, calls tools such as a shell or a file reader, reads the result and repeats.
• Context window: everything the model can see in one request, measured in tokens. Space in it is limited and costs money.
• Token: a small piece of text, often part of a word. Model limits and bills are counted in tokens.
• Markdown: plain text with light formatting, such as a hash sign for a heading and a dash for a list item.
• YAML: a simple text format for settings, written as key, colon, value on each line.
• Frontmatter: a YAML block at the very top of a file, opened and closed by a line of three dashes.

Agent skills are an open format for packaging a procedure so an agent can find it and follow it. The format is not tied to one agent tool. The specification says a skill is a directory, which is another word for folder, containing at minimum a SKILL.md file. Many agent tools can read the same folder, so you write the procedure once.

The SKILL.md file has two parts. The frontmatter at the top says what the skill is called and when to use it. The Markdown body below it holds the steps, examples and edge cases.

Next to SKILL.md you may add any other files. The specification suggests three folder names: scripts for code the agent can run, references for longer documents and assets for templates or data files. None of them is required.

The running example in this guide is that release-notes skill. Its job is to turn the commits since the last git tag into tidy notes, the same way every time. A git tag is a named marker on one commit, such as v1.0.0.

A SKILL.md file holds frontmatter with at least a name and a description, then free-form Markdown instructions. Here is the full file for the running example, exactly as we validated it.

---
name: release-notes
description: Write release notes for this repository from git commits. Use when someone asks for a changelog, release notes or a summary of what shipped since the last tag, even if they do not say "changelog".
license: Apache-2.0
metadata:
  owner: platform-team
  version: "1.2"
---

# Release notes

## Steps
1. Find the last tag: git describe --tags --abbrev=0
2. List commits since that tag: git log LAST_TAG..HEAD --pretty=format:%s
3. Pipe that list into the script: python3 scripts/group_commits.py
4. Fill assets/template.md with the JSON groups the script prints.
5. Check the wording against references/style.md before you finish.

## Gotchas
- Commits starting "chore:", "ci:", "docs:" or "test:" stay out of the notes. The script drops them unless they are marked breaking.
- Breaking changes are marked with "!" after the type, as in "feat!:". List them first.
- Do not invent ticket numbers. If a commit has none, leave it out of the line.

Read it top to bottom. The three-dash lines fence off the frontmatter. Everything after the second fence is the body that the agent follows.

The frontmatter fields

The specification defines six fields, checked on its page as of 23 October 2026. Only two are required. Three of them, name, description and compatibility, have hard length limits.

The description does the triggering

The name and description are the only text the agent sees before it decides to load a skill. The site's guide on optimising descriptions says the description carries the entire burden of triggering. So write it as advice to the agent: what the skill does, then when to use it.

Compare two versions. "Helps with releases." gives the agent nothing to match. Ours names changelogs, release notes and "what shipped since the last tag", and adds "even if they do not say changelog". The same guide recommends this slightly pushy style, within the 1,024-character limit.

Progressive disclosure means the agent loads a skill in three stages, and pays for the later stages only when it needs them. At start-up it reads the name and description of every installed skill. It reads the full instructions only for the skill that matches the task.

Pause and predict before you read on. Your team installs 20 skills. How many full SKILL.md bodies does the agent load when someone asks it to fix a typo? The answer is usually zero, because no description matches a typo fix.

The specification gives rough sizes for each stage. The name and description cost about 100 tokens per skill. It recommends keeping the body under 5,000 tokens and the main SKILL.md under 500 lines. Extra files load only when needed, so a long reference costs nothing until a step asks for it.

Think of a hotel front desk with a folder of how-to sheets. The receptionist knows every sheet's title by heart, which is the catalog. A guest asks for an airport cab, so the receptionist pulls out that one sheet, which is the body. The sheet says to ring the cab desk, which is the script.

Where the picture breaks: a receptionist reliably picks the right sheet. An agent picks by reading descriptions, and it can miss or choose wrongly. Its choice also varies from run to run, which is why later sections test triggering more than once.

One more detail matters for long chats. When an agent tool trims old messages to save space, skill instructions can be lost without any error. The client guide on the specification site advises agent tools to protect loaded skill content from that trimming.

A skill teaches the agent how to do a job, while the others give it standing rules, actions or facts. They work together, and a real agent often uses all four in one task.

MCP, the Model Context Protocol, is an open protocol through which a server offers tools to an agent. Each tool has a name, a description and a JSON Schema, a machine-readable description of its inputs. The protocol's tools page says so in version 2026-07-28, current as of 23 October 2026. A tool answers "what can I do?" while a skill answers "how should I do this job here?"

RAG, short for retrieval-augmented generation, searches a store of documents and adds the best matches to the prompt. It suits questions of fact. A skill is different because the author picks the content, and the agent follows it as steps rather than quoting it.

A system prompt is the closest cousin, and the difference is lifecycle. A system prompt is always on, so every line costs tokens on every request. A skill sits in its own folder, has its own version and its own tests, and loads only on a match.

Use a skill when the same multi-step job repeats and the agent keeps getting a step wrong without help. Skip it when one sentence of guidance or one tool call would do.

Good signs that a skill will help:

• The job has a fixed order of steps, such as a release, a migration or an incident write-up.
• Your team keeps correcting the agent in the same way. Those corrections become a gotchas list.
• Every run, the agent writes the same helper code from scratch. That code belongs in scripts.
• The procedure is long, but only some tasks need it, so it should not sit in the system prompt.

Signs that something else fits better:

• The rule applies to every request, such as a tone or a safety rule. Put it in the system prompt.
• The agent needs a new action, such as calling your billing API. Build a tool.
• The agent needs fresh facts from many documents. Use retrieval.
• The agent already does the job well without help. The best-practices guide warns that such a skill may add nothing.

Scope matters too. The best-practices guide compares a skill to a function: one coherent unit of work. Too narrow, and several skills must load for one task. Too broad, and the description cannot trigger precisely.

Make a folder, write SKILL.md, add any script the steps need, then run the reference validator until it prints a success line. The steps below are the exact ones we ran on 23 October 2026.

1. 1

   Create the folder

   Make a folder called release-notes. The folder name must match the name field exactly, or validation fails.

2. 2

   Write SKILL.md

   Add the frontmatter and the body shown earlier. Keep the steps short and put the gotchas where the agent reads them before it acts.

3. 3

   Bundle the script

   Save the grouping code as scripts/group_commits.py. Paths in SKILL.md are relative to the skill folder.

4. 4

   Add the template and style notes

   Put the fill-in template in assets and the wording rules in references. Step 4 and step 5 point to them.

5. 5

   Install the reference validator

   Create a virtual environment with Python 3.11 or newer and run pip install skills-ref==0.1.1. Pin the version, because this is an alpha package.

6. 6

   Validate

   Run agentskills validate release-notes. Expect the line Valid skill: release-notes and an exit code of 0.

7. 7

   Try the steps by hand

   Run the git and script commands yourself before any agent does. If they fail for you, they will fail for the agent.

The bundled script

The script reads one commit subject per line, drops housekeeping commits and prints groups as JSON. Structured output suits agents, because the agent can read it without guessing where each field ends.

"""Group commit subjects by type. Reads one subject per line on stdin, prints JSON."""
import json
import sys

KEEP = {"feat": "Features", "fix": "Bug fixes", "perf": "Performance"}
SKIP = {"chore", "ci", "docs", "test"}


def group(lines):
    groups = {"Breaking changes": [], "Features": [], "Bug fixes": [], "Performance": [], "Other": []}
    for line in lines:
        line = line.strip()
        if not line:
            continue
        head, sep, text = line.partition(":")
        if not sep:
            groups["Other"].append(line)
            continue
        kind = head.split("(")[0].rstrip("!")
        if head.endswith("!"):
            groups["Breaking changes"].append(text.strip())
        elif kind in SKIP:
            continue
        elif kind in KEEP:
            groups[KEEP[kind]].append(text.strip())
        else:
            groups["Other"].append(line)
    return {k: v for k, v in groups.items() if v}


if __name__ == "__main__":
    if sys.stdin.isatty():
        sys.exit("Error: pipe commit subjects into this script, one per line.")
    print(json.dumps(group(sys.stdin.readlines()), indent=2))

We fed it four commits made after tag v1.0.0 in a throwaway repository. Here is the exact pipe and its output, with each list squeezed onto one line.

git log v1.0.0..HEAD --pretty=format:%s | python3 scripts/group_commits.py

{
  "Breaking changes": ["drop v1 login endpoint"],
  "Features": ["add CSV export"],
  "Bug fixes": ["handle empty cart"]
}

What just happened? The chore commit vanished, the commit marked feat! moved to breaking changes and the rest sorted by type. A breaking change is kept even on a skipped type: we checked that chore!: drop Python 3.8 support still lands under breaking changes. The agent no longer decides these rules each time. The script makes them the same on every run.

What the validator prints

pip install skills-ref==0.1.1
agentskills --version
# agentskills, version 0.1.1

agentskills validate release-notes
# Valid skill: release-notes

# Same skill copied into a folder called notes
agentskills validate notes
# Validation failed for notes:
#   - Directory name 'notes' must match skill name 'release-notes'

A failing check exits with code 1, so you can run the validator in a CI pipeline, the checks that run on every pull request. The release-notes skill then stays valid as people edit it.

It checks that SKILL.md exists, that its frontmatter is valid and that the folder name matches. It reads nothing else. We ran 16 cases against skills-ref 0.1.1, the reference library linked from the specification, on Python 3.13 on 23 October 2026.

Three gaps between the documents and the tool are worth knowing, as of 23 October 2026. The specification page explains none of them, so pin your version.

• The command name differs. The specification page shows skills-ref validate, but the 0.1.1 package from PyPI installs a command called agentskills.
• The name rule is ambiguous. The specification says unicode lowercase alphanumeric characters, then lists only a to z and 0 to 9. Version 0.1.1 takes the Unicode reading and accepts café, so stick to a to z, digits and hyphens.
• Agent tools may be gentler than the validator. The client guide suggests a tool should warn and still load a skill whose name breaks the rules.

The same library can also build the start-up catalog. This short program, which we ran, mimics stages 1 and 2 of progressive disclosure. We put release-notes and a deliberately broken skill called Bad-Name inside a folder called skills. It skips invalid skills, keeps only names and descriptions, then reads one full body.

from pathlib import Path

from skills_ref import read_properties, validate

skills_root = Path("skills")

# Tier 1: at startup, keep only name and description for every skill.
catalog = {}
for folder in sorted(p for p in skills_root.iterdir() if p.is_dir()):
    problems = validate(folder)
    if problems:
        print("skipped", folder.name, problems)
        continue
    props = read_properties(folder)
    catalog[props.name] = {"description": props.description, "path": folder / "SKILL.md"}

for name, entry in catalog.items():
    print(name, "-", len(entry["description"]), "characters in the catalog")

# Tier 2: only when a task matches, read the full SKILL.md.
chosen = "release-notes"
body = catalog[chosen]["path"].read_text(encoding="utf-8")
print(chosen, "loaded:", len(body.splitlines()), "lines")

skipped Bad-Name ["Skill name 'Bad-Name' must be lowercase"]
release-notes - 196 characters in the catalog
release-notes loaded: 22 lines

Because a skill can tell an agent to run its scripts, so installing a skill is close to installing software. A passing validator only means the frontmatter is tidy. Our test showed it never opens the scripts folder.

There is a quieter risk too. The body of SKILL.md is instructions that land in the agent's context. The client guide warns that project skills may come from an untrusted repository, such as a freshly cloned open-source project. It suggests loading them only when the user has marked the folder as trusted.

Before you install or merge a skill, check these points:

• Read every script, as you would read a pull request. Look for network calls, file deletes and anything that reads secrets.
• Read the body for instructions that widen the job, such as "also upload the repository" or "ignore earlier rules".
• Check the allowed-tools field, if present. It pre-approves tools, so keep the list as small as the job needs.
• Pin versions of any package a step installs, such as npx [email protected] rather than a bare name.
• Keep skills in version control, with a named owner in metadata and a review on every change.

Tool permissions still matter while a skill runs. The MCP tools page says a human should be able to deny tool calls, and clients should confirm sensitive operations. A skill does not remove that need. It only tells the agent which tools to reach for.

Run two kinds of test: trigger tests that check the agent loads the skill at the right times, and output tests that check the result beats working without the skill. The specification site publishes a guide for each.

Trigger tests

Write about 20 realistic requests: 8 to 10 that should load the skill and 8 to 10 that should not. The most useful negatives are near-misses that share words with the skill but need something else.

• Should trigger: "what went out since v2.3? boss wants a summary for the client".
• Should trigger: "draft the changelog for tomorrow's release".
• Should not trigger: "fix the typo in CHANGELOG.md line 12". It shares a word but is a one-line edit.
• Should not trigger: "tag this commit as v2.4.0". It touches releases but needs no notes.

Model behaviour varies between runs, so run each request about 3 times and count the trigger rate. A should-trigger request passes if it triggers in more than half its runs, the guide's suggested 0.5 threshold. A should-not-trigger request passes if it triggers in fewer than half. Hold back about 40 percent of the requests as a validation set, so you do not tune the description to the exact wording of the rest.

Output tests

Store a few test cases in evals/evals.json inside the skill folder. Each has a prompt, a plain description of a good result and optional input files. Run each case twice: once with the skill and once without, in a fresh session each time.

{
  "skill_name": "release-notes",
  "evals": [
    {
      "id": 1,
      "prompt": "Write release notes for everything since v1.0.0",
      "expected_output": "Notes with breaking changes first and no chore commits",
      "assertions": [
        "The breaking change about the v1 login endpoint is listed first",
        "No line mentions bumping dependencies"
      ]
    }
  ]
}

Assertions are checks you can judge from the output alone. The guide suggests adding them after your first run, once you have seen real output. Grade each one pass or fail with evidence, using a script where you can. Then compare pass rate, time and tokens between the two runs.

The evaluation guide's own sample shows how to read the result. A skill that adds 13 seconds but raises the pass rate by 50 points is probably worth it. One that doubles tokens for a 2-point gain might not be. Drop assertions that pass in both runs, because they prove nothing about the skill.

Frame skills as a packaging and loading problem: how an agent finds the right procedure without paying for every procedure on every request. Walk through it in this order.

1. 1

   State the problem

   Teams repeat multi-step procedures, and pasting them into prompts wastes tokens and drifts between copies.

2. 2

   Define the package

   One folder per procedure, a SKILL.md with name and description, plus optional scripts, references and assets.

3. 3

   Explain loading

   Catalog of names and descriptions at start-up, full body on a match, extra files only when a step needs them.

4. 4

   Place it among other parts

   System prompt for standing rules, tools or MCP servers for actions, retrieval for facts, skills for procedures.

5. 5

   Cover trust

   Treat skills as code: review scripts, gate untrusted project skills, keep tool approval and pin dependencies.

6. 6

   Cover testing

   Trigger tests with near-miss negatives and repeated runs, plus with-skill and without-skill output tests.

7. 7

   Name failure modes

   The skill never triggers, triggers on the wrong task, conflicts with another skill or is dropped when old context is trimmed.