What Are Agent Skills?

An Agent Skill is a folder containing a SKILL.md file that an AI agent loads only when the task calls for it. The file holds instructions written in plain Markdown, with a small YAML header at the top telling the agent what the Skill does and when to use it. Optional subfolders can carry scripts, reference documents, and assets the agent can open or run.

That is the whole idea. No API, no server, no SDK. A folder of instructions the agent discovers on its own.

The format started at Anthropic and was released as an open standard, and it has since been adopted by a long list of coding agents and IDEs (agentskills.io). This article covers what goes inside a Skill, how the loading mechanism actually works and what it costs in tokens, how Skills compare to MCP servers and system prompts, which clients support them today, real Skills people are running in production, how to build one, and the cases where a Skill is the wrong answer.

Agent Skills compared to MCP servers, system prompts, and subagents

Read this before anything else, because most confusion about Agent Skills comes from mixing them up with the three things sitting next to them.

The short version: a system prompt is what the agent always knows, a Skill is what it knows how to do when the situation comes up, an MCP server is what it can reach, and a subagent is where it goes to think without making a mess.

How Agent Skills work

The mechanism that makes Skills interesting is progressive disclosure, and Anthropic's documentation splits it into three levels (platform.claude.com).

Level 1 is metadata. At startup, the agent loads only the name and description from the YAML frontmatter of every installed Skill. That costs around 100 tokens per Skill. This is the entire index the agent works from, and it is cheap enough that you can have a lot of Skills installed without noticeably eating your context window.

Level 2 is the body. When a user request matches a Skill's description, the agent reads the rest of SKILL.md into context. Anthropic recommends keeping this under 5k tokens. This is where your actual instructions live: the process, the constraints, the things you want done in a specific order.

Level 3 is everything else in the folder. Reference documents, templates, scripts. None of it costs context until the agent opens it. Scripts get a special treatment worth understanding: the code itself never enters the context window, only the output of running it. So a 2,000-line Python script that produces a 40-token result costs you 40 tokens.

The consequence for how you write Skills is direct. SKILL.md should be a short routing document that tells the agent what to do and points to where the detail lives. Long reference material belongs in files the agent opens on demand. If you write one enormous SKILL.md, you have thrown away the main benefit of the format and reinvented a very large system prompt.

The other thing to internalize is that the description field is the trigger. The agent matches the user's request against your description text to decide whether to load the Skill at all. A vague description means the Skill never fires, and you will spend an afternoon debugging instructions that the agent never read.

What goes in a SKILL.md file

The required structure is small. A YAML frontmatter block with two mandatory fields, then Markdown.

name has a maximum of 64 characters, lowercase letters, numbers, and hyphens only. It cannot contain the words "anthropic" or "claude" (platform.claude.com).

description must be non-empty and can run up to 1024 characters. It has to state both what the Skill does and when to use it. Those are two separate jobs and skipping the second one is the most common mistake.

A minimal file looks like this:

---
name: quarterly-revenue-report
description: Builds the quarterly revenue report from the finance export. Use when the user asks for a quarterly report, revenue summary, or QBR numbers.
---

## Overview
...

## Process
1. ...

The optional folders sit alongside it. scripts/ holds executable code the agent can run. references/ holds documents it can read. assets/ holds templates, logos, boilerplate files. The layout is documented on agentskills.io.

For the body itself, the most battle-tested structure in public is the one used across addyosmani's collection: Overview, When to Use, Process, Rationalizations, Red Flags, Verification (github.com/addyosmani/agent-skills). The two sections most people would never think to write are the interesting ones. Rationalizations lists the excuses an agent makes for skipping a step, so the Skill can preempt them. Verification tells the agent how to check its own work before declaring the task done. Both exist because agents cut corners under instruction-following pressure, and naming the specific corner they cut is what stops it.

Agent Skills vs MCP servers

This is the comparison that actually decides whether you should build a Skill, and it deserves more than a row in a table.

MCP is a protocol for giving an agent capabilities. You run a server, it exposes tools, the agent calls them. It handles authentication, it talks to live systems, it returns fresh data, it can write to your database. It requires infrastructure and it costs context for as long as its tool definitions are loaded.

