What Are Agent Skills (and What Is a SKILL.md File)?

Quick answer
An Agent Skill is a directory with a SKILL.md file (plus optional scripts and resources) that packages one procedure an agent can load when a task matches.
The only required frontmatter fields are name and description; name must be lowercase words joined by single hyphens and must match the folder name.
Skills use progressive disclosure: the agent sees only the name and description until it decides the skill is relevant, so an unused skill costs almost nothing in context.
A skill is instructions, not a capability. It tells the agent how to use tools it already has, which is why it is different from an MCP server.
Because skills can ship scripts and shell instructions, an installed skill is executable supply chain — treat it like code you did not write.

What is an Agent Skill?

An Agent Skill is a folder that contains a SKILL.md file and, optionally, supporting scripts and reference files. The SKILL.md describes one procedure: how to run a migration, how to review a pull request in this repository, how to format a changelog. When a task matches the description, the agent reads the skill and follows it.

The format was introduced in late 2025 and donated to the Agentic AI Foundation in October 2026, so it is no longer tied to a single coding tool. Because it is just markdown and files, the same skill folder can be copied between agents, committed to a repository, or installed from a registry.

What does a SKILL.md file contain?

A SKILL.md is YAML frontmatter followed by markdown instructions. The required fields are name and description. Optional fields cover licence, compatibility, metadata, and an experimental allowed-tools list. The body is normal prose: what the skill does, when to use it, the steps to follow, and how to verify that the result is correct.

The description is the most important line in the file. The agent uses it to decide whether to load the skill at all, so a vague description means the skill never triggers, and an over-broad one means it triggers on unrelated work.

---
name: changelog-entry
description: Write a changelog entry for a merged pull request in the format this repository uses. Use when asked to update CHANGELOG.md.
---

1. Read the diff for the merge commit, not the whole branch.
2. Group the change as Added, Changed, Fixed, or Removed.
3. Write one sentence in the imperative mood, naming the user-visible effect.
4. Add the entry under the Unreleased heading and leave existing entries untouched.

How does an agent decide to use a skill?

The harness exposes the skill’s name and description to the model, and keeps the body on disk until the model asks for it. That two-stage design is why a folder of twenty skills does not consume twenty documents of context: only the matches are read in full.

Triggering is a judgement call by the model, not a deterministic lookup. Two skills with overlapping descriptions compete, and the model may choose neither. Writing descriptions that name the task and the file types involved is more reliable than writing descriptions that describe the skill in the abstract.

How is a skill different from an MCP server?

An MCP server gives the agent new tools: a way to query a database, call an API, or read a ticketing system. A skill gives the agent a procedure for using tools it already has. MCP expands what the agent can reach; skills change how it behaves once it is there.

The practical consequence is security. An MCP server is a process with credentials and network access, so it needs scoping and auditing. A skill is text plus optional scripts that the agent may execute with the permissions it already holds, so it needs review of what it tells the agent to run.

Where this bites vibecoders
A generated skill usually looks convincing because it is fluent markdown, and nothing in the file forces it to be safe or correct. Before installing one, read the body for commands that download and execute code, instructions to read an entire environment file, or a step that disables permission prompts. The agent will follow those instructions with your credentials.

Where AI coding assistants get this wrong

Writing a description that describes the skill instead of the task that should trigger it.
Putting a whole style guide in one skill instead of one procedure per skill.
Copying a skill from a registry without reading the scripts it tells the agent to run.
Assuming an installed skill is used in every session; without a matching description it is silently ignored.
Shipping secrets or internal URLs inside a skill folder that gets committed to a repository.
Treating the skill name as free-form text when the specification requires lowercase hyphenated words.

Checklist

Give each skill exactly one job and name the trigger conditions in the description.
Keep name lowercase and hyphenated, matching the folder name.
Read every script and command in the skill before installing it.
Check whether the skill asks for permissions beyond the task.
Commit project skills to the repository so reviewers can see changes.
Test that the agent loads the skill for a realistic prompt.

FAQ

Are Agent Skills the same as Claude Skills?

Claude Skills was the original name for the format Anthropic published. In October 2026 the standard was donated to the Agentic AI Foundation and is now vendor-neutral, so other agents can implement the same SKILL.md format. The file layout did not change with the donation.

Do skills run code?

A skill itself is markdown, but it can include scripts and can instruct the agent to run commands. The agent executes those commands with whatever permissions the session has. That is why an unfamiliar skill is a supply-chain risk rather than a document.

How many skills should a project have?

As many as there are distinct procedures worth standardising, but each one should be narrow. A large library with overlapping descriptions makes triggering unreliable, because the model has to choose between near-duplicates. Prefer a few precise skills over a large vague set.

Where should skills live?

Team-wide skills that describe how this repository works belong in the repository, under version control, so changes are reviewable. Personal preferences belong in your user-level skills directory. Mixing the two is how a personal shortcut ends up governing everyone’s agent.