What are Agent Skills?

A skill is written know-how that stays out of the way until it is needed. Instead of pasting the same long instructions into every conversation, you save them once, and the agent pulls them in when the task matches.

How do Agent Skills work?

Skills work through progressive disclosure: the agent sees a little about every skill all the time, and the full details only when it decides a skill is relevant.

1. 1
   Discovery

   At startup, the agent reads only each skill's name and description from its SKILL.md front matter. This costs a few dozen tokens per skill.
2. 2
   Activation

   When a request matches a skill's description, the agent reads the full SKILL.md instructions into its context.
3. 3
   Deeper resources

   If the instructions point to other files, such as reference documents, templates or scripts, the agent reads or runs them only when needed.

Because only descriptions are loaded up front, an agent can have many skills installed without filling its context window. This is context engineering built into the format.

What is inside a skill?

A skill is a folder. The only required file is SKILL.md, which starts with YAML front matter containing a name and a description, followed by instructions in Markdown.

pdf-invoices/
├── SKILL.md          # name, description, and the main instructions
├── reference.md      # detailed field rules, read only when needed
├── template.json     # an output template
└── scripts/
    └── extract.py    # a helper the agent can run

---
name: pdf-invoices
description: Extract vendor, date, totals and line items from PDF invoices
  into our accounting JSON format. Use when the user shares an invoice PDF
  or asks to process invoices.
---
# Processing invoices
1. Run scripts/extract.py on the PDF to get the raw text.
2. Map fields using the rules in reference.md.
...

The description is the most important line in the skill: it is the only thing the agent sees when deciding whether to use it. The free Skills guide has a full chapter on writing descriptions that trigger reliably.

Where did Agent Skills come from?

Anthropic introduced Agent Skills for Claude, Claude Code and its API in October 2025, and published the format as an open standard in December 2025, with the specification at agentskills.io. Many agent tools, including OpenAI Codex, GitHub Copilot, Cursor and Gemini CLI, have adopted it, so a skill written once can work across them.

What is the difference between Agent Skills and MCP?

Skills give an agent knowledge of how to do something; MCP gives it a connection to something. They are complementary.

When should you create a skill?

Create a skill for a task that recurs, has a right way of being done, and needs more than a line or two of instructions. One-off requests are better handled by just asking, and self-contained tasks that produce a lot of intermediate work may suit a subagent better.

• ✓Do: Write the description around when to use the skill, with the words users actually say
• ✓Do: Keep SKILL.md short and move detail into reference files the agent reads on demand
• ✓Do: Include scripts for steps that must be exact, such as parsing or validation
• ✓Do: Test that the skill triggers on the right requests and not on similar wrong ones
• ✕Avoid: Create several skills with overlapping descriptions; the agent will pick inconsistently
• ✕Avoid: Put everything in one giant SKILL.md
• ✕Avoid: Install skills from untrusted sources; they can include scripts the agent will run