AI Agent Skills Explained: SKILL.md, Tools, MCP and How to Write Skills That Don't Waste Tokens

An AI agent skill is a folder with a SKILL.md file that teaches an agent how to do a specific job: a short name and description, step-by-step instructions, and optional scripts, templates and reference files. The agent keeps only each skill's name and description in context, loads the instructions when a task matches, and opens the other files only if it needs them. Written well, skills make an agent more reliable at your tasks for very little cost. Written badly, they fill the context window, slow every step and raise your bill.

Quick answer

• What: packaged know-how for an agent (a procedure, conventions, scripts), stored as files.
• Format: SKILL.md with YAML front matter (name, description) plus Markdown instructions.
• Loading: three levels. Metadata always (about 100 tokens per skill), instructions when triggered (under about 5,000 tokens recommended), extra files only when read.
• Who supports it: Anthropic created the format and released it as an open standard; Claude, Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot, VS Code, Cursor and many more support it.
• Versus tools and MCP: tools and MCP give an agent abilities; skills tell it how to use them for your job.

What agent skills are

Anthropic's documentation describes skills as "reusable, filesystem-based resources that give Claude domain-specific expertise: workflows, context, and best practices that turn a general-purpose agent into a specialist." The open specification at agentskills.io puts it more simply: "a skill is a folder containing a SKILL.md file."

weekly-report/
├── SKILL.md          # required: metadata + instructions
├── scripts/
│   └── build_report.py
├── references/
│   └── metrics.md
└── assets/
    └── template.md

Unlike a prompt, which you repeat in every conversation, a skill loads on demand. Unlike a fine-tuned model, it is plain text you can read, version in Git and change in a minute.

The SKILL.md format

Two fields are required in the front matter. The rules below come from Anthropic's docs and the open specification:

Claude Code adds its own optional fields, such as disable-model-invocation (only you can trigger it), context: fork (run in a sub-agent), paths (only activate for matching files) and model.

How skills load: progressive disclosure

The design that makes skills efficient is called progressive disclosure. Anthropic's overview gives the numbers:

Two details matter for cost:

• Scripts are cheap. When the agent runs a bundled script, "the script's code never loads into the context window." Only the output does. That is why Anthropic calls scripts "far more efficient than having Claude generate equivalent code on the fly."
• Once loaded, a skill stays. Claude Code's docs note that a skill's content stays in context after it is invoked. After the conversation is compacted, re-attached skills share a combined budget of 25,000 tokens, keeping the first 5,000 tokens of each. A bloated skill keeps costing you for the rest of the session.

Skills vs tools vs MCP

People often mix these up. They are layers, not alternatives.

MCP is "an open-source standard for connecting AI applications to external systems," which its site compares to "a USB-C port for AI applications." Anthropic describes skills as complementary to MCP servers: MCP provides the connection, a skill provides the procedure. A skill can, for example, tell the agent to use a specific MCP tool by its fully qualified name, such as GitHub:create_issue, which Anthropic's guidance recommends to avoid "tool not found" errors. For the protocol side in more depth, see MCP vs API.

Skills now work across products. agentskills.io says the format "was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products." The OpenAI Agents SDK, for instance, can mount skills into its shell tool.

Why badly written skills make agents slow and expensive

This is the part most explainers skip. Skills are context, and context is what you pay for, on every turn of the agent loop. Anthropic's own guide opens with the line: "The context window is a public good." Your skill shares it with the system prompt, the conversation, other skills' metadata and the user's request.

Here is how skills go wrong:

1. Vague descriptions trigger the wrong skill, or no skill. The description is what the agent matches against, out of possibly "100+ available Skills." "Helps with documents" will either fire on everything (loading instructions you did not need) or never fire.
2. Giant SKILL.md files. A 1,500-line skill loads all of it whenever it triggers, even if the task needs one section. Every later turn re-sends that text.
3. Explaining what the model already knows. Anthropic's example: a concise PDF instruction is about 50 tokens; the version that first explains what a PDF is runs to about 150. Triple the cost, no gain.
4. Inlining code instead of shipping scripts. If the skill contains a 200-line function the agent must read and retype, you pay for it twice. A script the agent runs costs only its output.
5. Deep chains of references. Anthropic warns that when files reference files that reference files, the agent may only preview them (for example with head -100), so it reads more turns and still misses information.
6. Too many options. "Use pypdf, or pdfplumber, or PyMuPDF..." makes the agent deliberate, and deliberation is tokens.
7. Loading everything up front. The same problem hits tools. Anthropic's engineering team notes that most MCP clients "load all tool definitions upfront directly into context," and in one example moving work into code execution cut usage "from 150,000 tokens to 2,000 tokens."

