A skill is a reusable package of instructions that gives an agent a specialized capability on demand. Skills follow an open format built around a single file, SKILL.md, and were introduced by Anthropic in late 2025. 1 3 Where the previous guide's MCP servers connect an agent to tools and data, skills teach an agent how to do a task well — captured once and reused.

How skills work: progressive disclosure

The clever part is how skills are loaded. Rather than stuffing every instruction into the context window, skills reveal themselves in three layers, a pattern called progressive disclosure:

  • Discovery. Only each skill's name and one-line description sit in the system prompt — roughly 80 tokens each — so an agent can hold many skills cheaply. 2
  • Activation. When the agent judges a skill relevant to the task, it loads the full SKILL.md instructions into context.
  • Execution. Only if the task needs more does it pull in supplementary files — scripts, references, assets. 5
Figure 1 — Skills load in layers, so the context window stays lean no matter how many are installed.

Figure 1 — Skills load in layers, so the context window stays lean no matter how many are installed.

Anatomy of a skill

A skill is a folder whose entry point is a Markdown file with a small YAML header:

---
name: pdf-filler
description: Fills PDF forms from a data file. Use when a user

provides a PDF form and values to enter.

---

Instructions

1. Read the form's fields. 2. Map the provided values to those fields. 3. Write the completed PDF to the output folder. A minimal SKILL.md — plain-English instructions with a name and a triggering description.

Figure 2 — The frontmatter is always visible for discovery; the body and extra files load on demand.

Figure 2 — The frontmatter is always visible for discovery; the body and extra files load on demand.

The description matters most: it is what the agent matches against to decide whether to activate the skill, so it should state plainly what the skill does and when to use it. 1 Skills can also bundle scripts that run without consuming context, and can restrict which tools they're allowed to use.

Why skills help

  • Leaner context, better results. Loading only what's needed keeps the window focused; measured setups report meaningful token savings and accuracy gains versus one giant prompt. 3
  • Written in plain English. A domain expert can read, edit, or create a skill without coding — or have an AI draft one with a skill-creator. 2
  • Reusable and shareable. Version a skill like any file, commit it to a repository, or distribute it across a team or organization. 1

Skills, MCP, and memory — how they differ

  • MCP servers connect the agent to tools and data (what it can reach).
  • Skills package know-how for a task (how to do it well).
  • Memory persists facts and context across sessions (what it remembers).

They compose: a skill might instruct the agent to call an MCP tool and record the result in memory.

Getting started

Coding agents like Claude Code and Cursor already support skills, and the local Hermes setup from the harness guide reads skills from a folder. To make your own, write a short SKILL.md with a clear description, drop it in the skills directory, and let the agent discover it. 1

Key takeaways

  • A skill is a reusable SKILL.md package that gives an agent a specialized capability on demand. 1
  • Progressive disclosure loads skills in three layers (discovery → activation → execution) to keep context lean. 2
  • A strong description is what makes a skill trigger reliably.
  • Skills package know-how; MCP connects tools; memory persists facts — and they work together.