Primer
What is an agent skill?
A skill is a folder of instructions an AI agent loads on demand. It is not a plugin, not a prompt you paste, and not a model. It is the file where someone writes down how a job should be done — and the agent reads it only when that job comes up.
A folder with one required file
A skill is a directory containing SKILL.md, with a short YAML header
(name, description) and then the instructions. Optional folders
hold scripts, reference documents and templates the agent can load later. The format was
developed by Anthropic, released as an open standard, and is now supported by a long list of
clients — Claude Code, Cursor, Codex, GitHub Copilot, Gemini, Windsurf, Zed and more.
How it loads: three stages
- Discovery. At startup an agent sees only each skill's name and description — a few lines, not the whole file.
- Activation. When your request matches the description, the agent reads the full instructions.
- Execution. It follows them, loading bundled reference files or running scripts only if the job needs them.
This is why the description matters as much as the content: it is the routing rule. A skill with a vague description never gets loaded, no matter how good the file is.
How you install one
Skills live in the project they describe. The skills CLI from Vercel installs a
repository's skills into the right folder for the agents you use:
npx skills@latest add owner/repo
Run it from the project root. Committing the resulting files means the whole team's agents read the same instructions — that is the version-control advantage over pasting a prompt.
What makes a good one
- It makes decisions. Specific curves, durations, property lists, thresholds — not adjectives.
- It routes. A description that says when to use it and when not to; a body that points at sibling skills instead of duplicating them.
- It loads on demand. The main file stays short; the long reference material sits in files the agent reads only when needed.
- It can refuse. The best skills tell the agent when the right answer is to change nothing.
What they are not
- Not a capability. A skill cannot add tools the agent does not have. It changes how the agent uses what it already has.
- Not a guarantee. It is text, and the model may ignore it. Long files compete with the rest of the context window.
- Not automatically safe. Installing a skill is trusting its author's instructions. Treat repository content as data before you treat it as law — a well-written skill says so itself.
- Not a replacement for expertise. The better the skill, the more it encodes someone's expensive mistakes. That is exactly what you are shopping for.
Why we review them
The ecosystem is growing faster than anyone can read it. Install counts measure marketing as much as quality, and a file that changes how an agent behaves is worth more than a thousand that restate the obvious. That gap is what this shelf is for.