What Are Agent Skills?

The Problem: Agents Are Generalists

A frontier LLM knows an enormous amount about the world in general and almost nothing about your world in particular. It doesn’t know that your team reviews SQL migrations with a specific checklist, that your PDF-heavy workflow needs OCR fallback for scanned documents, or that your API returns error codes in a nonstandard format. Ask it to do that work and it’ll either guess — sometimes plausibly, sometimes wrong — or ask you to explain, every single time.

The obvious fix is to explain the context once, in the system prompt. That works until you have five workflows, then twenty, then a team’s worth of institutional knowledge. System prompts don’t scale: every instruction you add is a permanent tax on every conversation, whether or not that instruction is relevant to the task at hand. A system prompt covering PDF handling, SQL review, deployment procedures, and brand voice guidelines pays the full token cost even when the user just wants to know what day it is.

Agent Skills solve this by moving instructions out of the always-loaded prompt and into folders the agent loads on demand.

What a Skill Actually Is

At its simplest, a skill is a directory containing a SKILL.md file:

pdf-processing/
├── SKILL.md          # Required: metadata + instructions
├── scripts/           # Optional: executable code
├── references/        # Optional: documentation
├── assets/             # Optional: templates, resources

SKILL.md has two parts: YAML frontmatter with at minimum a name and description, and a Markdown body with the actual instructions. That’s the whole format. No proprietary schema, no vendor lock-in — just a folder and a Markdown file, which is why the same skill can run in Claude Code, Claude.ai, VS Code, Cursor, and any other client that implements the (open) Agent Skills specification.

The format was originally developed by Anthropic for Claude, then released as an open standard that other agent products have since adopted.

Progressive Disclosure: The Core Idea

The reason skills don’t have the same scaling problem as system prompts is progressive disclosure — a three-stage loading model:

1. Discovery. When an agent session starts, it scans the available skill directories and reads only the name and description from each SKILL.md — roughly 100 tokens per skill. This happens for every installed skill, whether or not it’s ever used in that session. An agent can have fifty skills registered and pay almost nothing for the ones that don’t apply.

2. Activation. When the user’s request matches a skill’s description, the agent reads the full SKILL.md body into its context — the actual instructions.

3. Execution. The agent follows those instructions, optionally running bundled scripts or reading referenced files as it goes. Those referenced files (in scripts/, references/, assets/) load only if the instructions call for them — a skill can bundle megabytes of reference material without any of it entering context unless it’s actually needed.

Session start
  └─ Discovery:    load name + description for every skill  (~100 tokens each)
User: "merge these three PDFs and extract the tables"
  └─ Activation:   description matches → load full SKILL.md   (<5,000 tokens)
  └─ Execution:    follow instructions, run scripts/merge.py,
                    read references/table-extraction.md if needed

Think of it like a library versus a desk. A system prompt is everything sitting on your desk — visible, immediate, but cluttered the moment you have more than a few things. Skills are a library: a card catalog you scan in a second (discovery), and you only pull a specific book off the shelf once you know you need it (activation).

What Skills Give You

• Domain expertise on demand. Legal review checklists, data pipeline conventions, presentation formatting rules — captured once as reusable instructions, loaded only when relevant.
• Repeatable workflows. A multi-step process — say, “how we cut a release” — becomes a consistent, auditable procedure instead of something re-explained (and re-drifted) in every conversation.
• Cross-product reuse. Because the format is open, a skill built for one client works in any compatible one. Build once, use everywhere.

What Belongs in a Skill (and What Doesn’t)

A skill should teach the agent what it wouldn’t otherwise know: your project’s conventions, an unfamiliar API’s quirks, a non-obvious edge case, the specific tool your team has standardized on. It should not re-explain things the underlying model already understands well — what a PDF is, how HTTP works, what a database migration does in general. Every sentence in a skill competes for attention once it’s loaded, so the discipline of “would the agent get this wrong without me telling it?” matters from the very first skill you write. You’ll see exactly why this matters once you cover progressive loading later in this course — every extra sentence is a token cost paid on every activation.

A Concrete Before/After

Without a skill, asking an agent to “review this PR” gets you a generic pass — check for typos, maybe suggest a docstring. The agent has no idea your team requires parameterized queries, checks for missing auth on every endpoint, and flags error messages that leak internal details.

With a code-review skill installed, the same request activates instructions written by someone who’s done that review a hundred times: the specific checklist, the specific failure patterns your codebase tends to produce, the specific tools (a linter, a security scanner) to run first. The agent isn’t smarter — it has your team’s expertise, loaded exactly when it’s needed.

Summary

• Agents are generalists; skills give them specific, reusable expertise without permanently bloating every prompt
• A skill is just a folder with a SKILL.md file — open format, no vendor lock-in
• Progressive disclosure loads skills in three stages: discovery (name + description, always), activation (full instructions, when relevant), execution (bundled files, as needed)
• A skill should add what the agent lacks and omit what it already knows

Next, you’ll go under the hood of SKILL.md itself — the exact frontmatter fields and naming rules that make a skill valid.