What is a SKILL.md file?

A SKILL.md is a markdown file that packages procedural knowledge for an AI agent: a short front-matter block (name and description) plus a detailed body of instructions, often with reference files or runnable scripts alongside it. Anthropic's own example is a front-end design skill — essentially a very detailed, expert-written prompt the agent reads only when doing front-end work.

How does progressive disclosure work in agent skills?

Only the skill's front matter — its name and a one-line description — sits in the agent's context by default. When the agent decides a task needs that capability, it reads the full SKILL.md body, and only then any linked references or code. Knowledge loads in stages, exactly when it's needed.

When should I write a skill instead of adding to the system prompt or building an MCP tool?

The system prompt is only for information the agent needs regardless of task; skills are for knowledge needed some of the time (policies, procedures, formats); tools are for atomic actions the model can't do itself. In the Anthropic workshop's refactor this cut a 400-line prompt to 15 lines while lifting evals from 83% to 92%.

Agent Skills & Progressive Disclosure

Episodes on PodLearn

Anthropic Workshop: Build Agents That Run for Hours — Ash Prabaker & Andrew Wilson

Keep exploring

MCP explained by the people building it
Building AI agents with Claude
What builders say about AI agents
Podcast MCP server — bring transcripts into Claude