Agent Skills documentation
Agent Skills documentation
Worth reading when writing your own skills; the content is fairly technical.
Explains what a skill is, the SKILL.md folder structure, and how Claude loads skills automatically when needed.
Overview
This is Anthropic's official documentation page explaining Agent Skills: modular capabilities that help Claude do specialized work well. Each skill packages instructions, metadata and optional resources such as scripts or templates, and Claude uses it automatically when your request matches.
The page describes a "progressive disclosure" mechanism with three levels: metadata is always loaded, the instructions are loaded only when the skill is triggered, and reference files and scripts are read or run only when needed. This lets you install many skills without using up context.
The documentation also states where skills work (Claude API, Claude Code, Claude.ai), the limits of each platform and security notes. This is the first page to read before a business decides to bring skills into its workflows.
Highlights
Loaded on demand
When not in use, each skill takes only about 100 tokens for its name and description; the instructions enter context only when triggered.
Scripts run outside context
Claude runs scripts via bash and receives only the output, so processing is stable and saves tokens.
Prebuilt office skills
PowerPoint, Excel, Word and PDF skills are available on the Claude API and Claude.ai.
Clear rules for SKILL.md
name is at most 64 characters, lowercase letters, numbers and hyphens only; description is non-empty and at most 1024 characters.
A different sharing model per platform
Claude.ai is personal use only, the API is shared across the whole workspace, Claude Code is per user or per project.
What it's for
Automatic reports via the API
A dev team calls the Claude API with the xlsx or pptx skill to generate reports and slides from internal data.
Standardizing department processes
Package processes such as drafting template contracts or checking records into a skill so Claude follows them consistently.
Assessing risk before deployment
The IT department uses the security section of the documentation as a checklist for vetting external skills.
Choosing the right platform
Managers compare network limits and sharing scope to choose whether to use skills on Claude.ai, the API or Claude Code.
How to use it
- 1
Grasp the concept
Read the section explaining what a skill is and the three levels of loading content to understand how Claude uses skills.
- 2
Choose a platform
Decide whether you will use skills on the Claude API, Claude Code or Claude.ai, since each has different limits.
- 3
Write SKILL.md
Create a file with YAML frontmatter containing name and description, followed by step-by-step instructions and examples.
- 4
Put the skill in your environment
Claude Code places skills in ~/.claude/skills/ or .claude/skills/; Claude.ai uploads a zip file in Settings > Features; the API uploads through the /v1/skills endpoints.
- 5
Security review
Review every file in the skill, especially scripts and external network calls, before real use.
Video guides
Claude Agent Skills Explained
Anthropic
The Only Claude Skills Guide You Need (Beginner to Expert)
Kenny Liao
Anthropic Agent Skills Explained: Build Specialized Claude Agents (Complete Tutorial)
Prompt Circle AI
Real-world example
Suppose a furniture store chain with a 3-person dev team wants to automate monthly sales report slides. The team reads the Agent Skills documentation and realizes that on the Claude API, skills run in a container with no network, so they decide to include the data in the request instead of letting the skill call an outside API. They use the prebuilt pptx skill to create slides, and also write a custom skill describing the layout, colors and file naming standards of the company, then upload it to the workspace so the whole team can use it.
Tips & notes
The description decides everything
Claude compares your request with the description to pick a skill, so state clearly what the skill does and when to use it.
Skills do not sync automatically
Skills uploaded to Claude.ai are not on the API and vice versa; Claude Code uses its own directory, so you must manage each place.
Treat skills like software
Use only skills you wrote yourself or that come from Anthropic; unknown skills must be checked carefully because they can lead to data leaks.
Split out reference files
Put long documents in separate files; Claude reads them only when needed, so they cost no tokens if unused.
FAQ
How is a skill different from a prompt?
A prompt is an instruction within one conversation, while a skill is saved and loaded automatically when relevant, so you do not have to repeat instructions.
Which Claude.ai plans can use custom skills?
According to the documentation, custom skills are available on Pro, Max, Team and Enterprise plans with code execution enabled.
Do skills on the API have Internet access?
No. On the Claude API, skills run in a sandbox with no network and cannot install extra packages at runtime.
Is skill data covered by ZDR?
The documentation states Agent Skills are not covered by the Zero Data Retention agreement and are retained under standard policy.
Useful links
Want to apply this in your business?
2dm looks at your workflows, picks the right tools and sets them up with your team. The first call is free.
Same topic
Anthropic Skills
4.5
Anthropic's official repository of example skills for Claude: each skill is a folder of instructions and resources that helps Claude do one specific kind of task well.
Skills in Claude Code
4.0
How to create, install and use your own skills for Claude Code, on your machine or per project.
Introducing Agent Skills (article)
4.0
An article by Anthropic's engineering team on why Agent Skills exist and how they are designed.