How Agent Skills Work: Progressive Disclosure Explained

How Anthropic Designed the Skills System

This is the official Anthropic explainer on how Agent Skills work mechanically - short and practical.

The progressive disclosure system. At startup, only name and description of each installed skill loads into the system prompt - about 30-50 tokens per skill. This makes Claude aware of skills without consuming context. When a user prompt matches a skill's description, Claude dynamically loads the full skill.md. If that skill references other files or scripts, they load progressively as needed. Result: you can install many skills for complex tasks without bloating context.

How skills fit with other Claude features:

• Claude.md = project-specific context (tech stack, coding conventions, repo structure). Lives alongside your code. "We use Next.js and Tailwind."
• Skills = portable expertise that works across any project. A front-end design skill teaching typography standards activates automatically when building UI.
• MCP servers = universal integration protocol connecting Claude to external sources (GitHub, Linear, Postgres). "MCP connects to data. Skills teach Claude what to do with it."
• Sub-agents = specialized AI assistants with fixed roles, own context windows, custom prompts. Skills provide portable expertise any agent can use.

The synergy: Claude.md sets foundation → MCP servers connect data → Sub-agents specialize → Skills bring expertise.

7 Insights From Anthropic on Agent Skills Architecture

• 30-50 tokens per skill - Only name/description loaded at startup; full content loaded when matched
• Progressive loading - skill.md loaded on match; referenced files/scripts load as needed
• Portable across surfaces - Works in Claude Code, API, and claude.ai
• Claude.md = project, skills = expertise - Claude.md is repo-specific; skills are reusable across projects
• MCP = data, skills = what to do - MCP gives access; skills teach patterns (query optimization, etc.)
• Sub-agents can share skills - Front-end agent and reviewer can both use accessibility skill
• Use cases - Onboarding new hires, PR security practices, data analysis methodology

What This Means for Agent Developers

Skills use progressive disclosure to pack hundreds of capabilities into 30-50 tokens each - only loading full content when needed. Combined with MCP for data and Claude.md for project context, skills form the expertise layer that makes general agents into specialized ones.