Teach an agent a job once.

An agent skill is a folder that teaches an AI agent how to do one job, such as writing release notes or filling in a PDF form. At its heart is a SKILL.md file: a name, a short description and step-by-step instructions, plus optional scripts and reference files. The agent sees only the name and description until a task needs the skill. Then it loads the rest.

That on-demand loading is the point. You can give an agent dozens of skills without crowding its context window, and write each procedure once instead of pasting it into every chat. Anthropic created the format and released it as an open standard. As of September 2026, its official showcase lists more than 40 products that support agent skills, including Claude Code, Codex, GitHub Copilot, Cursor and Gemini CLI.

01What is an agent skill?

The folder layout is simple. Only SKILL.md is required.

release-notes/
  SKILL.md          required: metadata and instructions
  scripts/          optional: code the agent can run
  references/       optional: docs the agent reads when needed
  assets/           optional: templates, schemas, sample data

Most skills are just the Markdown file. Add scripts when a step needs to be exact every time, such as validating a form, and reference files when the instructions would otherwise get long.

02How agent skills load: progressive disclosure

Skills are built around a trick called progressive disclosure: the agent pulls in detail only as a task calls for it. It happens in three stages.

1. 01

   Discovery

   At startup, the agent reads only the name and description of every installed skill. The spec puts this at roughly 100 tokens per skill, so a large library stays cheap.

2. 02

   Activation

   When your request matches a description, the agent reads the whole SKILL.md into its context. The spec recommends keeping that body under 5,000 tokens and 500 lines.

3. 03

   Execution

   The agent follows the steps, opening reference files or running scripts only when an instruction calls for them. When it runs a script, usually only the output enters the context, not the code.

This is context engineering built into a file format. Instead of front-loading every procedure you might need, the agent carries a table of contents and fetches the chapter when it needs it. The same discipline matters more once a job is split across several agents instead of one, which our guide to multi-agent systems covers.

03Agent skills vs MCP vs AGENTS.md

People mix these up because all three shape what an agent can do. They solve different problems.

A plain way to hold the difference: an MCP server hands the agent a new tool, and a skill hands it the manual for a job. They combine well. A skill can tell the agent which MCP tools to use and in what order. Our guide to the Model Context Protocol covers the tool side.

AGENTS.md is different again: it holds the rules for one project and loads every time. If a section of your AGENTS.md file only matters for one kind of task, such as cutting a release, it probably wants to be a skill.

04A complete SKILL.md example

Here is a small, complete skill that drafts release notes from git history. The folder name must match the name field.

release-notes/
  SKILL.md
  references/
    STYLE.md

---
name: release-notes
description: Drafts user-facing release notes from the git history since the last tag. Use when the user asks for release notes, a changelog entry or a summary of what shipped.
---

# Release notes

## Steps
1. Find the latest tag with `git describe --tags --abbrev=0`.
2. List the changes since then with `git log <tag>..HEAD --oneline --no-merges`.
3. Group them under three headings: New, Improved and Fixed.
   Skip refactors, tests and dependency bumps unless users will notice them.
4. Rewrite each item for users, not developers, in one sentence.
5. Follow the tone and format in [the style guide](references/STYLE.md).

## Rules
- Never invent a change that is not in the log.
- If a commit message is unclear, list it under "Needs review" instead of guessing.
- Output Markdown only, ready to paste.

# Release notes style
- Lead with the benefit: "You can now export reports as CSV."
- Present tense, second person, no internal jargon.
- One sentence per item. No commit hashes or ticket numbers.

The frontmatter follows the open standard. The name uses only lowercase letters, numbers and hyphens, at most 64 characters. The description can run to 1,024 characters and should say both what the skill does and when to use it. Skills like this pair well with broader automations; see our list of agentic workflows you can run today for ten more jobs worth scripting.

05Which tools support agent skills?

Most major coding agents now read the same SKILL.md format, but they look for skills in different folders. As of September 2026, according to each vendor’s docs:

Each skill gets its own subfolder, such as .agents/skills/release-notes/SKILL.md. Cursor also reads .claude/skills/ and .codex/skills/ for compatibility.

You can let the agent pick a skill automatically, or call it by name. Type /release-notes in Claude Code, Cursor or VS Code, or $release-notes in the Codex CLI. Gemini CLI asks for your confirmation before it activates a skill.

Skills also work outside coding tools. In the Claude apps, you can upload a custom skill as a zip file on paid plans with code execution turned on.

06How to install agent skills safely

A skill is instructions plus code, running with whatever access your agent has. So a malicious skill can do anything your agent can do. The first large audit of public skill registries, published by Snyk in February 2026, shows the risk is real.

Anthropic’s own advice is blunt: “Use Skills only from trusted sources,” meaning ones you wrote or got from Anthropic. Claude Code’s docs add a sharper warning. A skill’s allowed-tools field can pre-approve tools for itself, so review that field in any skill checked into a repository before you run the agent there.

Skills that download content while they run deserve extra care. Even a trustworthy skill can turn hostile if a page it depends on changes later.

07FAQ

Next, pick the MCP servers worth installing first, or learn what the Model Context Protocol does under the hood.