Agent Skills are a packaging format for knowledge. There is no server. There is no auth layer. There is no live connection. A Skill knows only what somebody wrote in a file.

They are not competitors, and the healthiest way to think about it is that MCP gets the agent to your data and a Skill tells it what to do once it is there. An MCP server can pull the last 90 days of support tickets. A Skill can encode the way your team triages them. Running both is normal.

Where people go wrong is trying to solve capability problems with Skills. Four cases where a Skill is the wrong tool:

There is also a practical argument for Skills that MCP cannot match. Skills are cheap. 100 tokens per Skill at rest means you can install thirty of them and pay almost nothing until one fires. Thirty MCP servers is a very different conversation about your context budget and your ops burden. If what you have is process knowledge rather than a systems integration problem, the Skill is the lower-cost answer and you should reach for it first.

Against system prompts, the calculus is simpler. Everything in your system prompt is paid for on every request, including the 400 lines about your PDF export conventions that are relevant twice a month. Move conditional procedure into Skills and keep the system prompt for what is genuinely always true.

Against subagents, Skills are not an alternative at all. A subagent is an execution strategy. It can load Skills of its own. Use subagents when you need context isolation, use Skills when you need to encode a procedure.

Which clients support Agent Skills

Skills started as an Anthropic format and were released as an open standard, so support now runs well past Claude. As of September 2026, the client list published on agentskills.io includes Claude Code, Cursor, GitHub Copilot, VS Code, Codex and ChatGPT, Gemini CLI, OpenCode, OpenHands, Goose, Kiro, Letta, Amp, Roo Code, Factory, Tabnine, Laravel Boost, Databricks Genie Code, Snowflake Cortex Code, Pulumi Neo, and Mistral Vibe.

Inside Anthropic's own surfaces, the pre-built document Skills for pptx, xlsx, docx, and pdf are available on the Claude API, on claude.ai, on Claude Platform on AWS, and on Microsoft Foundry.

Installation differs by surface. In Claude Code, custom Skills live in ~/.claude/skills/ for personal Skills or .claude/skills/ inside a project. On claude.ai you upload a zip through Settings, then Features. On the API you use the /v1/skills endpoints, and Skills there require the code execution tool to be enabled.

One detail that catches teams out: Skills do not sync across surfaces. claude.ai Skills are per-user, API Skills are workspace-wide, and Claude Code Skills live on whatever filesystem you put them on. If you want one Skill available everywhere, you are distributing it three times, which is a strong argument for keeping Skills in a git repo rather than uploading zips by hand.

Runtime behavior also differs, and this one has security consequences. On the Claude API, Skills run sandboxed with no network access and no runtime package installation. In Claude Code, a Skill's scripts have the same network access as any other program running on that machine.

Examples of Agent Skills people actually use

Anthropic's own document Skills are the clearest illustration of why the format exists. The pptx, xlsx, docx, and pdf Skills bundle the procedures and code needed to produce real Office and PDF files. The model does not need to hold the OOXML details in context. It loads a Skill when a user asks for a deck, follows the process, and runs the bundled scripts whose code never touches the context window.

The largest public collection is addyosmani/agent-skills, at 92.4k stars and 9.8k forks under an MIT license. It ships 25 Skills, 24 covering the software development lifecycle plus one meta Skill, mapped to 9 slash commands: /spec, /plan, /build, /test, /constraints, /review, /webperf, /code-simplify, and /ship. You can install it with npx skills add addyosmani/agent-skills.

Individual Skills worth reading before writing your own: test-driven-development, code-review-and-quality, and security-and-hardening. They are useful less as things to install and more as examples of how much specificity a good Skill carries. They anticipate the shortcuts an agent takes and close them off by name.

On the framework side, Laravel Boost ships Laravel-specific Skills, which is the pattern to watch. Frameworks and platforms distributing their own conventions as Skills means the agent stops guessing at the idioms of your stack and starts following the ones the maintainers wrote down.

The pattern across all of these is the same. Skills earn their place where there is a right way to do something, that right way is written down nowhere the agent can see, and the agent otherwise improvises a plausible wrong version of it.

