What Are Agent Skills? A Plain Guide to SKILL.md

An agent skill is a folder of instructions that an AI agent loads only when it needs them. It contains a file called SKILL.md, and usually a few reference documents, templates, or scripts beside it. You install it once, and from then on your agent knows how to do a specific job the way you want it done.

The short version

A skill is a folder, not a setting, a subscription, or a model.
Your agent keeps only a one-line description in mind, and opens the full instructions when your request matches it.
A skill carries know-how. An MCP server carries access. They solve different problems.
Skills are plain text files, so you can read them, diff them, and put them in version control.
When something goes wrong, you can open the file and see why.

What is inside a skill

Here is a real one — story-first-deck, a Skill that turns an outline into a presentation:

story-first-deck/
├── SKILL.md                  the instructions
├── references/
│   └── workflow.md           detail the agent reads only when needed
├── skill-manifest.json       metadata: version, output type, dependencies
└── LICENSE.md

SKILL.md opens with a short block of frontmatter and then plain prose:

---
name: story-first-deck
description: Build a story-first presentation by choosing the right
  production lane: native PPTX, HTML, image-first, or carousel.
---

# Story-first Deck

Build a story-first presentation by choosing the right production lane…

That is the whole format. Two fields and a body. Nothing is compiled, nothing runs in the background, and there is no plugin API to learn.

Skills can carry more when the job needs it. One of the Skills we use internally to deploy this site has a scripts/ folder holding the script the agent runs, and an agents/ folder holding per-agent configuration. But the floor is one file.

How your agent decides to use one

This is the part that surprises people, and it explains most of what feels strange about skills.

Your agent does not read every installed skill on every message. It keeps only the description line in view. When your request looks like a match for that line, it opens the full SKILL.md and follows it.

Two consequences follow:

The description does the matching. A skill with a vague description gets skipped even when it is exactly the right tool. If an installed skill never seems to fire, the description is the first thing to look at — not the instructions.

More skills is not better. Every installed skill puts its description in front of your agent on every turn. Ten well-chosen skills work better than sixty, because your agent has less to sort through before it starts.

Skills, prompts, MCP servers and plugins

These four get confused constantly. They sit at different layers:

	Solves	Lives as	Reach for it when
Prompt	Saying what you want, once	A message in the chat	You are doing this one time
Agent skill	Fixing how something gets done, repeatably	A folder with `SKILL.md`	You make the same kind of thing often, to a standard
MCP server	Reaching data and systems outside the chat	A running service	The agent needs your database, an API, your files
Plugin	Changing the host app itself	A host-specific package	You need the tool to behave differently

The useful distinction is know-how versus access. A skill teaches your agent how to build a deck the way you like decks built. An MCP server lets it reach the numbers that go on slide seven. Wanting both is normal; they are not substitutes.

When a skill is worth installing

Worth it:

You produce the same kind of output repeatedly — decks, article images, landing pages, reports.
You have a standard in your head that you keep re-explaining.
The work takes several steps in a particular order.
The output has a format someone else has to accept.

Not worth it:

A genuine one-off. Write a prompt.
Work where the requirements change completely every time.
Anything whose real problem is access to data. That is an MCP server.

The honest test: if you have explained the same preferences to an AI three times, that is a skill.

Where skills come from

There are open collections on GitHub you can clone, and vendors publishing their own. The quality range is wide, and there is no built-in way to tell a skill that has been tested from one that was written in an afternoon and never run again.

That gap is the reason Skillry exists. Every Skill in our catalog is packaged and shows real output. When we have run it in a supported agent, its page also shows a Last tested date and the agents we actually used. You can browse the catalog and inspect the result before installing anything.

Questions people ask

Is an agent skill the same as a Claude Skill? Claude Skills are the most widely used implementation of this format. The folder-and-SKILL.md structure is open, so other agents read the same files. See our guide on using skills in Codex and Cursor.

Do I need to know how to code? No. Installing a skill means putting a folder where your agent looks for skills. Using it means describing what you want in ordinary language.

Do skills cost anything to run? The skill itself is text. Cost comes from the model calls your agent makes, plus any outside service the skill calls — image or video generation, for instance. A well-written skill tells you which upfront.

Can a skill do something harmful? A skill is instructions, and some ship scripts that run on your machine. Read SKILL.md before installing and inspect anything in scripts/. An install flow should never ask you to paste an API key or password. A runtime dependency may require its own credential, but the Skill should name it clearly and tell you how to store it safely.

How many should I install? Fewer than you would guess. Install what you actually use, and delete the rest.

How do I update one? Replace the folder with the newer version and start a fresh session. Skills that publish a changelog are worth reading first.

Now that you know what one is, install your first skill — it takes about two minutes.