What is an Agent Skill?
An Agent Skill is a reusable instruction file that teaches an AI agent to do one task well, such as reviewing code or extracting PDF tables. It ships as a SKILL.md file: YAML frontmatter plus Markdown instructions. The agent loads it automatically when a request matches, and the same file works across Claude Code, Cursor, Codex, and 60+ other agents.
Think of a skill as a specialist you hire once and keep. Instead of re-explaining your preferred workflow every session, you install the skill and the agent applies it whenever the task matches: the same review checklist, the same document pipeline, the same deployment runbook, every time.
What is a SKILL.md file?
A SKILL.md file is the open format an Agent Skill ships in: YAML frontmatter with name,
description, and optional license, followed by Markdown instructions in the body. The
agent reads the short description to decide when the skill is relevant, then loads the full body only when needed.
Larger skills add companion files (scripts, templates, reference docs) next to the SKILL.md.
---
name: dockerfile-optimizer
description: Reviews and optimizes Dockerfiles for smaller, faster builds. Use when the user asks to improve a Dockerfile.
license: MIT
---
# Dockerfile optimizer
When asked to optimize a Dockerfile:
1. Pin the base image and prefer slim variants.
2. Order layers from least to most frequently changed.
3. ...Full field reference and lint rules: SKILL.md format.
How does an agent decide to use a skill?
Automatically, through what the ecosystem calls progressive disclosure. At session start the agent sees only each installed skill's name and description, which costs almost no context. When your request matches a description, the agent pulls in that skill's full instructions and follows them. You never have to invoke a skill by name, which is why a specific, trigger-rich description matters more than anything else in the file.
Agent Skills vs. MCP servers vs. plugins
The three extend an agent in different ways. A skill adds knowledge and method. An MCP server adds live capabilities. A plugin (a Pack, on SkillMD) bundles related skills so you can install a whole workflow at once.
| Agent Skill | MCP server | Plugin / Pack | |
|---|---|---|---|
| What it is | An instruction file (SKILL.md) | A running program exposing tools | A bundle of skills, sometimes commands |
| What it adds | Knowledge, method, house rules | Live data and actions (APIs, services) | A complete workflow in one install |
| Executes code? | No; the agent reads it | Yes; it is a process | Only what its member skills describe |
| Install | Copy one file, or one CLI command | Configure a command or endpoint | One command installs every member |
The two compose well: a skill can teach the agent when and how to use an MCP server's tools.
Are Agent Skills safe?
Treat a skill like any code or configuration you add to your workflow. On SkillMD, every public skill passes an automated safety review before it is listed, shows a verdict on its page, and carries capability flags that say whether it is docs-only or can execute scripts, make network calls, or read secrets. Independent open-source scanners also audit skills, and their results appear on each skill's page. SkillMD never runs a skill's scripts for you: review the SKILL.md before installing, especially from unverified authors.
Where to get Agent Skills
SkillMD (this site) is a free, open registry of thousands of safety-reviewed Agent Skills for Claude Code, Cursor, Codex, and 60+ other agents. Three ways to install any of them:
- CLI:
npm i -g skillmds, thenskillmd add <owner>/<name>. - Agent chat: connect the SkillMD MCP server and ask your agent to install a skill by name.
- Manual: download the SKILL.md from any skill page and copy it into your agent's skills directory.
Frequently asked questions
What is the difference between an Agent Skill and a prompt?
A prompt is something you type once; a skill is a saved, versioned instruction file the agent loads by itself whenever a matching task comes up. Skills can also ship companion files (scripts, templates, references), carry a license, and be shared and reviewed like code.
Do I need to invoke a skill by name?
No. The agent compares your request against each installed skill's description and loads the most relevant one automatically. A clear description with concrete trigger phrases is what makes a skill discoverable to the model.
Where do I get Agent Skills?
SkillMD (skillmd.com) is a free, open registry of thousands of Agent Skills. Search by task, category, or agent, then install with one CLI command (npx skillmds add owner/name), through the hosted MCP server, or by copying the SKILL.md file directly.