Introducing Agent Skills
by Anthropic
The primary source on SKILL.md and why progressive disclosure beats always-loaded tools.
Overview
Anthropic's announcement post, published 16 October 2025, introducing Agent Skills — the format that has since become the main way to give Claude reusable, task-specific expertise. A Skill is just a folder containing a SKILL.md file plus any scripts and reference files it needs. The SKILL.md carries YAML frontmatter with a name and a short description stating when the skill applies; Claude reads only that metadata at session start, costing a few dozen tokens per skill, and loads the full body and supporting files only once a task matches. That progressive disclosure is the whole design argument, and it is why the post positions Skills against heavier integration approaches: an MCP server's tool definitions occupy context whether or not you use them. Anthropic states four properties — skills compose and stack, Claude coordinates which ones apply, resources load on demand, and skills can execute bundled code rather than only instruct. Skills run everywhere Claude does: the Claude apps on Pro, Max, Team and Enterprise, Claude Code via its plugin marketplace, the Claude Agent SDK, and the Claude Developer Platform through the Messages API and a /v1/skills endpoint. Anthropic ships built-in skills for Excel, PowerPoint, Word and fillable PDFs, and names Box, Canva, Notion and Rakuten as launch partners. The companion anthropics/skills repository is public and carries working examples you can copy rather than reinvent.
At a Glance
- Topic
- Skills
- Level
- All Levels
- Format
- Guide
- Cost
- Free
- Duration
- ~10 min read
- Provider
- Anthropic
- Hands-on
- No
- Certificate
- None
What You’ll Learn
- ✓Understand what a Skill is: a folder, a SKILL.md, optional scripts
- ✓Explain progressive disclosure and why metadata costs only a few tokens
- ✓Write frontmatter descriptions that tell Claude when a skill applies
- ✓Compare the context cost of Skills against always-loaded MCP tool definitions
- ✓Identify where skills run: Claude apps, Claude Code, Agent SDK, API
- ✓Bundle executable scripts so a skill acts rather than only instructs
- ✓Recognise how multiple skills stack and get coordinated automatically
Highlights
- •The primary source for the SKILL.md format, from the team that defined it
- •Makes the context-economics argument explicitly, which is the actual reason Skills caught on
- •Simon Willison's independent write-up the same day sharpens the comparison against MCP and flags the sandboxing risk
- •Names real launch partners — Box, Canva, Notion and Rakuten — rather than hypothetical use cases
- •Links to the public anthropics/skills repository so you can read working examples, not just prose
- •A ten-minute read that saves reverse-engineering the format from scattered examples
Who It’s For
Best For
- ✓Developers deciding between Skills and MCP for a given integration
- ✓Claude Code users wanting to package a repeatable workflow
- ✓Engineers building on the Claude Agent SDK or Messages API
- ✓Teams standardising how internal know-how reaches an agent
Prerequisites
- •None — the post is readable without prior agent experience
- •Basic familiarity with Markdown and YAML frontmatter helps
FAQ
What is Introducing Agent Skills?
Anthropic's 16 October 2025 announcement of Agent Skills, the folder-plus-SKILL.md format for packaging reusable expertise that Claude loads only when a task matches. It explains progressive disclosure, why that costs far less context than always-loaded tool definitions, where skills run across the Claude apps, Claude Code, the Agent SDK and the API, and which built-in and partner skills shipped at launch. It is the primary source for the format.
Is Introducing Agent Skills free?
Introducing Agent Skills is free to access.
What level is Introducing Agent Skills for?
Introducing Agent Skills is aimed at a all levels audience. Recommended background: None — the post is readable without prior agent experience, Basic familiarity with Markdown and YAML frontmatter helps.
How long does Introducing Agent Skills take?
Expect roughly ~10 min read. Most learners work through it at their own pace.
What will I learn from Introducing Agent Skills?
You'll learn: Understand what a Skill is: a folder, a SKILL.md, optional scripts; Explain progressive disclosure and why metadata costs only a few tokens; Write frontmatter descriptions that tell Claude when a skill applies; Compare the context cost of Skills against always-loaded MCP tool definitions; Identify where skills run: Claude apps, Claude Code, Agent SDK, API; Bundle executable scripts so a skill acts rather than only instructs; Recognise how multiple skills stack and get coordinated automatically.
Topics
Sources
This page was written from 3 sources, 2 on domains other than claude.com.