Agent Skills (Overview) — Claude Docs
by Anthropic (Claude Docs)
The canonical reference for how Agent Skills load, level by level.
Overview
The official Agent Skills overview defines a Skill as a filesystem directory packaging instructions, metadata and optional resources — scripts, templates, reference files — that Claude loads automatically when a request matches. Its centre is the progressive-disclosure table: Level 1 is the YAML frontmatter name and description, always in the system prompt at roughly 100 tokens per Skill; Level 2 is the SKILL.md body, under 5k tokens, read via bash only once the Skill triggers; Level 3 is bundled files and scripts that cost nothing until accessed, with script code never entering context at all, only its output. The page documents the frontmatter contract precisely: `name` at most 64 characters, lowercase letters, numbers and hyphens only, no XML tags and no reserved words 'anthropic' or 'claude'; `description` non-empty, at most 1024 characters, and required to state both what the Skill does and when to use it, because that string is what Claude matches a request against. It then covers each surface and its constraints: the Claude API needs the code execution tool plus the `skills-2025-10-02` beta header and runs Skills in a sandboxed container with no network access and no runtime package installation; Claude Code loads them from `~/.claude/skills/` or `.claude/skills/` with full network access; claude.ai takes per-user zip uploads with no org-wide admin management. It closes on security — treat a Skill like installing software, audit every bundled file, distrust Skills that fetch external URLs — plus the pre-built pptx, xlsx, docx and pdf Skills, the open-source anthropics/skills repository, and the cross-surface sync, sharing-scope and data-retention limitations.
At a Glance
- Topic
- Skills
- Level
- Beginner
- Format
- Documentation
- Cost
- Free
- Duration
- ~15 min read
- Provider
- Anthropic (Claude Docs)
- Hands-on
- No
- Certificate
- None
What You’ll Learn
- ✓The three progressive-disclosure levels and the token cost of each
- ✓The exact SKILL.md frontmatter validation rules for name and description
- ✓Why the description string decides whether a Skill ever triggers
- ✓How Claude reads Skill files and runs bundled scripts through bash
- ✓Which beta header and container parameters the Claude API requires
- ✓Runtime constraints per surface: network access and package installation
- ✓How to audit a third-party Skill before trusting it with your data
Highlights
- •Authoritative and kept current — the reference every Skill author returns to
- •Explicit token-cost table for the three loading levels
- •Precise validation rules you will not get from blog posts
- •Walks a PDF Skill through startup, trigger, load and execute step by step
- •Documents what does NOT work: no cross-surface sync, no admin management on claude.ai
Who It’s For
Best For
- ✓Developers writing or debugging their first Skill
- ✓Engineers deciding between a Skill, an MCP server and a plain prompt
- ✓Security reviewers auditing Skills before an organisational rollout
Prerequisites
- •Basic understanding of Claude, agents and tool use
- •Comfort reading YAML frontmatter and technical documentation
FAQ
What is Agent Skills (Overview) — Claude Docs?
The official Claude documentation on Agent Skills: the three-level progressive-disclosure model and its token costs, the exact SKILL.md frontmatter validation rules, how Skills behave differently on the Claude API, Claude Code and claude.ai, and the security and runtime constraints. The reference every Skill author returns to when a Skill will not trigger.
Is Agent Skills (Overview) — Claude Docs free?
Agent Skills (Overview) — Claude Docs is free to access.
What level is Agent Skills (Overview) — Claude Docs for?
Agent Skills (Overview) — Claude Docs is aimed at a beginner audience. Recommended background: Basic understanding of Claude, agents and tool use, Comfort reading YAML frontmatter and technical documentation.
How long does Agent Skills (Overview) — Claude Docs take?
Expect roughly ~15 min read. Most learners work through it at their own pace.
What will I learn from Agent Skills (Overview) — Claude Docs?
You'll learn: The three progressive-disclosure levels and the token cost of each; The exact SKILL.md frontmatter validation rules for name and description; Why the description string decides whether a Skill ever triggers; How Claude reads Skill files and runs bundled scripts through bash; Which beta header and container parameters the Claude API requires; Runtime constraints per surface: network access and package installation; How to audit a third-party Skill before trusting it with your data.
Topics
Sources
This page was written from 3 sources, 2 on domains other than platform.claude.com.