The good news about agent skills is that there is almost nothing to learn. A skill is a folder. Inside it lives a SKILL.md file: a little YAML frontmatter and some markdown. That's the whole format, and its deliberate smallness is most of why Anthropic's reference repository has cleared 159,000 stars. You can ship your first skill in the time it takes to read this piece.

The bad news is that the one part that looks trivial — a single sentence of frontmatter — is the part that decides whether your skill ever runs. Let's build one correctly, install it, publish it, and spend our real attention where it pays.

The anatomy#

Here is a complete, working skill:

my-csv-cleaner/
└── SKILL.md
---
name: csv-cleaner
description: Use when the user asks to clean, validate, dedupe, or reshape a CSV or Excel file. Covers header normalization, type coercion, and null handling.
---

# CSV Cleaner

When cleaning tabular data:
1. Infer and normalize headers to snake_case; report any renames.
2. Coerce obvious types (dates, numbers) and flag values that resist coercion.
3. Report row counts before/after any dedupe, and never drop rows silently.
...

Two required fields, name and description, then instructions. You can add bundled scripts and resource files for the model to call or read, but you don't have to — plenty of the most useful skills are pure prose.

The description is the retrieval query, not the docs#

Now the lever nobody tells you about. When a model decides whether to use a skill, it does not read the instructions first. It reads only the name and description, matches them against what the user is currently doing, and loads the body only if that matches. The description isn't documentation for humans skimming a registry — it's the query your skill has to win.

A skill with immaculate instructions and a lazy description is a book with a great story and no title on the spine. Nobody pulls it off the shelf.

This changes how you write that one line. The instinct is to describe the feature ("A powerful tool for data tasks"). The correct move is to describe the trigger — the concrete situations, in language resembling how a user would phrase them, where this skill should fire. "Use when the user asks to clean, validate, or reshape a CSV or Excel file" will match real requests. "Data utilities" will not. When a skill mysteriously never activates, the description is the bug ninety percent of the time.

Installing#

Installation has settled into two lanes.

Publishing#

To publish, you make the folder reachable and discoverable:

  1. Put it in a repo. A public GitHub repo with your skill folder(s) is the baseline unit of distribution; the plugin-marketplace flow points directly at owner/repo.
  2. Write the description as SEO for a model. Same principle as above, now aimed at every user whose task should match. Name the trigger conditions explicitly.
  3. Version it, and mean it. Tag releases and encourage installers to pin. A skill can be poisoned or degraded in an update exactly like a package; a moving tag is a standing invitation.
  4. Conform to the spec at agentskills.io so your skill loads across the tools that implement it, not just the one you tested in.

The format is small on purpose so that the interesting work moves elsewhere — into writing instructions a model follows reliably, and into the one sentence that decides whether it ever gets the chance. Get the description right and the rest is markdown.

Companion piece: before you install anything from an open registry, read why agent skills are a supply-chain problem →