What are Agent Skills?

An Agent Skill is a folder that teaches an AI coding agent to do something specific, well, the way you want it done. The whole format is a markdown file with a few lines of YAML at the top — which is exactly why it spread across the ecosystem so quickly.

The anatomy of a skill

One folder, one required file, and whatever supporting material the task needs:

pdf/
├── SKILL.md          ← required
├── reference.md      ← optional deep detail
├── examples/
│   └── invoice.pdf
└── scripts/
    └── fill_form.py  ← optional, the agent may run it

Only SKILL.md is mandatory. Everything else exists because the instructions in it point at them — a reference document the agent reads when it needs specifics, an example to pattern-match against, a script it can execute instead of reimplementing something fiddly.

Inside SKILL.md

A YAML frontmatter block fenced by ---, then plain markdown instructions:

---
name: pdf
description: Fill, merge and extract text from PDF files. Use when the
  user mentions PDFs, forms, or scanned documents.
license: MIT
allowed-tools:
  - Bash(python3)
  - Read
---

# Working with PDFs

When asked to fill a form, first inspect the field names:

```bash
python3 scripts/fill_form.py --inspect input.pdf
```

Then map the user's values onto those field names before writing...

The frontmatter fields

name — lowercase, hyphenated, up to 64 characters. If it is missing, the folder name is used instead.
description — up to 1024 characters, and the single most important line in the file. More on why below.
license — an SPDX identifier. Worth setting on anything you publish.
allowed-tools — which tools the skill expects to use. Agents that understand it treat it as a grant; others ignore it.
compatibility and metadata — optional portable fields for declaring what the skill assumes and carrying your own bookkeeping.

Individual agents add their own extended fields on top of these. Unknown keys are ignored rather than rejected, which is what lets one file work across tools that support different feature sets.

How an agent decides to use a skill

This is the part that determines whether your skill ever fires, and it is not obvious from looking at the format.

Agents do not load every installed skill into context. That would be ruinously expensive with more than a handful. Instead they see a list of names and descriptions — one line each — and pull in the full body of a skill only when its description matches the task at hand.

Your description is doing selection, not marketing. “Helps with documents” will lose to “Fill, merge and extract text from PDF files. Use when the user mentions PDFs, forms, or scanned documents.” Say what it does and name the situations that should trigger it.

The practical consequence: fifty installed skills cost you fifty description lines, not fifty documents. Being generous with what you install is fine. Being vague about what they do is not.

Writing a good one

Write the description last. You will understand the trigger conditions better once the instructions exist.
One skill, one job. A skill covering three loosely related tasks is a skill whose description cannot be specific, and a vague description does not get selected.
Push detail into reference files. Keep SKILL.md to the procedure, and point at a reference document for the exhaustive parts. The agent reads it when it needs it.
Prefer a script over prose when the task is deterministic. “Run this” beats twelve paragraphs describing what the script would have done.
Describe the task, not the toolbar. Instructions written against one agent’s exact affordances stop working everywhere else.

Treat installing one as installing software

A skill is instructions your agent will follow, and possibly scripts it will run with your permissions. That is the same trust decision as installing a package, except nothing about markdown signals “this is code” the way a package manager does.

Before you install one from a source you do not know, look at:

Bundled scripts — what do they actually do?
Tool grants — does a formatting skill really need shell access?
External URLs — where is it sending things, or fetching from?
Instructions aimed past you — text trying to override the agent’s other rules is a red flag, not a feature.

None of this requires paranoia, just the habit of reading before installing. It is also why Skill Installer makes the preview mandatory and surfaces those four things as flags — the flags inform, they never block, because plenty of legitimate skills ship scripts.

Next steps

Ready to install one? See how to install skills in Claude Code, or the universal directory for Cursor, Codex and others. Wondering how this relates to MCP? That comparison is here. The format itself is documented at agentskills.io.