What an Agent Skill Actually Is

A Skill is a folder with a markdown file in it. That is not a simplification — it is the whole mechanism. Everything interesting about Skills follows from the fact that the folder sits on a filesystem the model can read at its own discretion.

First in a series on Agent Skills: what they are, how they load, and how to build ones that actually fire.

The minimum viable Skill

One directory, one file:

invoice-audit/
└── SKILL.md

And the file needs exactly two things in its YAML frontmatter:

---
name: invoice-audit
description: Check supplier invoices against the PO ledger for
  duplicate numbers, VAT errors and totals that do not reconcile.
  Use when the user mentions invoices, supplier billing or an
  accounts payable review.
---

# Invoice audit

## Step 1 — locate the ledger
...

That is a working Skill. Drop it in ~/.claude/skills/ for yourself or .claude/skills/ in a project to share it with the repository, and it is available.

The part that surprises people

A Skill is not loaded because you selected it. It is loaded because the model read your request, read the one-line description, and decided the two matched.

That makes the description the entire public interface of a Skill. The body can be excellent and it will never run if the description does not say when to use it. This is why the field is specified as covering two things — what the Skill does and when it applies — and why the third article in this series is about nothing else.

The naming rules, because they bite

The name is capped at 64 characters, must be lowercase letters, numbers and hyphens only, and cannot contain the words anthropic or claude. The description is capped at 1024 characters. Neither may contain XML tags. These are validation rules, not style advice: get them wrong and the Skill does not load.

How this differs from the things it resembles

A prompt is conversation-level and one-off. You paste it, it applies to that exchange, and it is gone.

A project instruction file is always in context. That is its purpose and its cost: everything in it is paid for on every single request, whether relevant or not.

A Skill sits between the two. It is written once, stored on disk, and costs almost nothing until the moment it is relevant. That property is the entire reason to prefer it, and it is what the next article is about.

Where they live

The same folder format works across surfaces, but distribution does not follow it. In a coding agent, Skills are filesystem-based: personal or per-project, and shareable through plugins. Through the API they are uploaded and shared workspace-wide. In the chat app they are uploaded as a zip and are individual to each user.

Worth knowing before you plan a rollout: Skills do not sync between these surfaces. A Skill uploaded in one place is not available in the others. If your team needs the same capability everywhere, it has to be published to each one.

One caution before you install anything

A Skill is instructions plus executable code that an agent will follow and run. Treat installing one exactly as you would treat installing a package: read what is in it. A Skill that fetches from an external URL is importing whatever that URL decides to say today. The advice from Anthropic is blunt on this point, and it is right — use Skills from sources you trust, and audit the rest.

What to take away

A Skill is a folder, a markdown file, and two required fields. The description decides whether it is ever used. Everything else in this series is about the consequences of those three facts.

Next: the three levels a Skill loads in, and why a large Skill can cost you almost nothing.