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).
- At start-up the agent reads only each skill's name and description, roughly 100 tokens per skill (source 1).
- When a task matches a description, the agent reads the full SKILL.md. The spec suggests keeping it under 5,000 tokens and 500 lines (source 3).
- Extra files and scripts load only if the instructions point to them. When a script runs, only its output enters the model's context, not its code (source 1).
The file format
A SKILL.md starts with a short header in YAML, then plain Markdown instructions. Two header fields are required (source 3).
- name: up to 64 characters, lowercase letters, numbers and hyphens, matching the folder name.
- description: up to 1,024 characters, saying what the skill does and when to use it.
- Optional fields include license, compatibility, metadata and an experimental allowed-tools list.
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.
- Claude Code: ~/.claude/skills for personal skills, .claude/skills inside a project (source 1). You can also run a skill by typing a slash and its name, and plugins can bundle skills for a whole team (source 5).
- Claude apps and API: upload a zip in claude.ai settings, or use the Skills API. Anthropic also ships ready-made skills for Word, Excel, PowerPoint and PDF files (source 1).
- Codex: .agents/skills in the repository, or $HOME/.agents/skills for personal skills (source 6).
- GitHub Copilot: .github/skills, .claude/skills or .agents/skills in a project, and ~/.copilot/skills or ~/.agents/skills at home (source 7).
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:
- 1. Anthropic: Agent Skills overview: platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- 2. Agent Skills: Overview: agentskills.io
- 3. Agent Skills: Specification: agentskills.io/specification
- 4. Anthropic Engineering: Equipping agents for the real world with Agent Skills: www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- 5. Claude Code Docs: Skills: code.claude.com/docs/en/skills
- 6. ChatGPT: Build skills: learn.chatgpt.com/docs/build-skills
- 7. GitHub Docs: About agent skills: docs.github.com/en/copilot/concepts/agents/about-agent-skills
- 8. Model Context Protocol: Specification (extensions): modelcontextprotocol.io/specification/latest