Agent Skills¶
Summary¶
A minimal form factor for packaging procedural knowledge that agents can dynamically load. Organized folders containing a SKILL.md instruction file, optional scripts as tools, templates, and reference materials.
Origins¶
Introduced by Barry Zhang and Mahesh Murag at Anthropic in December 2025. The industry quickly converged on this standard — adopted by Claude Code, Pi, Tolgee, and others.
What Skills Are¶
Skills are folders. That simplicity is deliberate:
- SKILL.md — core instruction file (markdown)
- Scripts (Python, bash, etc.) — executable tools the agent can run
- Templates — fill-in-the-blank documents
- Reference docs — examples, documentation, guidelines
Progressive Disclosure¶
The key innovation that makes skills scale:
1. At startup, agent sees only metadata (name + short description) — like reading book titles on a spine
2. When agent decides it needs a skill, it reads the full SKILL.md
3. Rest of folder is organized for ease of access
4. Allows hundreds or thousands of skills without context overload
This contrasts with prompts, where everything is crammed into context at once and gets messy fast.
Types of Skills¶
| Type | Creator | Purpose |
|---|---|---|
| Foundational | Platform builders | New general/domain capabilities (document creation, scientific analysis) |
| Third-party | Partners | Product-specific skills (Notion workspace, Browserbase automation) |
| Enterprise | Organizations | Company best practices, internal workflows, code style guides |
Skills vs MCP¶
| MCP | Skills | |
|---|---|---|
| Role | Connection to outside world | Expertise and procedural knowledge |
| Analogy | The hands | The experience |
| What it does | Pull data from APIs, connect to tools | Tell the agent what to do with the data |
| Together | Agent that can connect to anything AND knows how to handle what it finds |
The Emerging Agent Architecture¶
Model (CPU)
↓
Agent Runtime (OS — orchestrates context, tokens in/out)
↓
MCP Servers (Network/IO — external tools and data)
↓
Library of Skills (Applications — domain expertise)
Future: Agent-Created Skills¶
Skills are designed as a concrete step toward continuous learning: - Anything the agent writes down can be used efficiently by future versions - Already possible: Claude creates skills via "Skill Creator" - Goal: Claude on day 30 is much better than Claude on day 1 - Vision: collective, evolving knowledge base curated by people and agents