Skip to content

What is an agent skill?

Glossary entry. Checked on 19 November 2026.

Agent skill, in plain words

An agent skill is a folder that teaches an AI agent how to do one kind of task. It holds a SKILL.md file (a name, a description of when to use it, and instructions) and can include scripts, templates and reference files. The agent loads it only when a task matches the description.

What is in a skill

Every skill has a SKILL.md file. It starts with a short header, then the instructions:

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

# Release notes

1. List the pull requests merged since the last tag.
2. Group them into Added, Changed and Fixed.
...

In Anthropic's format the name is lower-case letters, numbers and hyphens, up to 64 characters, and the description (up to 1,024 characters) must say both what the skill does and when to use it. A skill folder can also hold more Markdown files, scripts the agent can run, and templates.

Loaded only when needed

Skills are cheap to install because the agent reads them in stages:

  1. At start-up it reads only each skill's name and description.
  2. When your request matches a description, it reads that skill's instructions.
  3. It opens extra files or runs scripts only if the instructions point to them, and only a script's output enters the conversation.
  1. 1Name and descriptionAlways, at start-up

    About 100 tokens per skill

  2. 2SKILL.md instructionsWhen a task matches

    Under 5k tokens

  3. 3Extra files and scriptsOnly if needed

    Nothing until used

How a skill loads. At start-up the agent reads only each skill’s name and description. When a task matches, it reads the SKILL.md instructions. Extra files and scripts load only if the instructions point to them.

Skills and MCP

They solve different problems and work well together. An MCP server gives an agent access: new tools and data, such as your issue tracker. A skill gives it know-how: the steps your team follows, the format you want, which tools to use for a job.

Where skills work

As of 19 November 2026, Anthropic documents skills in the Claude apps (uploaded as a zip on paid plans with code execution on), in Claude Code (folders in ~/.claude/skills/ or a project's .claude/skills/) and in the Claude API. Skills added in one of these places don't appear in the others. Other agents read the same folder format; the agent skills section of the directory shows which ones each skill lists.

Safety

A skill is instructions plus code, so treat installing one like installing software. Anthropic advises using skills only from sources you trust and reading every file first, looking for network calls or file access that don't match what the skill says it does.

Share this definition

Lessons that use this term

Sources

Official documentation, checked on 19 November 2026. Products change: if a step differs, the source has the current version.