What Are Agent Skills? A Plain Guide to the SKILL.md Format

So what is an Agent Skill, really, and is it a genuine format or another word for “prompt”? Here is the plain answer, before the hype has a chance to crowd in. An Agent Skill is a folder of instructions, scripts, and reference files with a SKILL.md file at its root. Your AI coding agent reads that folder and follows a repeatable workflow instead of improvising one from scratch each time. The SKILL.md file holds a small block of metadata at the top and plain-language instructions below it. Anthropic introduced the format for Claude, and because a skill is just files plus optional scripts, other AI coding agents that read files and run shell commands can follow the same workflow, with installation steps that vary by client.

If you have pasted the same long prompt into an assistant for the tenth time, that is the itch a skill scratches. You write the workflow once, save it as files, and the agent loads it on demand. Slow down on that one word: files. You can open a skill and read every instruction your agent is about to follow, before a single one runs. That is the difference between a workflow you can reason about and a plugin you have to take on faith, and it is the reason the format matters.

What a skill actually contains

At minimum, a skill is a directory with one file: SKILL.md. Most real skills bundle more. The Anthropic Agent Skills documentation describes three kinds of content, each loaded at a different moment:

• Metadata. A short YAML header with the skill’s name and description.
• Instructions. The body of SKILL.md: the workflow steps, the questions to ask, the quality checks, and the mistakes to avoid.
• Resources and code. Optional extra files. Reference documents the agent reads only when it needs them, and scripts the agent runs through the shell.

A typical layout looks like this:

scrolldio/
  SKILL.md
  references/
    concepts.md
  scripts/
    encode.sh
  assets/
    starter-page.html

The folder name is not cosmetic. Per the Agent Skills specification, a skill’s name must match its parent directory, so an agent and a person both know what they are looking at without guessing.

How the SKILL.md file is structured

Every SKILL.md opens with YAML frontmatter, and two fields are required: name and description. Per the Agent Skills specification, the name can run up to 64 characters using lowercase letters, numbers, and hyphens, and the description can run up to 1024 characters. The description has to state two things: what the skill does and when the agent should use it.

---
name: scrolldio
description: Turn a business brief into a cinematic scroll website. Use when the user wants a scroll-driven landing page with AI-generated visuals.
---

# Scrolldio

## Workflow
1. Capture the brief, audience, and conversion goal.
2. Choose a concept and lock an identity frame.
3. Generate a coherent scene set, then seam-safe motion.

That description is not decoration. It is the text the agent matches your request against when it decides whether to load the skill at all. A vague description means the skill never fires when you need it. A precise one means it fires at the right moment and stays quiet the rest of the time. Write it the way you would teach a colleague when to reach for the tool.

Why you can install many skills without slowing your agent down

The reason a stack of skills does not bloat every conversation is a pattern the Anthropic docs call progressive disclosure. The agent loads information in stages.

• The metadata is always in context, at a cost of roughly 100 tokens per skill.
• The instructions load only when the skill is triggered.
• The resources and scripts load only when the workflow reaches for them. A script’s code never enters the context window; the agent runs it and reads the output.

So a skill can ship a long checklist or a large reference file without taxing every message you send. The heavy material sits on disk until the moment it earns its place. This is why a well-built skill feels lightweight even when it carries real depth behind it.

A skill is more than a saved prompt

A prompt lives and dies inside one conversation. A skill is files you keep, version in git, and move between projects. Because the instructions sit next to runnable scripts, a skill can hand deterministic work to code and keep the judgment work for the model. Checking image dimensions, encoding a video, validating a file: those belong in a script that does the same thing every run. Deciding which concept fits a brand belongs to the model reading the instructions.

That split is what turns a lucky one-off into a result you can repeat. Code behaves identically every time. Instructions keep the model on a known path. A saved prompt gives you neither of those, which is why the tenth paste never quite matches the first.

Where skills live and how your agent finds them

Skills are filesystem-based. In Claude Code, you place a personal skill in ~/.claude/skills/ and a project skill in .claude/skills/ inside the repository, per the Claude Code documentation. Other agents use their own directory, and the exact path varies by client. The shared idea holds across all of them: drop the folder where the agent looks, refresh the session, and the skill shows up in the available list.

If you want to see the shape of a real one before writing your own, Anthropic publishes a set of open-source skills in its public skills repository. Reading a few good examples end to end teaches the format faster than any spec.

Why plain files are the real feature

Here is the part the hype skips. Because a skill is plain files, you can inspect it the way you would any dependency you let near your shell. Open it, read the instructions, see exactly what the agent will be told to do, then decide. A plugin you cannot read asks you to trust a stranger’s judgment. A skill you can read asks you to trust your own.

That readability is the premise behind Aaria, a marketplace for Agent Skills packaged from real product work. Every listing, including Scrolldio, ships as standard Markdown, scripts, and templates, and any capable AI coding agent can follow the workflow. Installation steps differ by client, and each listing states what your agent must already be able to do. Nothing hides behind a compiled blob, because the entire value of the format is that you never have to guess.

Once you can read a skill in full, the next question follows on its own: how do you tell a good one from a dressed-up prompt dump? That is a job for a checklist, and worth its own guide.

FAQ

What is the SKILL.md format? SKILL.md is a Markdown file with a YAML header at the top. The header carries the skill’s name and description, and the body carries the workflow instructions the agent follows. It sits at the root of the skill’s folder, and you can read the whole thing before you install it.

Do I need Claude to use Agent Skills? The format started with Claude. Because a skill is just files plus optional scripts, a capable AI coding agent that can read a folder and run shell commands can follow one, though installation steps differ by client.

What is the difference between a skill and an MCP server? A skill is instructions and assets the agent reads and runs locally. An MCP server is a separate service that exposes tools over a protocol. They work well together: a skill can tell the agent how and when to call the tools an MCP server provides.

How big can a skill be? The instructions are meant to stay small, but bundled reference files and scripts can be large because they load only when needed. That is the point of progressive disclosure: depth on disk, not in every conversation.