Lesson 16.116.1 From a prompt you repeat to a skill

In everyday life. A restaurant does not explain its own salad dressing to every new cook. It keeps a recipe card in a notebook. The notebook's tabs say what each card is for, so a cook finds the right one in seconds without reading them all. The card gives the steps. Anything long, such as the supplier's allergy sheet, is clipped behind it and read only when needed.

What you will learn. How to turn work you keep explaining into a folder that an agent loads only when it has that work to do. What the folder's main file may hold. How a standard keeps it working across products.

Why it matters. A procedure kept in private prompts drifts, and nothing says which copy is current. Written once, to a standard, it is kept in one place that many products can read.

What is a skill?

A skill is a recipe card for an agent. It is a folder that teaches an agent one procedure: what the work is, the steps, what to check, what never to do.

invoice-triage/
├── SKILL.md          required: frontmatter, then the instructions
├── scripts/          optional: code the agent runs
├── references/       optional: documents it reads when needed
└── assets/           optional: templates and data files

Why does a standard define it?

So a skill written once works in any product that follows the standard. Until recently, every AI product had its own way to package instructions and tools. That is changing. An open standard is a public specification, a document that says exactly what a valid file looks like. Anyone may implement it, which means build it into a product, and it is developed in public. A product that follows a specification is said to conform to it.

The Agent Skills specification (agentskills.io, checked November 2, 2026) defines the skill folder. Where a standard covers an idea, this chapter teaches the standard itself: its fields, its rules and what it leaves out. Some ideas have no standard yet, such as who may start a command or where people find plugins. For those, the chapter teaches the idea in plain words and says that no shared standard exists. Standards change too, so each one is named with the date it was checked, and with its version where it has one. 16.10 then says how each product carries out each standard, and where it differs.

What goes in the file?

SKILL.md starts with frontmatter, a short block of settings between two --- lines, written in a plain format called YAML. The instructions follow, in Markdown. The specification allows exactly six frontmatter fields:

How does an agent find the right skill without reading them all?

In three stages. An agent cannot read every skill on every turn. The specification calls its answer progressive disclosure: show a little, then more only when needed.

1. Always: the name and description of every skill, about 100 tokens each. This is how the agent knows a skill exists.
2. When used: the body of SKILL.md. The specification recommends under 5,000 tokens and under 500 lines.
3. When needed: a file from references/ or assets/, or a script run from scripts/. A script is usually run rather than read, so its code stays out of the agent's context unless the agent opens it.

So a library of fifty skills costs about fifty short descriptions until one is needed. That is why the description matters more than any other line. With the name, it is all the agent sees before it decides to load the skill (16.3).

Figure 16.3. An agent sees every skill's name and description. It loads a skill's body only when the work matches, and its files only when a step needs them.

Is a skill the same as the rules file?

No. A skill is a procedure. The rules file holds facts. Chapter 12's project rules file says what is always true here: how to run the tests, never edit data/. A skill says how to do one job, step by step, and loads only for that job. If a section of your rules file has become a procedure, it belongs in a skill.

What can a skill do by itself?

Nothing. A skill's instructions are plain text you can read. They are not a program, and they have no power of their own. They can tell an agent to run a script. What the agent may then do is set by the product's permissions, not by the skill's words (16.9).

How do I check a skill?

With a program, because the rules are written down. The standard's own validator, a program that checks a file against the rules, is skills-ref validate. It checks the frontmatter and the naming rules.

At work. Every Monday, Brightline's AP clerk pastes the same paragraph into a chat: "Here are this week's invoices. Flag any vendor we don't know, any duplicate, any terms that don't match, anything over the controller's limit, and anything due this week." Each clerk's paragraph is slightly different, and one still says the limit is $10,000, the limit before September's policy. Ana asks for one skill instead. Its description tells the agent when to use it. Its body holds the steps. Ana's rules sheet goes in references/, and the script that sorts, or triages, the invoices goes in scripts/. Brightline already has one small skill, /due-by-friday, in the repository.

The operating rule: when you paste the same instructions a third time, write a skill. Keep the description short and specific, the steps in the body, and anything long in a supporting file.

Practice it. Practice: from a prompt to a skill, in your own tool, fifteen minutes.