Agent Skills: giving an agent new capabilities with SKILL.md

There's a clean way to give an agent new, reusable capabilities without bloating its system prompt: skills. A skill packages instructions, expertise, and even scripts into a folder the agent can pull in when a task calls for it — and thanks to how it's loaded, you can give an agent a hundred skills and pay almost no context for the ninety-nine it isn't using.

What a skill is

A skill is a folder containing a SKILL.md file — a bit of YAML frontmatter (a name and a description) followed by instructions in Markdown — plus optional scripts and resource files. It's a self-contained package of 'here's how to do this task', which the agent reads to gain a capability it didn't have in its base prompt.

# a skill is a folder: pdf-forms/SKILL.md  (+ optional scripts, resources)

---
name: pdf-forms
description: Fill and extract data from PDF forms. Use when the user works with PDFs.
---

# Filling PDF forms
Step-by-step instructions the agent follows when this skill is triggered,
and which may reference bundled scripts or files that load only when needed.

Progressive disclosure: the key idea

Skills scale because they load in layers rather than all at once — progressive disclosure, which is really context engineering applied to capabilities:

• Level 1 — the name and description are always in context. Tiny, so many skills cost almost nothing, and this is what the agent uses to decide a skill is relevant.
• Level 2 — when a skill is relevant, its full SKILL.md body loads: the actual instructions for the task.
• Level 3 — bundled files and scripts load only on demand, when the instructions reach for them.

The payoff: the agent carries a cheap index of everything it can do, and pulls the expensive detail into context only for the skill it's actually using right now.

Skills vs tools: when to use what

Skills and tools solve different problems, and the distinction is worth getting right. A tool is a single function the model calls — a discrete action with a schema (see the tool-calling post). A skill is a package of instructions, knowledge, and optional scripts that teaches the agent how to do something — a whole procedure, which may itself use tools.

• Use a tool when — you want the model to invoke one specific capability: query a database, send an email, call an API.
• Use a skill when — you want to give the agent a reusable procedure or expertise it can follow: a workflow, a domain playbook, a format it must produce, backed by scripts.
• The one-liner — a tool is a verb the model calls; a skill is a playbook the agent reads. Tools do; skills teach.

Why skills matter

Skills make capabilities reusable, composable, and portable: author one once and any agent can load it, without you rewriting a giant system prompt for every new task. It's the cleanest way I've seen to grow what an agent can do while keeping its context lean — which, as the context-engineering post argues, is most of the battle.

Tools give an agent hands. Skills give it know-how — packaged, discoverable, and loaded only when the moment calls for it.