How to create an Agent Skill

Start from a task the agent already gets wrong in a consistent way. If you cannot name the specific failure, you do not have a Skill yet, you have a preference, and preferences belong in your system prompt or nowhere.

Create the folder and the SKILL.md file. Write the frontmatter first, and spend real time on the description, because it is the only thing standing between your instructions and never being read. Name what the Skill does, then name the situations that should trigger it, using the words a user would actually type.

Write the body as a process, not an essay. Numbered steps. Concrete file paths, real command names, actual output formats. If a step has an exception, write the exception. If the agent tends to skip a step and claim it was unnecessary, write that excuse down and rule it out.

Keep the body under 5k tokens. When it grows past that, move the detail into references/ and leave a pointer behind. The agent will open the file when it needs it and pay nothing for it when it does not.

Push deterministic work into scripts/. Anything the agent tends to get subtly wrong by hand, and anything with a verifiable output, is better as a script that runs than as instructions the agent follows. The code stays out of context and only its output comes back.

End with a verification step. Tell the agent how to prove the task is done rather than letting it decide by feel.

Then test it by trying to trigger it accidentally and deliberately. Ask for the task in three different phrasings and see whether the Skill fires. Ask for something adjacent and see whether it fires when it should not. Most Skill debugging is description debugging.

Install it where your team works. For Claude Code, drop it in .claude/skills/ inside the project repo so it ships with the codebase and everyone gets it on clone.

What Agent Skills cannot do

Skills go stale silently. The file that encoded your deploy process in March keeps confidently describing the March process in September, and nothing in the format tells the agent that the world moved. There is no versioning of truth here, only versioning of a document. Someone has to own the update, and in practice nobody does until the Skill causes a visible failure.

Skills have no source of truth outside the file. A Skill cannot check whether it is still right. It cannot query the current state of your pricing, your policy, your architecture, or your law. If accuracy at the moment of use matters, the Skill needs to be paired with something that can go and look.

Skills are executable software and should be treated that way. Anthropic's documentation is explicit that you should install Skills only from trusted sources, that a malicious Skill can direct an agent to invoke tools or execute code against the Skill's stated purpose, and that Skills fetching external URLs are particularly risky (platform.claude.com). Bundled scripts run with whatever permissions the agent has, which in Claude Code means the permissions of the machine. Installing a Skill from a random repo is the same trust decision as running a random install script, and it deserves the same scrutiny. Read the SKILL.md and the contents of scripts/ before you install anything you did not write.

The deeper limitation is that a Skill is one person's judgment frozen at one moment. It works beautifully for procedure and poorly for calls that depend on the specifics in front of the agent. When the decision is genuinely consequential and genuinely novel, you want a person who is accountable for the answer, not a file that resembles one.

How to keep an Agent Skill from going stale

The honest answer first. Version the Skill alongside the thing it describes, put one person's name on it as owner, and attach a review trigger to whatever actually changes. If a Skill documents your deploy process, the pipeline config changing is the signal to reread it. Skills kept in a repo get most of this for free. Skills uploaded as zips through a settings panel get none of it, which is the strongest practical argument for keeping them in version control.

The other option is to stop packaging the judgment and let the agent ask for it. On Callstand, an expert publishes a connector without writing code, and an agent calls it mid-workflow, paying per call from prepaid credits. A human answers each call against the situation actually in front of the agent and stands behind that answer, so there is no document to keep current and no one has to notice it went stale.

Should you build one

Build a Skill when the same procedure keeps getting done slightly wrong, when the correct version fits in a document, and when it does not depend on data that changes underneath you.

Do not build a Skill when what you need is live data, credentials, a system integration, or a judgment call that has to account for specifics nobody could have written down in advance. And do not build one to encode something the model already knows how to do well, because you will pay context to make it worse.

There is a third branch worth naming, and it applies if you are the expert rather than the one installing. When the advice you would write down changes month to month, publishing it as something the agent calls is less work than authoring a SKILL.md and then keeping it honest for the next two years.

The format is small on purpose. Most of its value comes from the discipline of writing your process down clearly enough that a machine can follow it, which is a thing worth doing even if you never install the file.

Frequently asked questions