What are Claude skills? Agent skills explained

A skill is a folder that teaches an AI agent how to do one kind of task well. At minimum it contains a single file, SKILL.md: a short YAML header with a name and a description, followed by plain-language instructions. Bigger skills add reference documents, templates and scripts the agent can run.

---
name: release-notes
description: Write release notes from merged pull requests. Use when the user asks for a changelog or release notes.
---

# Release notes

1. List merged PRs since the last tag.
2. Group them into Added, Changed and Fixed.
3. Write one plain sentence per change.

How agents load skills

Skills use progressive disclosure. At startup the agent only reads each skill's name and description, about 100 tokens per skill. When your request matches a description, it reads the full SKILL.md. Reference files and scripts load only when the instructions point to them. That is why you can install dozens of skills without filling the context window.

• Level 1: name and description, always loaded.
• Level 2: the SKILL.md body, loaded when the skill triggers.
• Level 3: bundled files and scripts, loaded or run only when needed.

Where skills work

Anthropic introduced skills for Claude, then published the format as an open standard at agentskills.io. Today the same SKILL.md runs in Claude Code, the Claude apps, the Claude API, Cursor, OpenAI Codex, Gemini CLI, GitHub Copilot, Windsurf, OpenCode and more than 70 other agents supported by the skills CLI.

Why skills instead of a long prompt

• Reusable: write it once, every session and every teammate gets it.
• Cheap: only the description costs context until the skill is used.
• Composable: a planning skill, a testing skill and a review skill can hand off to each other.
• Portable: one folder works across agents.

In the SkillsBench study (arXiv 2602.12670), curated skills raised agents' average task pass rate by 16.2 percentage points across 86 tasks. Skills the model wrote for itself gave no benefit on average.