What is an Agent Skill — and why it costs almost nothing

Here's a neat trick. You can hand an agent twenty sets of instructions — how your team names branches, how releases get shipped, how to check the layout — and it barely takes up any room in its memory. It holds twenty short lines. The full text? It reads only the one it actually needs.

That's an Agent Skill. And yes, technically it's just a folder with a text file in it.

A skill is a folder, not code

The smallest possible skill looks like this:

release-checklist/
└── SKILL.md

That's it. One SKILL.md file and the skill exists. Inside, it splits in two: a small metadata header at the top, and plain instructions below it.

---
name: release-checklist
description: Check a release before shipping. Use when asked to cut a release,
  ship a version, or prepare a build.
---

Before shipping, walk the steps:

1. Run the tests, make sure they're green.
2. Bump the version number in the manifest.
3. Check that every change made it into the changelog.

The header (called frontmatter) is YAML between two sets of triple dashes. Only two fields are required: name (up to 64 characters, lowercase letters, digits and hyphens) and description (up to 1024 characters). Everything below is your own text in Markdown, written in plain words.

If the skill needs extra files — an email template, a script, a reference doc — they go in scripts/, references/, assets/ subfolders. The agent opens them when it gets that far.

Why it's cheap: the agent reads in stages

Here's the clever part. The agent doesn't hold the whole skill in context. Loading happens in three stages:

• Stage 1. At startup it sees only name and description — literally one line per skill. Think table of contents.
• Stage 2. A task matches the description, so it reads the body of SKILL.md in full.
• Stage 3. The instructions point at a file in references/, so it opens that too.

This is called progressive disclosure. The practical upshot: twenty skills in a project cost you almost no context while they sit unused. Keep as many as you like — you pay for the one that fires.

The description matters more than the instructions

Beginners write great instructions and a lazy description — and then the skill never fires.

Because description is the only thing the agent sees up front. It isn't a title for humans; it's the trigger condition. It has to say what it does and when to use it.

• Bad: description: Component stuff
• Good: description: Create a new UI component following project conventions. Use when asked to add a component, a button, a card, or a new screen.

The second one contains the words you actually use: "button", "card", "screen". The agent matches your phrasing against the description and remembers the skill exists. Same logic as a good prompt: specifics beat generalities.

Why this matters for you, not just for big teams

Odds are you've explained the same thing three times already: "our components live in this folder", "write commits in English", "run the linter before you push". Every new session, from scratch.

A skill turns that explanation into a file. Write it once and it works in every session, for everyone on the team, because it sits in the repository right next to the code.

One more thing: the format is open. The Agent Skills spec is published as a standard (agentskills.io), and it isn't Claude Code only — Microsoft Agent Framework reads the same SKILL.md files. A skill you write travels to another tool without a rewrite.

Ready to build one? Walk it step by step in how to write an Agent Skill — from empty folder to first successful trigger.

How is a skill different from a system prompt?

A system prompt loads every time, in full — it sets the agent's general behavior. A skill sits on the shelf and gets pulled in for a specific task. Roughly: the system prompt is personality, the skill is a manual.

Can a skill run code?

Not on its own — it's just text. But scripts can live in the folder beside it, and the instructions can tell the agent to run them. The code is then executed by the agent through its own tools, under the same permissions and limits as always.

How many skills is too many?

As long as the descriptions are distinct and precise, thirty is fine. Trouble comes from similar descriptions, not from count: if two skills are described the same way, the agent picks the wrong one. Separate them by wording, not by number.