A simple illustration of why it adds up (arithmetic, not a benchmark): an agent run of 20 turns re-sends its context 20 times. A skill that adds 4,000 unnecessary tokens costs about 80,000 extra input tokens in that one run, before any output. Prompt caching softens the price, but not the slower responses or the crowded context that makes the model less accurate. The broader discipline is context engineering.

How to write a good skill: practical rules

1. Write the description like a search query match

Say what it does and when to use it, in the third person, with the words users actually type. Anthropic warns the description must be third person because it is injected into the system prompt.

# Bad
description: Helps with reports

# Good
description: Builds the weekly sales report from the CRM export, with totals by region and a summary table. Use when the user asks for the weekly report, sales summary or regional totals.

In Claude Code, put the key use case first: the combined description and when_to_use text is cut at 1,536 characters in the skill listing.

2. Keep SKILL.md short; push detail out

• Body under 500 lines (Anthropic and the spec agree).
• Put long references in references/ and link them directly from SKILL.md, one level deep.
• Give long reference files a table of contents so a partial read still shows what is there.

3. Assume the model is smart

Only add what the agent does not already know: your conventions, your systems, your edge cases. Cut background explanations.

4. Prefer scripts for anything deterministic

Validation, file conversion, API calls with fixed parameters, calculations: ship a script and say "Run scripts/validate.py." It is more reliable than generated code and costs only its output. This is the deterministic-first principle from what is agentic AI, applied inside a skill.

5. Set the right degree of freedom

Anthropic's analogy: a narrow bridge needs exact instructions ("Run exactly this script. Do not modify the command"); an open field needs only direction. Fragile, high-stakes steps get low freedom; judgment calls get high freedom.

6. Give one default, not a menu

"Use pdfplumber. For scanned PDFs, use pdf2image with pytesseract instead." One default plus one escape hatch.

7. Add a checklist and a feedback loop for multi-step work

A copyable checklist and a "validate, fix, repeat" step stop the agent skipping validation.

8. Test before you write much

Anthropic recommends building evaluations first: run the agent on real tasks without the skill, note where it fails, write the minimum instructions that fix those failures, and test on every model you plan to use. A skill that works on a large model may need more detail for a small one.

A small, good SKILL.md

---
name: weekly-sales-report
description: Builds the weekly sales report from the CRM CSV export, with totals by region and a summary table. Use when the user asks for the weekly report, sales summary or regional totals.
---

# Weekly sales report

## Steps
1. Find the newest `crm_export_*.csv` in `data/`.
2. Run: `python scripts/build_report.py data/<file> > report.md`
3. If the script prints `MISSING COLUMNS`, stop and tell the user which columns.
4. Fill `assets/template.md` with the totals from `report.md`. Keep regions in the order the script prints them.
5. Check: totals in the summary must equal the sum of regions. If not, rerun step 2.

## Rules
- Exclude rows where `account_type` is `test`.
- Currency is as exported; never convert.
- Metric definitions: see [references/metrics.md](references/metrics.md).

It is short, says when to trigger, pushes the calculation into a script, keeps definitions in a reference file, and includes a self-check.

Security: treat skills like software

Skills can instruct an agent to run code and call tools, so they carry real risk. Anthropic's docs say to use skills "only from trusted sources," warn that a malicious skill "can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose," and flag skills that fetch external URLs as especially risky, because fetched content can contain instructions. Read every file before installing, including scripts and images, and be careful with skills in agents that can reach sensitive data. More on this in AI agent security.

Where skills live

Anthropic notes custom skills do not sync across these surfaces; upload them separately where you need them.

The bottom line

A skill is the cheapest way to make an agent good at your work: plain files, loaded only when needed. The whole benefit depends on discipline. Write a precise description, keep SKILL.md short, move detail into reference files, move anything deterministic into scripts, and test on real tasks. A skill library built that way makes an agent faster and cheaper; one built carelessly quietly taxes every step. If you are building the agent itself, start with how to build an AI agent.