# SKILL.md: the file that teaches an agent a procedure

> Canonical: https://auxfirst.com/news/skill-md-agent-skills.html
> Markdown representation of this article, for agents and LLM crawlers.

What a SKILL.md is, how the Agent Skills format works (frontmatter, body, bundled files, progressive disclosure), the fields Claude Code adds, where skills live, the writing rules that hold, and a template.

By Emil Krzemiński, founder of auxfirst. Published 26 October 2026.

Every context file in the MD series so far has described a *place*: a repository, a brand, a website. `SKILL.md` is the one that describes a *procedure*, and that single difference changes everything about how it is written, when it loads, and what it can do. It is also the only one of the family that routinely carries executable code, which is why the last section of this piece is about security rather than style.

> **In one paragraph**
>
> An Agent Skill is a folder with a `SKILL.md` at its root. The file opens with YAML frontmatter holding a `name` and a `description`, then gives Markdown instructions; the folder may also hold scripts, reference documents and templates. An agent loads only every skill’s name and description at startup, reads the body of one when a task matches its description, and opens the other files only if the instructions point it there. The format was published by Anthropic in October 2025, released as an open standard in December 2025, and is read by Claude.ai, Claude Code, the Claude API and a growing list of other agent products.

## What a SKILL.md is

The specification is short enough to quote in structure. A skill is a directory. At minimum it contains one file, `SKILL.md`, and that file must contain YAML frontmatter followed by Markdown content. The frontmatter needs two fields: a `name` and a `description`. Everything else is optional, including the body, though a skill without a body does nothing. [1]

Anthropic introduced the format on 16 October 2025 with an engineering note that compared building a skill to writing an onboarding guide for a new hire: instead of building a custom agent for each use case, you capture the procedural knowledge once and let a general agent load it when needed. [3] On 18 December 2025 the format was released as an open standard at agentskills.io, with the stated aim of cross-platform portability, and the specification now describes the format as adopted by a growing number of agent products beyond Anthropic’s own. [1][2]

The claim to keep in mind is the modest one. A skill does not make an agent smarter. It gives a capable agent the context it would otherwise lack: your process, your conventions, your scripts, your edge cases. The authoring guidance says this plainly: the default assumption is that the model is already very smart, so add only what it does not already have. [4]

## Why it is not AGENTS.md

