Agents Lookup

Learn / Skills

Agent skills explained

What a SKILL.md file is, how agents load skills only when needed, where Claude, Codex and Copilot look for them, and how to write a safe one.

Updated 2026-11-19. "(source N)" refers to the numbered list at the end.

What a skill is

A skill is a folder that teaches an agent how to do one job well. At minimum it holds a file called SKILL.md with a name, a description and written instructions. It can also hold scripts, reference documents and templates (source 2).

Think of it as the onboarding binder you would hand a new employee for one task. How we write refund emails. How we format the weekly sales report. How we check a supplier invoice before paying it.

Where the idea came from

Anthropic introduced the format for Claude and then released it as an open standard called Agent Skills, published at agentskills.io (source 2). Other vendors have since adopted it. OpenAI says its ChatGPT and Codex skills build on the open standard (source 6). GitHub Copilot supports skills in its CLI, its cloud agent and agent mode in several editors (source 7).

How agents load skills

The clever part is that skills load in stages, so you can install many without filling the model's memory. The spec calls this progressive disclosure (source 3).

The file format

A SKILL.md starts with a short header in YAML, then plain Markdown instructions. Two header fields are required (source 3).

Write the description first

The description does the most work. It is what the agent matches your request against, so it must say both what the skill does and when it applies (source 1). Help with invoices is weak. Check supplier invoices against purchase orders before payment; use when the user mentions an invoice, a bill or paying a supplier is strong.

Where skills live

Each tool looks in its own folders, though the file format is shared.

Skills, prompts and MCP

These three are easy to mix up. A prompt is a one-off instruction in a chat. A skill is reusable know-how that loads on its own when relevant (source 1). An MCP server gives the agent new tools or data, such as access to your CRM.

They work well together. When Anthropic launched skills in October 2025, it described them as a way to package procedural knowledge and said it would explore how they can complement MCP servers (source 4). In practice, the skill holds the know-how and the server holds the access. For example, an MCP server lets the agent read orders, and a returns-policy skill tells it how to judge each return. The MCP project is also working on a way to share skills over MCP (source 8).

A small business example

Say your team answers wholesale enquiries. You could write a skill called wholesale-quotes. The description says to use it when someone asks about bulk pricing. The instructions list your price breaks, minimum order sizes and the tone to use. A references folder holds the current price sheet. A short script works out shipping by weight.

Now anyone on the team who uses the agent gets the same, correct answer, and you update one file when prices change.

Treat skills like software

Because a skill can include instructions and code, a malicious one can tell the agent to misuse its tools or send data elsewhere. Anthropic's advice is to use skills only from sources you trust, to read every bundled file before installing, and to be extra careful with skills that fetch content from the web (source 1).

Runtime limits differ by product. On Anthropic's API, skills run in a sandbox with no network access. In Claude Code, they have the same network access as any program on your computer (source 1). Know which you are using before you install a skill someone else wrote.

For skills that change things, such as a deploy or a bulk email, Claude Code lets you set disable-model-invocation in the header so the agent cannot start the skill on its own. Only a person typing the command can run it (source 5).

Sources

Written by Agents Lookup in our own words. Facts come from these pages: