What are agent skills? SKILL.md, explained
An agent skill is a folder of instructions that an AI coding agent loads to perform a specific task the way you want it done. At minimum it contains a SKILL.md file — markdown with a small frontmatter header — and optionally supporting files: checklists, reference documents, scripts, templates. When the agent recognizes that a task matches the skill's description, it reads the instructions and follows them.
That is the whole idea. No plugin API, no code to compile, no server to run. A skill is knowledge, packaged.
Where skills came from
Skills grew out of a simple observation: system prompts don't scale. Teams kept pasting the same instructions into every session — review checklists, release procedures, architecture rules — and agents kept forgetting them the moment the session ended.
Anthropic formalized the answer for Claude Code in late 2025: put the instructions in a SKILL.md file with a name and a description, drop it in a known folder, and let the agent decide when to load it. The format was deliberately boring — markdown plus two frontmatter fields — which is exactly why it spread. Today most major coding agents read the same convention, many of them through the shared .agents/skills directory, and the format is documented as an open standard at agentskills.io.
How a skill actually works
Three properties make skills different from a block of text in a system prompt:
- Progressive disclosure. The agent doesn't carry every skill in context all the time. It sees only each skill's one-paragraph
description; the full instructions load when a task matches. Fifty skills cost almost nothing until one is needed. - They travel as files. A skill is a folder. It can be copied, diffed, reviewed, versioned, and installed — everything your team already knows how to do with files.
- They encode judgment, not just facts. A good skill says how to decide: "prefer X unless Y", "never do Z without asking". That is what makes an agent behave like a senior member of your team instead of a generic assistant.
A minimal example
---
name: secure-code-review
description: Reviews diffs against our security checklist. Use when
reviewing pull requests or when the user asks for a security pass.
---
# Secure code review
1. Read the full diff before commenting.
2. Check every input path against references/owasp.md.
3. Flag secrets, raw SQL, and disabled validations as blockers.
4. Output findings as a table: severity, file, line, fix.
The description matters more than anything below it — it is the only part the agent sees before deciding whether the skill applies. Vague descriptions produce skills that never trigger.
What skills are not
- Not prompts. A prompt is a one-off instruction in a conversation. A skill is persistent, named, and reusable across sessions and people.
- Not MCP servers. MCP gives agents live capabilities — querying a database, calling an API. Skills give agents knowledge and procedure. The two compose well; they don't compete.
- Not fine-tuning. No training run, no model artifact. Change the file, and the behavior changes in the next session.
The part nobody tells you about
Writing one skill is easy. The hard part appears when they multiply: ten engineers, forty skills, three coding agents, and no one can say which version of deploy-checklist anyone is running. Skills end up zipped into Slack threads and copied between laptops — precisely the problem package managers solved for code decades ago.
That distribution problem is what MasterSkills exists for: a private registry where teams publish skills with versions and access rules, and every member installs them into all of their coding agents with one command. But whichever tool you use, the principle stands — treat skills like packages, not like pasted text.