This is the confusion that costs people the most, because `SKILL.md` looks like a sibling of [AGENTS.md](https://auxfirst.com/news/agents-md-for-non-engineering-teams.html) and [CLAUDE.md](https://auxfirst.com/news/claude-md-best-practices.html) and is not one.

A workspace file describes a place and loads in every session: where the material lives, how work is done here, what must pass, what must not be touched. A skill describes how to do one kind of work and loads only when that work comes up. Claude Code’s own guidance is to reach for a skill “when a section of CLAUDE.md has grown into a procedure rather than a fact”, and the memory documentation puts the same rule the other way round: keep `CLAUDE.md` to facts the agent should hold every session, and move anything that is a multi-step procedure into a skill. [6]

The test is simple. If the sentence you are writing would be true whatever the agent was doing today, it is a fact about the workspace. If it only matters when the agent is doing a particular kind of task, it is a step in a procedure. Facts go in the workspace file. Procedures go in a skill, where they cost nothing until they are needed.

*Figure 1 · Place versus procedure · Three files, two jobs, one that loads on demand.* AGENTS.md and CLAUDE.md describe a workspace and load in every session. SKILL.md describes a procedure: at startup only its name and description load; the body loads when a task matches; bundled files load only when the instructions point to them. The question to ask of every line: would this be true whatever the agent was doing today? Yes: workspace file. No: it is a step in a procedure, and it belongs in a skill.

## The anatomy, field by field

A skill directory, with the conventions the specification recommends for the optional parts: [1]

```
skill-name/
├── SKILL.md        # required: frontmatter + instructions
├── scripts/        # optional: code the agent runs
├── references/     # optional: documents the agent reads when needed
├── assets/         # optional: templates, images, data files
└── ...             # anything else
```

The frontmatter fields defined by the specification:

| Field | Status | Rules |
|---|---|---|
| name | required | 1–64 characters; lowercase letters, numbers and hyphens only; no leading, trailing or consecutive hyphens; must match the parent directory name. |
| description | required | 1–1,024 characters, non-empty. Says what the skill does *and* when to use it, with the keywords an agent would match against a task. |
| license | optional | A license name, or the name of a bundled license file. Keep it short. |
| compatibility | optional | Up to 500 characters. Only when the skill has environment requirements: an intended product, system packages, network access. Most skills do not need it. |
| metadata | optional | A map of string keys to string values for anything the specification does not define. Use distinctive key names to avoid collisions. |
| allowed-tools | optional | A space-separated string of tools pre-approved for the skill. Marked experimental; support varies between agents. |

The body has no format restrictions. The specification recommends step-by-step instructions, examples of inputs and outputs, and common edge cases, and notes that the agent loads the entire file once it decides to activate the skill, which is the reason to split long content into referenced files. [1] File references use relative paths from the skill root and should stay one level deep: `SKILL.md` points to `references/REFERENCE.md`, and `REFERENCE.md` does not point onward to a third file, because an agent following a chain of references tends to preview rather than read. [1][4]

Anthropic’s authoring guidance adds two constraints the open specification does not: a name may not contain the reserved words “anthropic” or “claude”, and neither field may contain XML tags. [4] The specification ships a reference validator, `skills-ref validate ./my-skill`, that checks the frontmatter and naming rules. [1]

## Progressive disclosure

The design principle that makes the format work is that an agent never loads a whole skill. It loads in three stages, each only when the previous one justified it: [1][2][3]

*Figure 2 · Three levels of disclosure · What is in the context window, and when.* Level one, at startup: the name and description of every installed skill, about 100 tokens each. Level two, on activation: the full SKILL.md body, recommended under 5,000 tokens and 500 lines. Level three, as needed: scripts run without being read, references read on demand, assets used when required. Context cost rises from left to right; frequency of loading falls. Figures from the specification. A script in `scripts/` is the cheapest thing in a skill: the agent runs it and reads only its output, so the code itself never enters the context window.

Two consequences follow that are easy to miss. First, the amount of material you can bundle is effectively unbounded, because a reference document costs nothing until it is opened; the engineering note makes exactly this point about agents that have a filesystem. [3] Second, the budget that matters is level two. The `SKILL.md` body loads whole, into a context window that already holds the system prompt, the conversation and the user’s request, and every token in it competes with those. The authoring guidance calls the context window “a public good” for this reason. [4]

## The description is the trigger

At level one the agent sees nothing but names and descriptions, possibly a hundred of them, and chooses from those. The description is therefore the entire triggering mechanism, and the guidance on writing it is specific: [4]

- **Say what it does and when to use it.** “Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.” The second sentence is the half people leave out, and it is the half that triggers.
- **Third person, always.** The description is injected into the system prompt. “Processes Excel files”, not “I can help you” or “You can use this to”; a shift in point of view is enough to break discovery.
- **Include the words a user would say.** Not the words you would use to describe the category.
- **One description per skill.** Vague ones (“Helps with documents”, “Processes data”) do not fail loudly. They fail by never being chosen.

Claude Code adds an optional `when_to_use` field that it appends to the description in its listing, with trigger phrases or example requests, and truncates the combined text at 1,536 characters, so the key use case goes first. [5] Whatever the agent, test the trigger rather than trusting it: the authoring guidance asks for at least three evaluation scenarios per skill, built before the documentation is written, because a description that never fires is indistinguishable from a skill that does not exist. [4]

## What Claude Code adds, and what does not travel

Claude Code reads every field in the specification and a set of its own. The ones that change how a skill behaves: [5]

| Field | What it does | Use it for |
|---|---|---|
| disable-model-invocation | Set to `true`: the agent cannot load the skill on its own; only `/name` runs it. | Anything with side effects, where you decide the timing: deploy, commit, send. |
| user-invocable | Set to `false`: hidden from the `/` menu; only the agent invokes it. | Background knowledge that is not an action a person would take. |
| allowed-tools | Tools the agent may use without asking during the turn that invokes the skill. | Letting a bundled script run without a permission prompt. |
| disallowed-tools | Tools removed from the agent’s pool while the skill is active. | Autonomous skills that must never ask a question or end the conversation. |
| context: fork | Runs the skill in its own subagent context, in the background by default. | Long procedures that should not fill the main conversation. |
| paths | Glob patterns; the skill loads automatically only when the agent works on matching files. | Procedures that belong to one part of a codebase. |
| hooks | Hooks registered when the skill is invoked and kept for the rest of the session. | Checks that must run after every edit the skill makes. |
| model, effort | Override the model or effort level for the rest of the turn. | Skills that need more or less reasoning than the session default. |

Two details are worth knowing. In Claude Code every field is optional, `name` defaults to the directory name, and a field it does not recognize is ignored without an error, so a typo in a field name fails silently. [5] And a line of the form `!`git diff HEAD`` in the body is dynamic context injection: the command runs and its output replaces the line before the agent reads the skill, so the instructions arrive with the live state already inlined. [5]

> **What does not travel**
>
> Outside Claude Code, only the specification’s fields are allowed: `name`, `description`, `license`, `compatibility`, `metadata` and `allowed-tools`. Upload a skill that uses `argument-hint` or `disable-model-invocation` to claude.ai or the Skills API, or package it with Anthropic’s packaging script, and it fails with a hard error naming the unexpected key. [5] If a skill is meant to be portable, write it to the specification and keep the Claude Code extras for skills that will only ever live in a Claude Code project.

## Where skills live

Where the folder sits decides which sessions load it. For Claude Code: [5]

| Scope | Path | Loads in |
|---|---|---|
| Enterprise | `.claude/skills//SKILL.md` in the managed settings directory | Every user on machines where the organization deploys it. |
| Personal | `~/.claude/skills//SKILL.md` | All your projects on this machine. |
| Project | `.claude/skills//SKILL.md` | Sessions in this repository. Commit it so the team gets it. |
| Nested | `/.claude/skills//SKILL.md` | Sessions started in or below that directory; a session started above it loads the skill once it works on files there. |
| Plugin | `

/skills//SKILL.md` | Wherever the plugin is enabled, as `/plugin-name:skill-name`. | | claude.ai account | Uploaded to claude.ai | Cowork, cloud and signed-in terminal sessions. | Other agents that read the format have their own locations; the specification deliberately does not define one. What it does define is the portable unit, the folder, which is why a skill written to the specification can be moved between products by copying a directory. [1][2]

## Writing rules that hold

Anthropic’s authoring guide is long and most of it is examples. The rules underneath it, in the order they tend to matter: [4]

### 01 · Assume a capable reader

*Only add what the agent does not already know.* Challenge every paragraph: does the agent really need this explanation? The guide’s own example cuts a 150-token explanation of what a PDF is down to a 50-token instruction with a code snippet. The explanation was not wrong. It was already known.

### 02 · Match freedom to fragility

*Narrow bridge, exact instructions; open field, general direction.* A code review can be described as four loose steps because many approaches work. A database migration gets “run exactly this script, do not add flags” because only one sequence is safe. Deciding the degree of freedom is most of the design.

### 03 · One level deep

*Every reference file linked directly from SKILL.md.* An agent that reaches a file through another file tends to preview it with the first hundred lines rather than read it. Reference files longer than a hundred lines get a table of contents at the top for the same reason.

### 04 · Workflows as checklists; validators as loops

*Steps the agent can copy and tick off; a check it runs before proceeding.* For anything multi-step, give a checklist the agent can carry in its response. For anything quality-critical, write the loop explicitly: draft, validate, fix, validate again, proceed only when it passes. The validator can be a script or a style guide; what matters is that the loop is written down.

### 05 · No dates, one vocabulary, one default

*The three things that rot.* Time-sensitive instructions (“before August use the old API”) become wrong silently; put legacy patterns in a collapsed section instead. Mixed terms (“field”, “box”, “element”) read as three things. And a menu of five libraries is worse than one default with an escape hatch.

### 06 · Scripts solve, they do not defer

*Handle the error; justify the constant; say whether to run or read.* A bundled script should handle its own failure cases rather than crash and let the agent improvise, should document why a timeout is 30 and not 47, and the instructions should say whether the agent runs it or reads it as reference. Pre-written scripts are more reliable than generated code and cost no context, because only their output is read.

### 07 · Evaluate first, then write, then watch

*Three scenarios before the documentation; real tasks after it.* Run the agent on representative tasks without the skill and record where it fails. Write the minimum that fixes those failures. Then watch how the agent actually navigates the skill: files read in an unexpected order, references never followed, one file opened every time. Each is a structural signal, and the fix is usually to move content, not add it.

> *The one-line version: A skill is an onboarding guide for a colleague who is brilliant, literal, and has never seen your process.*

## A skill is a dependency with execute rights

This is where `SKILL.md` parts company with the rest of the MD series. An `AGENTS.md` or a `brand.md` is text; the worst it can carry is an instruction, which is bad enough and the subject of [its own piece](https://auxfirst.com/news/markdown-context-file-security.html). A skill carries instructions *and* code the agent runs, and Anthropic’s own note on the format says what follows from that: a malicious skill can introduce vulnerabilities into the environment where it runs, or direct the agent to exfiltrate data and take unintended actions. [3]

The recommended practice is the practice for any dependency with execute rights. Install only from sources you trust. For anything else, read every bundled file before use, with particular attention to code dependencies, bundled resources such as images and scripts, and any instruction or code that has the agent connect to an external network address. [3] Claude Code’s `allowed-tools` field makes the question sharper, because a skill can pre-approve its own script to run without a prompt; that is the right design for a trusted skill and exactly the mechanism an untrusted one would want. [5]

There is a governance point underneath the security one. A skill that only reads and summarizes is a different object from a skill that writes to a system of record, sends a message or moves money, and the difference is not in the format; it is in what the procedure does. Score the action, not the file. [The Action Heat Ladder](https://auxfirst.com/action-heat-ladder.html) exists for that, and a skill whose steps land in the hot bands needs the same mandate, supervision and evidence trail as any other agent action; the [AI agent governance](https://auxfirst.com/ai-agent-governance.html) framework says what those are.

## A template and a worked example

A minimal skill written to the specification, with the Claude Code extras left out so it travels:

```
---
name: reviewing-release-notes
description: Reviews draft release notes against the product's naming rules and claim policy, and returns a corrected draft with each change explained. Use when the user asks to check, review or tidy release notes, changelog entries or launch announcements.
license: MIT
metadata:
  owner: product-marketing
  version: "1.2"
---

# Reviewing release notes

## Steps
1. Read the draft the user supplied. Do not fetch anything else.
2. Check every product name against `references/names.md`.
3. Check every claim against `references/claims.md`. A claim not on the list is removed, not softened.
4. Return the corrected draft, then a list of changes, one line each, with the rule applied.

## Edge cases
- A feature name not in `names.md`: keep it verbatim and flag it; never guess a capitalization.
- A draft with no claims: say so and return it unchanged.

## Output
Corrected draft first, change list second, nothing else.
```

Every rule from the previous section is visible in it. The description says what and when, in the third person, with the words a user would say. The body assumes a capable reader. The references are one level deep and small. The degree of freedom is low where it must be (remove, never soften) and open where it can be. There are no dates in it.

For a skill at full size, [the auxfirst skill](https://auxfirst.com/auxfirst-skill.html) is our own: a single `SKILL.md` carrying the procedure for deciding how much autonomy an agent action may have, six reference documents loaded only when needed, three templates, one script that scores an action and returns its band, and a set of twenty trigger evaluations, because the description is the whole triggering mechanism and guessing is not a test. It is MIT-licensed and traces every claim to published auxfirst material. Read it as an example of the structure, whatever you think of the method.

Before sharing a skill, run its `SKILL.md` through the [context file checker](https://auxfirst.com/tools/context-file-checker.html). The checks that catch most skill drafts are the vague-directive one (“use your judgment” is not an instruction) and the missing done-criteria one, which is to say step four and the output section are where the work is.

## Questions people ask

### What is a SKILL.md file?

The one required file in an Agent Skill. A skill is a folder; SKILL.md sits at its root and has two parts: YAML frontmatter with at least a name and a description, and a Markdown body with the instructions. The folder can also hold scripts, reference documents and templates. An agent loads only the name and description at startup, reads the body when a task matches the description, and opens the other files only if the instructions point it there.

### How is SKILL.md different from AGENTS.md or CLAUDE.md?

AGENTS.md and CLAUDE.md describe a workspace and load in every session: conventions, commands, boundaries. A SKILL.md describes a procedure and loads only when it is used. Claude Code's own guidance is to move something into a skill when a section of CLAUDE.md has grown into a procedure rather than a fact. Facts about the place belong in the workspace file; how to do a particular kind of work belongs in a skill.

### What goes in the frontmatter?

Under the open specification: name (required, up to 64 characters, lowercase letters, numbers and hyphens, matching the folder name), description (required, up to 1,024 characters, what the skill does and when to use it), and optionally license, compatibility, metadata and allowed-tools. Claude Code accepts further fields such as disable-model-invocation, user-invocable, context, paths and hooks; those are not part of the specification, and uploading a skill that uses them to claude.ai or the Skills API fails with an error naming the unexpected key.

### How long should a SKILL.md be?

The specification recommends keeping the body under 500 lines and under roughly 5,000 tokens, and moving detail into referenced files that load only when needed. The metadata that every session carries is about 100 tokens per skill. The authoring guidance adds a sharper test: assume the model is already capable and keep only what it does not know.

### Why does the description matter so much?

Because it is the whole triggering mechanism. At startup an agent sees only names and descriptions, possibly for a hundred skills, and chooses from those. A description has to say what the skill does and when to use it, in the third person, with the terms a user would actually say. Claude Code appends an optional when_to_use field and truncates the combined text at 1,536 characters in its listing, so the key use case goes first.

### Are skills safe to install?

A skill is instructions plus, often, code that the agent runs. Anthropic's guidance is to install only from trusted sources and to read every bundled file before using one from anywhere else, paying particular attention to scripts, dependencies and anything that tells the agent to reach an external network address. Treat a skill the way you would treat a dependency with execute rights, because that is what it is.

## Read next & further reading

**The MD series**

- [CLAUDE.md best practices — what goes in, what stays out, and why most of them are too long](https://auxfirst.com/news/claude-md-best-practices.html)
- [AGENTS.md for teams that don’t write code — the workspace file, with a generator](https://auxfirst.com/news/agents-md-for-non-engineering-teams.html)
- [brand.md — brand guidelines agents can actually read](https://auxfirst.com/news/brand-md-context-file.html)
- [Prompt injection in .md context files — the risk model](https://auxfirst.com/news/markdown-context-file-security.html)
- [MD files explained — the complete .md file format guide](https://auxfirst.com/news/md-file-markdown-guide.html)
- [Markdown for AI — why .md files became the context format](https://auxfirst.com/news/markdown-for-ai.html)

**Tools**

- [The context file checker — twelve structural checks, in the browser](https://auxfirst.com/tools/context-file-checker.html)
- [The .md viewer — open and export any Markdown file, locally](https://auxfirst.com/tools/md-viewer.html)

**Where this sits in the auxfirst canon**

- [The auxfirst skill — a SKILL.md, six references, three templates, one script, twenty evals](https://auxfirst.com/auxfirst-skill.html)
- [The Action Heat Ladder — score what a procedure does, not the file it lives in](https://auxfirst.com/action-heat-ladder.html)
- [AI agent governance — the framework for agents that act](https://auxfirst.com/ai-agent-governance.html)

**Primary sources**

- [[1] Agent Skills — Specification (agentskills.io)](https://agentskills.io/specification)
- [[2] Agent Skills — Overview: what skills are and how they load](https://agentskills.io/what-are-skills)
- [[3] Anthropic Engineering — Equipping agents for the real world with Agent Skills, 16 October 2025 (open standard update, 18 December 2025)](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [[4] Claude Docs — Skill authoring best practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices)
- [[5] Claude Code Docs — Extend Claude with skills (frontmatter reference, locations, portability)](https://code.claude.com/docs/en/skills)
- [[6] Claude Code Docs — How Claude remembers your project (when to move a procedure out of CLAUDE.md)](https://code.claude.com/docs/en/memory)
- [anthropics/skills — Anthropic’s example skills, the specification and a template](https://github.com/anthropics/skills)

Method · Every field, limit and quotation was taken from the specification and Anthropic’s documentation as read on 26 October 2026, not from secondary coverage. Where Claude Code’s behavior differs from the open specification we have said which is which. The template is ours; the worked example is our own skill and we have said so.

**Emil Krzemiński is the founder of [auxfirst](https://auxfirst.com/index.html), the agentic experience design agency — helping product, developer and business teams design AI systems that remember, adapt, and earn the right to act. Start with [the AGENTS.md pattern](https://auxfirst.com/news/agents-md-for-non-engineering-teams.html), the [context file checker](https://auxfirst.com/tools/context-file-checker.html), or [a conversation](https://auxfirst.com/index.html#contact). For how machines read auxfirst, see the [AI info page](https://auxfirst.com/ai-info.html). Subscribe to the [auxfirst Substack](https://auxfirst.substack.com/) for what's next.**