Agent Skills is an open format for packaging procedural knowledge: a folder holding a SKILL.md, with YAML frontmatter at the top for a name and description, a Markdown body describing how the work is done, and — where useful — scripts, templates, and reference documents alongside.
A handy contrast: MCP gives an agent access to external tools and data; Skills teach the agent what to do with those tools and data. One is the interface, the other is the craft.
Grab It in One Sentence First
Agent Skills is a standard operating procedure written for an AI: one folder saying how this gets done, reusable by anyone.
An everyday analogy is the SOP taped to a restaurant kitchen wall. A new cook doesn't need the head chef narrating over their shoulder; a glance at that sheet gives the order of steps, the heat, the portions, and the usual pitfalls. Skills fix in place the knowledge you'd otherwise re-explain every time, and let the AI go read it.
Why This Term Emerged
Before the standard, every tool had its own format: Cursor had .cursorrules, GitHub Copilot had custom instructions, Windsurf had its own rules, Claude Code had its own project files. They were all doing the same thing — handing project conventions and common procedures to an AI — but the formats were mutually incompatible and portability was essentially zero.
In October 2025, Anthropic launched Agent Skills as a way to teach Claude repeatable workflows. On December 18, 2025, it released Agent Skills as an open standard, publishing the specification and SDK for any AI platform to adopt — the same path it took in making MCP the de facto standard for tool use.
Adoption moved fast: Microsoft (VS Code/Copilot) and OpenAI (ChatGPT, Codex CLI) shipped support within 48 hours; Google's Antigravity adopted it in January 2026; and by March 2026 more than thirty tools were reading identical SKILL.md files.
flowchart TB
Start["Session starts"] --> L1["Tier 1: load name + description only<br/>~30–50 tokens per skill"]
L1 --> Trigger{"Does the task match a skill?"}
Trigger -->|no| Idle["Body never loads"]
Trigger -->|yes| L2["Tier 2: load the full SKILL.md"]
L2 --> Need{"Need more detail while running?"}
Need -->|yes| L3["Tier 3: read references / scripts on demand"]
Need -->|no| Run["Execute the procedure"]
L3 --> RunWhat It Usually Includes
A skill is a directory:
my-skill/
├── SKILL.md # Required: YAML frontmatter + markdown body
├── scripts/ # Optional: executable code
├── references/ # Optional: docs loaded on demand
└── assets/ # Optional: templates and filesThe YAML frontmatter of SKILL.md needs at least name and description, with instructions in the body. The specification recommends keeping SKILL.md under 500 lines and moving detailed material into separate files. scripts/ holds code the agent can execute directly (Python, Bash, JavaScript), and references/ holds technical documentation, templates, or structured data read only when needed.
The key architectural idea is progressive disclosure, loading in three tiers: at startup only the name and description load (roughly 30–50 tokens per skill); the full SKILL.md loads when a task triggers it; reference files load only as execution requires them. The practical benefit is that the amount of context bundled into a skill is effectively unbounded, since the agent never has to read it all upfront.
The Difference from Prompts, MCP, and Subagents
The difference from a prompt is persistence and reuse. A prompt is what you said this time; a skill is a practice written down that takes effect next time on its own. You stop pasting the same conventions, and the agent pulls them up when it judges the task relevant.
The difference from MCP is the split between capability and knowledge. MCP answers "what can the agent connect to"; skills answer "once connected, what procedure applies." The two often pair up: MCP provides the database connection, the skill specifies that database's schema conventions and the checks required before querying.
The difference from a subagent is whether context is isolated. A skill runs in the main conversation using the current session's context; a subagent runs in a separate window and returns only a conclusion. Reach for a skill to reuse a procedure, for a subagent to keep a long process out of the way.
Its Relationship to Loop Engineering
Among the pieces Loop Engineering breaks out, skills are exactly the "codified knowledge" component — project conventions that would otherwise be re-explained each time, fixed into reusable files instead of pasted anew. In a loop that's been running a while, skills are usually the first thing to grow, because after a few cycles you notice you keep explaining the same things.
Where It's Easy to Misunderstand
The first misconception is writing skills as documentation. A skill is a set of instructions for an agent to execute, not a manual for a human to read; "this module handles user management" is useless, while "before changing this module run X to confirm Y, and after changing it you must update Z" is not.
The second is writing the description carelessly. Because only the name and description enter context at startup, whether a skill ever triggers depends entirely on how precisely the description is written. A vague description means the skill sits there and never gets called.
The third is stuffing everything into SKILL.md. The recommendation to keep it short and push detail into references/ exists so progressive disclosure actually works; a two-thousand-line SKILL.md cancels the benefit entirely.
The fourth is confusing a skill with a permission. Writing "always back up before deleting" into a skill is an instruction, not an enforced constraint — real boundaries have to come from tool permissions and guardrails.
How to Decide Whether to Use It
The test is plain: have you now explained this to the AI a third time? Commit conventions, the call order for an internal system, the fixed format of a document type, the checklist that must run before release — all good candidates for codifying as skills.
Poor candidates are one-off, task-specific requirements; just say them, since writing them up only adds maintenance. One more caution: procedures involving secrets, production data, or public publishing can be written as skills, but must also be constrained at the permission and approval layer — a paragraph of text followed voluntarily is not a boundary.