# 16.1 From a prompt you repeat to a skill (/building-ai-workers/skills-and-plugins/from-a-prompt-to-a-skill) --- type: Document title: "16.1 From a prompt you repeat to a skill" description: "Work you keep explaining becomes a skill: a folder with a SKILL.md and supporting files, taught through the Agent Skills specification and its three stages of loading." status: stable order: 316.01 ksor: owner: team:panaversity audience: [ public ] approval: by: process:panaversity at: 2026-11-02T19:44:48Z chapter: "16" part: III expert_status: co-build concepts: [ "16.1" ] last_verified: 2026-11-02 generated: at: 2026-11-02T19:44:48Z by: esl-rewrite/1.2.0+ksor.1 trust_tier: unverified build_id: sha256:e1fbcb7d9a8f8b9b7cb96875022325c02c9ba4be94cef13b301cbd39a9edad85 dirty: true ksor_version: 0.0.60 --- **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. ```text 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](both-ai-vendors.md) 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: | Field | Required | Rules | | --- | --- | --- | | `name` | Yes | 1 to 64 lowercase letters, digits and hyphens, no hyphen at the start or end, no `--`, and the same as the folder's name | | `description` | Yes | 1 to 1,024 characters. What the skill does and when to use it | | `license` | No | A license name or a bundled license file | | `compatibility` | No | Up to 500 characters on what the skill needs, such as a language or no network | | `metadata` | No | Extra labels, each a name with a text value | | `allowed-tools` | No | Tools the skill may use without asking. Marked experimental, and products differ | ### 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](writing-a-skill-with-the-expert.md)). ![Three stages of loading. On the left, a column of skill names and one-line descriptions marked always visible, about 100 tokens each. In the middle, one skill's full instructions marked loaded when used. On the right, a references file and a script, marked read or run only when needed.](img/progressive-disclosure.png) *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](../agentic-coding/rules-the-agent-reads.md)'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](installing-is-a-trust-decision.md)). ### 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](both-ai-vendors.md#practice-from-a-prompt-to-a-skill), in your own tool, fifteen minutes.