---
title: "Agent skills explained: how SKILL.md packages give agents new abilities"
description: "Agent skills are folders with a SKILL.md file that agents load on demand. Learn the format, progressive disclosure, where skills run, and skills vs MCP."
summary: "An agent skill packages instructions, scripts, and reference files in a folder that an agent loads only when a task calls for it. This explainer covers the SKILL.md format, progressive disclosure, Claude and Claude Code skills, other supporting agents, and how to secure and evaluate skills."
type: "explainer"
canonical_url: "https://theaiengineering.com/articles/agent-skills"
markdown_url: "https://theaiengineering.com/articles/agent-skills.md"
topic: "AI agents"
author: "The AI Engineering Editors"
publisher: "The AI Engineering"
published: "2026-11-17"
updated: "2026-11-17"
keywords: ["agent skills","claude skills","claude code skills","skill.md","agent skills vs mcp"]
citation: "The AI Engineering Editors. \"Agent skills explained: how SKILL.md packages give agents new abilities.\" The AI Engineering, updated Nov 17, 2026. https://theaiengineering.com/articles/agent-skills"
---

# Agent skills explained: how SKILL.md packages give agents new abilities

## TL;DR

- An agent skill is a folder containing a SKILL.md file, whose YAML frontmatter sets a name and a description, plus optional scripts, references, and assets that an agent loads when a task needs them.
- Skills use progressive disclosure: an agent loads only each skill's name and description at startup, reads the SKILL.md body when the skill triggers, and reads or runs bundled files only on demand.
- Anthropic introduced skills in October 2025, published Agent Skills as an open standard in December 2025, and donated the standard to the Agentic AI Foundation in October 2026.
- Claude's apps, Claude Code, the Claude API, and the Claude Agent SDK support skills, and so do Codex, Cursor, GitHub Copilot, VS Code, Gemini CLI, and other agents whose documentation confirms the format.
- Skills can carry executable code, so install them only from trusted sources, audit every bundled file, and run them in a sandbox with limited network and credential access.

Agent skills are folders of instructions, scripts, and reference files that an AI agent loads when a task calls for them, with a `SKILL.md` file as the entry point. A skill turns a general-purpose agent into one that follows your team's procedure for a release, a code review, or a spreadsheet report, without pasting that procedure into every prompt. This explainer covers the format, how agents load skills, where skills run as of November 2026, a worked example, how skills compare with MCP servers and instruction files, and how to secure and evaluate them. For related guides, see our [AI agents](https://theaiengineering.com/topics/ai-agents) hub.

## What are agent skills?

An agent skill is a directory with a `SKILL.md` file, holding YAML frontmatter and Markdown instructions, plus optional scripts, references, and assets that an agent loads on demand.

The [Agent Skills specification](https://agentskills.io/specification) defines the format. Only two frontmatter fields are required: `name`, which must match the folder name, and `description`, which says what the skill does and when to use it. Everything after the frontmatter is free-form Markdown that the agent follows once it activates the skill. The specification recommends, but does not require, three subfolders:

```text
skill-name/
  SKILL.md       required: frontmatter and instructions
  scripts/       optional: code the agent runs
  references/    optional: documentation the agent reads when needed
  assets/        optional: templates, images, and data files
```

| Field | Required | Constraint in the specification |
|---|---|---|
| `name` | Yes | 1-64 characters; lowercase letters, numbers, and hyphens; no leading, trailing, or consecutive hyphens; must match the parent directory |
| `description` | Yes | 1-1,024 characters; what the skill does and when to use it |
| `license` | No | A license name or a reference to a bundled license file |
| `compatibility` | No | Up to 500 characters on environment needs, such as system packages or network access |
| `metadata` | No | A map of string keys to string values, such as an author and a version |
| `allowed-tools` | No | Experimental; a space-separated list of pre-approved tools, with support that varies by agent |

Anthropic adds two rules for skills used with Claude: `name` cannot contain XML tags or the reserved words `anthropic` and `claude`, and `description` cannot contain XML tags.

Anthropic [introduced Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) on October 16, 2025, likening a skill to an onboarding guide for a new hire, and published the format as an open standard in December 2025. On October 22, 2026, Anthropic [donated Agent Skills to the Agentic AI Foundation](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation), the Linux Foundation project that also hosts the Model Context Protocol and AGENTS.md, and said more than 70 agent platforms had integrated the format. The project's [governance document](https://github.com/agentskills/agentskills), adopted on November 4, 2026, names David Soria Parra and Mahesh Murag as Lead Maintainers; the specification is Apache 2.0, and the documentation is CC BY 4.0.

## How agent skills work: progressive disclosure

Agent skills work through progressive disclosure: the agent loads information in stages instead of all at once. At startup it sees only each skill's name and description. When a task matches a description, it reads that skill's `SKILL.md` body. Bundled reference files load only when read, and scripts run without their code entering context.

**Figure 1: Progressive disclosure. Only the top layer costs context for every installed skill; the rest loads when a task needs it.**

Four layers of an agent skill from top to bottom: metadata loaded at startup, the SKILL.md body loaded on trigger, reference files read on demand, and scripts that run outside context.

Layers, top to bottom:

1. **Level 1: metadata**: Every installed skill About 100 tokens each (name, description)
2. **Level 2: instructions**: When the skill triggers Under 5,000 tokens advised (SKILL.md body)
3. **Level 3: references and assets**: Only when the agent reads them No cost until read (references/, assets/)
4. **Level 3: scripts**: Executed, not read Only output enters context (scripts/)

Loaded per task spans Level 2: instructions through Level 3: scripts.

Anthropic's [Agent Skills documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) puts metadata at about 100 tokens per skill and recommends a body under 5,000 tokens; the specification adds a limit of 500 lines for `SKILL.md`. In Anthropic's example, a PDF skill keeps a form-filling guide in `FORMS.md`, and when a user only wants a summary, Claude reads `SKILL.md` and never opens `FORMS.md`.

Scripts are the other route. When the instructions tell the agent to run `scripts/validate.py`, the agent executes it with its shell or code execution tool, and only the output, such as a pass message or a specific error, enters the [context window](https://theaiengineering.com/glossary/context-window). Anthropic's engineering post explains that running a sorting algorithm costs far less than generating sorted output token by token, and that code returns the same result every time.

This design is [context engineering](https://theaiengineering.com/glossary/context-engineering) built into a file format. Every token in the window competes for the model's attention, and research on [context rot](https://theaiengineering.com/glossary/context-rot) shows accuracy falls as inputs grow. A team can install dozens of skills and pay only for a short catalog until one is needed. Our [context engineering guide](https://theaiengineering.com/articles/context-engineering) applies the same principle to tools, memory, and history.

### How an agent activates a skill

Agents use two activation patterns. With file-read activation, the model reads `SKILL.md` with its ordinary file or shell tool, as Claude does with bash in the Claude API's code execution container. With a dedicated tool, the model calls something like Claude Code's `Skill` tool or Gemini CLI's `activate_skill` through ordinary [tool calling](https://theaiengineering.com/glossary/tool-calling), and the agent returns the body, sometimes after asking the user to approve.

**Figure 2: Activating a skill. The SKILL.md body enters context on request, and a bundled script returns only its output.**

Sequence between an agent runtime, the model, and a skill folder: catalog sent, model asks to read SKILL.md, body returned, model asks to run a script, only the script output returned.

Steps:

1. Agent runtime → Model: skill catalog + user request
2. Model → Agent runtime: tool call: read SKILL.md
3. Agent runtime → Skill folder: read file
4. Agent runtime → Model: SKILL.md body
5. Model → Agent runtime: tool call: run scripts/check.py
6. Agent runtime → Skill folder: execute script
7. Agent runtime → Model: script output only
8. Model → Agent runtime: answer that follows the skill

Most agents leave the decision to the model rather than matching keywords, according to the agentskills.io [client implementation guide](https://agentskills.io/client-implementation/adding-skills-support). Users can also force a skill: `/skill-name` in Claude Code and Cursor, `$skill-name` in Codex, and `@skill-id` in OpenCode.

## A worked example: SKILL.md and folder layout

A useful skill captures a procedure your team repeats and the model cannot infer. The example below reviews PostgreSQL migrations for operations that block writes or rewrite tables. It has a `SKILL.md` with frontmatter and a short workflow, a script the agent runs, and a reference file it reads only when a finding needs explanation.

```text
reviewing-migrations/
  SKILL.md
  scripts/
    check_migration.py
  references/
    locking-rules.md
```

```markdown
---
name: reviewing-migrations
description: Reviews PostgreSQL schema migration files for operations that lock tables, rewrite data, or break running application code. Use when the user adds or edits a migration, asks whether a migration is safe to deploy, or mentions ALTER TABLE, new indexes, or zero-downtime deploys.
license: Apache-2.0
metadata:
  owner: platform-team
  version: "1.2"
---

# Reviewing migrations

## Rules

- Flag CREATE INDEX on an existing table without CONCURRENTLY: it blocks writes until the build finishes.
- Flag ADD COLUMN with a volatile default such as clock_timestamp(): it rewrites the table and its indexes.
- Never run a migration against a real database during review.

## Workflow

1. List the migration files changed on this branch: `git diff --name-only origin/main -- migrations/`
2. Run the checker on each file and read its output: `python scripts/check_migration.py <file>`
3. For each finding, explain the risk in one sentence and propose a safer sequence.
   For lock levels and safe patterns, read [references/locking-rules.md](references/locking-rules.md).
4. End with one verdict: SAFE, SAFE WITH CHANGES, or UNSAFE.
```

| Part | Why it is written this way |
|---|---|
| `name` | Matches the folder, uses the gerund form Anthropic's [authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) suggest, and avoids the reserved words |
| `description` | States the task, then the situations and terms that should trigger it, including `ALTER TABLE`, which a user may type without saying "migration" |
| Rules | Sit near the top as plain statements; both match the [PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-createindex.html), where a standard `CREATE INDEX` locks out writes and a volatile column default rewrites the table |
| Workflow | Tells the agent to run the checker instead of reading it, and links the reference file one level deep from `SKILL.md` |
| Script | Does the deterministic part, handles its own errors, and prints specific messages the agent can act on |

## How the description decides when a skill triggers

A skill's name and description are all the model sees of it before deciding whether to load it, so the description controls triggering. The model compares each request against every description in its catalog. A vague description means the skill never loads, and an overly broad one means it loads for unrelated work and wastes context.

Agents also tend to skip skills for simple tasks they can handle alone; the agentskills.io guide on [optimizing descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) notes that a one-step request may not trigger a matching skill. And catalogs have budgets. Claude Code caps its skill listing at 1% of the model's context window by default, limits each entry to 1,536 characters, and drops descriptions of the least-used skills first when the listing overflows. Codex caps its list at 2% of the context window, or 8,000 characters when it doesn't know the window size.

### Tips for writing descriptions

- Say what the skill does, then when to use it, in one or two sentences. Anthropic recommends the third person, because the description is inserted into the system prompt.
- List the terms and file types people actually type, including indirect phrasings, and say the skill applies even when the user doesn't name the domain.
- Lead with the main use case, since long listings get truncated.
- If near-miss requests trigger the skill, say what it does not cover.
- Stay under 1,024 characters; descriptions tend to grow during tuning.
- Make risky skills manual. In Claude Code and Cursor, `disable-model-invocation: true` keeps a deploy skill from loading unless a user types it.

### Tips for writing instructions

- Write only what the model lacks. Anthropic's best practices treat the context window as shared and assume the model knows general concepts, so skip explaining what a PDF is.
- Use exact commands for fragile operations, such as migrations, and heuristics where many approaches work, such as code review.
- Link every reference file directly from `SKILL.md`, and give reference files over 100 lines a table of contents so a partial read still shows their scope.
- State whether the agent should execute a script or read it as documentation.
- Write MCP tools as `ServerName:tool_name` so the agent finds the right one among several servers.
- Put critical rules first. After compaction, Claude Code re-attaches only the first 5,000 tokens of each invoked skill.
- Move rules that must always hold out of the skill and into a mechanism such as a Claude Code hook, since the model applies a skill with judgment.

## Claude skills: where skills run in Claude's apps and API

Claude skills run in Claude's apps, including claude.ai and Cowork; in Claude Code; on the Claude API; and in the Claude Agent SDK. Anthropic's pre-built skills for PowerPoint, Excel, Word, and PDF work in the apps and on the API. Custom skills work on every surface, but uploads to claude.ai and to the API don't sync.

| Surface | How skills are added | Runtime, as documented in November 2026 |
|---|---|---|
| Claude apps (claude.ai, desktop, Cowork) | Pre-built document skills are active by default; custom skills upload as ZIP files under Customize > Skills | Requires code execution; network access depends on user and admin settings |
| Claude API | `container.skills` alongside the code execution tool; custom skills uploaded through `/v1/skills` | Sandboxed container with no network access and no runtime package installation |
| Claude Code | Folders in `~/.claude/skills/`, `.claude/skills/`, managed settings, or plugins | The same network access as any program on the user's machine |
| Claude Agent SDK | The same folders, discovered through the SDK's setting sources | Same behavior as Claude Code, driven from your code |

### Claude apps

In claude.ai, the desktop app, and Cowork, Claude uses the pre-built document skills when it creates documents. Custom skills are listed for the Pro, Max, Ultra, Team, and Enterprise plans with code execution turned on, and Team and Enterprise owners can provision skills for every member. Claude Enterprise organizations can also turn on content scanning for custom skills uploaded in claude.ai and Cowork.

### Claude API

On the API, a request lists skills in the `container` parameter and includes the code execution tool, whose container the skills run in. Anthropic's skills use IDs such as `pptx`, `xlsx`, `docx`, and `pdf` with date-based versions; custom skills get generated IDs and version IDs. The [skills guide](https://platform.claude.com/docs/en/build-with-claude/skills-guide) allows up to 20 skills per request and custom uploads under 30 MB, and uploaded skills are shared across the workspace.

```json
{
  "model": "claude-opus-5-5",
  "max_tokens": 4096,
  "container": {
    "skills": [{ "type": "anthropic", "skill_id": "xlsx", "version": "latest" }]
  },
  "tools": [{ "type": "code_execution_20250825", "name": "code_execution" }],
  "messages": [{ "role": "user", "content": "Build a quarterly revenue workbook with a chart from the attached CSV." }]
}
```

Pin an exact version in production, because `latest` moves when Anthropic updates a skill. The same API behavior applies on Claude Platform on AWS and on Microsoft Foundry deployments hosted on Anthropic. Managed Agents attach skills through an agent's `skills` array or load them from a GitHub repository mounted on the session.

### Claude Code skills

Claude Code skills are folders on disk, not uploads. Personal skills live in `~/.claude/skills/` and work in every project, project skills live in `.claude/skills/` and ship with the repository, organizations deploy skills through managed settings, and plugins add namespaced skills such as `/plugin-name:skill-name`. When names collide, enterprise beats personal, and personal beats project.

The [Claude Code skills documentation](https://code.claude.com/docs/en/skills) adds behaviors beyond the specification:

- Custom commands are merged into skills. A `.claude/commands/deploy.md` file still works, and a folder at `.claude/skills/deploy/` creates the same `/deploy` command.
- `disable-model-invocation: true` makes a skill manual-only, and `user-invocable: false` hides it from the `/` menu so only Claude loads it.
- Fields such as `context: fork` (run in a subagent), `paths` (activate only for matching files), `hooks`, and `model` are Claude Code extensions.
- A line such as `` !`git diff HEAD` `` runs before Claude sees the skill and is replaced by its output.
- Edits to skill folders apply without a restart, and sessions signed in with a claude.ai account download that account's enabled skills.

Those extensions don't carry over to claude.ai uploads or the Skills API, which accept only the specification's six fields and reject other keys with an error.

### Claude Agent SDK

The [Agent SDK](https://code.claude.com/docs/en/agent-sdk/skills) loads skills from the same folders as Claude Code. It has no API for registering a skill in code; you create the folder, point the session at it, and choose which skills Claude may invoke.

```python
from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    cwd="/path/to/project",               # .claude/skills/ here or in a parent directory
    setting_sources=["user", "project"],  # where skills are discovered
    skills="all",                         # or a list of skill names, or [] for none
    allowed_tools=["Read", "Grep", "Bash"],
)
```

If you set `setting_sources` explicitly and leave out `"user"` and `"project"`, the SDK loads no skills. The session's `init` message lists the user-invocable skills it found, which is the quickest way to confirm a skill loaded.

## Other agents that support agent skills

As of November 2026, the documentation for OpenAI Codex and ChatGPT, Cursor, GitHub Copilot, VS Code, Gemini CLI, Google Antigravity, OpenCode, and goose confirms support for `SKILL.md` skills. Most scan a tool-specific folder plus the shared `.agents/skills/` path, so one skill folder can serve several agents. Folder locations, invocation syntax, and extra frontmatter fields differ by tool.

| Agent | Project skills | Personal skills | How a skill loads |
|---|---|---|---|
| [Codex and ChatGPT](https://learn.chatgpt.com/docs/build-skills) | `.agents/skills/`, from the working directory up to the repository root | `~/.agents/skills/`; admins can use `/etc/codex/skills` | When relevant, or `$skill-name` and `/skills` in Codex, `@` in ChatGPT |
| [Cursor](https://cursor.com/docs/context/skills) | `.agents/skills/`, `.cursor/skills/`; also reads `.claude/skills/` and `.codex/skills/` | `~/.agents/skills/`, `~/.cursor/skills/` | When relevant, or `/skill-name` in Agent chat |
| [GitHub Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) | `.github/skills/`, `.claude/skills/`, `.agents/skills/` | `~/.copilot/skills/`, `~/.agents/skills/` | When relevant, in the Copilot CLI, cloud agent, code review, and IDE agent mode |
| [VS Code](https://code.visualstudio.com/docs/copilot/customization/agent-skills) | `.github/skills/`, `.claude/skills/`, or `.agents/skills/`, depending on the agent | `~/.copilot/skills/`, `~/.claude/skills/`, or `~/.agents/skills/` | Three-level loading, when relevant or invoked |
| [Gemini CLI](https://geminicli.com/docs/cli/skills/) | `.gemini/skills/` or `.agents/skills/` | `~/.gemini/skills/` or `~/.agents/skills/` | The model calls `activate_skill`, and the user approves |
| [Google Antigravity](https://antigravity.google/docs/skills) | `.agents/skills/` | `~/.gemini/config/skills/` | When relevant |
| [OpenCode](https://opencode.ai/docs/skills/) | `.opencode/skills/`, `.claude/skills/`, `.agents/skills/` | `~/.config/opencode/skills/`, `~/.claude/skills/`, `~/.agents/skills/` | The model calls the `skill` tool, or the user writes `@skill-id` |
| [goose](https://goose-docs.ai/docs/guides/context-engineering/using-skills/) | `.agents/skills/`; also `.goose/skills/` and `.claude/skills/` | `~/.agents/skills/` | When relevant |

The specification defines what goes inside a skill folder, not where it lives. The agentskills.io implementation guide calls `.agents/skills/` the convention that emerged for sharing skills across clients. On Google's side, Antigravity CLI replaced Gemini CLI for unpaid-tier and Google One users on June 18, 2026.

Portability has limits beyond paths. Cursor adds `paths`, `icon`, and `color` fields, Codex reads optional settings from `agents/openai.yaml`, and Claude Code adds the fields listed above. Runtimes differ too: a script that installs a package works in Claude Code and fails on the Claude API, which has no network access. State requirements in the `compatibility` field and test a shared skill in each agent your team uses. Our [AI coding agents comparison](https://theaiengineering.com/articles/ai-coding-agents) and [AI coding tools directory](https://theaiengineering.com/platforms/ai-coding-tools) cover the agents themselves.

## Agent skills vs MCP servers, AGENTS.md, system prompts, subagents, and plugins

Skills package procedures that load on demand, while the other mechanisms connect tools, set standing context, isolate work, or distribute bundles. MCP servers expose external tools and run their own code. AGENTS.md, CLAUDE.md, and system prompts load in full every session. Subagents work in separate context windows. Plugins package skills together with other components.

| Mechanism | What it is for | What loads into context | Who executes code |
|---|---|---|---|
| Agent skill | Procedures, domain knowledge, and helper scripts for specific tasks | Name and description at startup; the body when triggered; files when read | The agent, through its own shell or code execution tool |
| MCP server | Access to external tools, data, and actions | Tool definitions, or only tool names and server instructions where the client uses tool search | The server process, local or remote |
| AGENTS.md or CLAUDE.md | Standing project facts: commands, layout, conventions | The whole file, every session | No code; the agent may run commands the file mentions |
| System prompt | Role, rules, and output format for every turn | All of it, on every request | No code |
| Subagent | Isolating a subtask from the main conversation | The parent sees the subagent's description and its returned summary | The subagent, with the tools it is granted |
| Plugin | Packaging and distributing skills, subagents, hooks, and MCP servers | Descriptions of its model-invocable skills and agents every turn; the rest as components run | Its components: hooks by the agent runtime, MCP servers as processes, scripts by the agent |

### Skills vs MCP servers

An [MCP server](https://theaiengineering.com/glossary/mcp-server) handles access: it exposes tools, resources, and prompts over the protocol, and its own process executes each call. A skill handles method: which tools to call, in what order, and with which checks. Anthropic's article on [skills and MCP](https://claude.com/resources/articles/extending-claude-capabilities-with-skills-mcp-servers) puts it this way: if you are explaining how to do something, write a skill; if the agent needs to reach a system, connect an MCP server. One skill can coordinate several servers. Our [MCP explainer](https://theaiengineering.com/articles/what-is-model-context-protocol) covers the protocol side.

Context cost differs too. Anthropic's article notes that a connected server's tool definitions load upfront, while skills load on demand. Claude Code narrows that gap with [tool search](https://code.claude.com/docs/en/mcp), on by default, which loads only tool names and server instructions at session start.

### Skills vs AGENTS.md and CLAUDE.md

[AGENTS.md](https://theaiengineering.com/glossary/agents-md) and CLAUDE.md load at the start of every session, so they suit short facts that every task needs: build and test commands, directory layout, and conventions. Claude Code's documentation suggests turning a section of CLAUDE.md into a skill once it grows from a fact into a procedure, because a skill's body costs almost nothing until it is used. A repository can keep both: a short instruction file and a few skills for the long workflows.

### Skills vs system prompts

A [system prompt](https://theaiengineering.com/glossary/system-prompt) is sent with every request and fixes the model's role and rules. Skill metadata lives inside it, but skill bodies join the conversation only when needed. Skills also bring files and code, which a prompt cannot carry.

### Skills vs subagents

A [subagent](https://theaiengineering.com/glossary/subagent) runs a subtask in its own context window and returns a summary, while a skill adds instructions to the current context. The two combine. In Claude Code, `context: fork` runs a skill as a subagent's task, so a research or audit procedure explores in a separate window and only its findings return.

### Skills vs plugins

A plugin is a distribution unit rather than a capability. In Claude Code, a plugin is a directory with a `.claude-plugin/plugin.json` manifest that can bundle skills, subagents, hooks, and MCP servers, installed from a marketplace. Plugin skills are namespaced, so they never collide with your own. Codex, goose, and Antigravity CLI also load skills that ship inside plugins.

## Agent skills security: what to check before you install one

A skill is code and instructions from someone else, running with your agent's permissions. Anthropic's documentation says to use skills only from trusted sources, meaning ones you wrote or obtained from Anthropic, because a malicious skill can direct the agent to misuse tools, run code, or exfiltrate data. Review, restrict, and sandbox every skill you install.

The instructions themselves are an attack surface. A skill's body is text the model treats as guidance, which makes it a [prompt injection](https://theaiengineering.com/glossary/prompt-injection) channel with a privileged position, and bundled scripts run with whatever access the agent has. Anthropic's documentation also flags skills that fetch content from external URLs, because fetched pages can carry malicious instructions, and warns that a trusted skill can turn unsafe when its dependencies change.

Review and contain each skill before your agent uses it:

- **Read every file before installing.** Check `SKILL.md`, scripts, reference files, and images for unexpected network calls, file access, or operations that don't match the skill's purpose.
- **Pin and diff.** Pin skill versions and review the diff on every update, as you would a dependency upgrade.
- **Treat cloned repositories as untrusted.** The agentskills.io implementation guide recommends loading project-level skills only from folders the user has marked as trusted. Claude Code applies a project skill's `allowed-tools` even in a non-interactive `-p` run in a folder you never trusted, so review project skills before pointing an agent at a fresh clone.
- **Sandbox execution.** Run agents with third-party skills in an [agent sandbox](https://theaiengineering.com/glossary/agent-sandbox) that limits files, network hosts, and credentials. The Claude API's container has no network access, while Claude Code skills have the same network access as any program on your machine. Our [agent infrastructure directory](https://theaiengineering.com/platforms/agent-infrastructure) lists sandbox providers.
- **Restrict with permissions.** Claude Code can deny the `Skill` tool entirely or per skill with rules such as `Skill(deploy *)`, and the `disableSkillShellExecution` setting blocks the shell commands skills inject. Grant `allowed-tools` narrowly, since it pre-approves tool use.
- **Use organization controls.** Claude Enterprise can scan custom skills uploaded in claude.ai and Cowork for malicious content; that scanning does not cover the Skills API or the Claude Console.

For regulated teams, note that Agent Skills on Anthropic's platform were not eligible for zero data retention as of November 2026.

## How to evaluate an agent skill

Evaluate a skill on two questions. Does it trigger on the requests it should and stay out of the rest? Does it produce better results than the agent without it, at an acceptable cost in tokens and time? Answer both with labeled test sets, repeated runs, and a baseline without the skill, and retest when the skill or model changes.

### Test triggering

The agentskills.io method uses about 20 realistic prompts: 8 to 10 that should trigger the skill and 8 to 10 that should not. The most useful negatives are near misses that share keywords with the skill but need something else, such as a request to edit Excel formulas for a CSV analysis skill. Because model behavior varies, run each prompt three times, compute a trigger rate, and count a should-trigger prompt as passing above 0.5. To avoid overfitting the description, tune it on about 60% of the prompts and choose the version that scores best on the held-out 40%.

Detection depends on the agent. In Claude Code, a skill triggered when the JSON output contains a `Skill` tool call with that skill's name, and skills shipped in plugins can be tested with `claude plugin eval` and a `tool_used: Skill` grader.

### Test outcomes

For output quality, the agentskills.io [evaluation guide](https://agentskills.io/skill-creation/evaluating-skills) stores test cases in `evals/evals.json` inside the skill, each with a prompt, an expected output, optional input files, and assertions. Run every case with the skill and without it, then grade each assertion with evidence: scripts for mechanical checks such as valid JSON, and an [LLM-as-a-judge](https://theaiengineering.com/glossary/llm-as-a-judge) for qualities a script can't check. Compare the change in pass rate against the added tokens and time.

Anthropic's best practices add three habits: write evaluations before extensive instructions, start with at least three scenarios drawn from real failures, and test with every model the skill will run on. Anthropic's `skill-creator` skill automates much of this loop, and the methods carry over from our guide to [AI agent evaluation](https://theaiengineering.com/articles/ai-agent-evaluation).

### Watch real usage

Every installed skill costs catalog tokens on every turn, used or not. In Claude Code, `/skill-doctor` reports each skill's context cost and usage, which shows which skills to rewrite or remove.

## Where to go next

Skills sit on top of the agent loop described in our explainer on [what AI agents are](https://theaiengineering.com/articles/what-are-ai-agents): they change what the model knows at each step, not how the loop runs. To see where a skill catalog fits in a working loop, follow the guide on [how to build an AI agent](https://theaiengineering.com/articles/how-to-build-an-ai-agent), then add one skill and test it with the evals above.

## Frequently asked questions

### What is a SKILL.md file?

A SKILL.md file is the required entry point of an agent skill. It starts with YAML frontmatter containing a name, which must match the skill's folder name, and a description of what the skill does and when to use it. The Markdown body that follows holds the instructions the agent reads when the skill triggers, and it can point to scripts and reference files stored in the same folder.

### What is the difference between agent skills and MCP?

An MCP server gives an agent access to external tools and data through a protocol, and the server runs the tool code. An agent skill gives the agent procedural knowledge: instructions, reference files, and scripts the agent runs itself. A skill costs little context until it triggers. The two combine well, because a skill can describe how to use an MCP server's tools to complete a workflow.

### Can I use Claude skills in Codex, Cursor, or GitHub Copilot?

Usually, yes. Codex, Cursor, GitHub Copilot, VS Code, Gemini CLI, and other agents implement the open Agent Skills format, so a skill written for Claude works elsewhere if it sticks to the specification's fields. Each tool scans its own folders, though many read .agents/skills and some read .claude/skills. Fields only Claude Code understands, such as context: fork, may do nothing in other agents.

### Where do I put skills in Claude Code?

Put personal skills in ~/.claude/skills/<skill-name>/SKILL.md, which makes them available in every project on your machine, and project skills in .claude/skills/<skill-name>/SKILL.md, which you commit so the whole team gets them. Organizations can deploy skills through managed settings, and plugins ship skills that run as /plugin-name:skill-name. Claude Code picks up edits to existing skill directories without a restart.

### What is the difference between skills and slash commands in Claude Code?

Claude Code merged custom slash commands into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and existing command files keep working. A skill adds a folder for supporting files and lets Claude load it automatically when its description matches the task. Setting disable-model-invocation: true makes a skill manual-only, like a classic command.

### Are agent skills safe to install?

A skill is only as safe as its source. Skills contain instructions and can bundle scripts, so a malicious skill can direct an agent to run code, misuse tools, or send data elsewhere. Anthropic recommends using only skills you wrote or obtained from trusted sources, auditing every bundled file, and treating installation like installing software. Run skills in a sandbox with restricted network and credential access.

## Terms in this guide

- [Context window](https://theaiengineering.com/glossary/context-window): A context window is the maximum number of tokens a language model can take into account in a single request, including the system prompt, conversation history, tool results, and the generated output.
- [Context engineering](https://theaiengineering.com/glossary/context-engineering): Context engineering is the practice of selecting, structuring, and pruning all the information placed in an LLM's context window at each step, including instructions, retrieved data, tool results, and memory.
- [Context rot](https://theaiengineering.com/glossary/context-rot): Context rot is the decline in a language model's accuracy and recall as the number of tokens in its input grows, even when the information a task needs is present in the context.
- [Tool calling](https://theaiengineering.com/glossary/tool-calling): Tool calling is an LLM capability in which the model, given a list of tool definitions, outputs a structured request naming a tool and its arguments, which the application executes and returns.
- [MCP server](https://theaiengineering.com/glossary/mcp-server): An MCP server is a program that exposes tools, resources, and prompts to AI applications through the Model Context Protocol, running locally over stdio or remotely over Streamable HTTP.
- [AGENTS.md](https://theaiengineering.com/glossary/agents-md): AGENTS.md is an open format for a plain Markdown file, placed at a repository's root and optionally in subdirectories, that gives AI coding agents project instructions such as build commands, test commands, and conventions.
- [System prompt](https://theaiengineering.com/glossary/system-prompt): A system prompt is the set of developer-written instructions sent to a language model ahead of the conversation, defining its role, rules, output format, and tool use for every turn that follows.
- [Subagent](https://theaiengineering.com/glossary/subagent): A subagent is an AI agent that another agent starts for one subtask, running in a separate context window with its own instructions and tools, and returning only a condensed result.
- [Prompt injection](https://theaiengineering.com/glossary/prompt-injection): Prompt injection is an attack in which text supplied to a large language model, typed by a user or hidden in content the model reads, alters the application's intended behavior or output.
- [Agent sandbox](https://theaiengineering.com/glossary/agent-sandbox): An agent sandbox is an isolated execution environment in which an AI agent runs code, shell commands, or a browser, with enforced limits on the files, network hosts, and credentials it can reach.
- [LLM-as-a-judge](https://theaiengineering.com/glossary/llm-as-a-judge): LLM-as-a-judge is an evaluation method in which a language model scores or compares the outputs of an LLM application against a rubric, a reference answer, or another response, replacing or supplementing human graders.

## Related guides

- [What are AI agents? How agents work and when to use one](https://theaiengineering.com/articles/what-are-ai-agents): AI agents are LLM systems that call tools in a loop until a task is done. Learn how the loop works, agents vs agentic AI, examples, failure modes, and limits.
- [What is context engineering? A practical guide for AI agents](https://theaiengineering.com/articles/context-engineering): Context engineering is the practice of choosing what fills an LLM context window. Learn its components, why context rot happens, and how to measure results.
- [What is the Model Context Protocol (MCP)? How it works](https://theaiengineering.com/articles/what-is-model-context-protocol): The Model Context Protocol (MCP) is an open standard for connecting AI apps to tools and data. Learn its architecture, transports, tool calls, and security.
- [AI coding agents: how they work and how the major tools compare](https://theaiengineering.com/articles/ai-coding-agents): AI coding agents compared: how they differ from autocomplete, the four main categories, a comparison table of major tools, and how to evaluate and secure them.

Part of the [AI agents](https://theaiengineering.com/topics/ai-agents) topic hub.

## Cite this guide

The AI Engineering Editors. "Agent skills explained: how SKILL.md packages give agents new abilities." The AI Engineering, updated Nov 17, 2026. https://theaiengineering.com/articles/agent-skills

- Title: Agent skills explained: how SKILL.md packages give agents new abilities
- Author: The AI Engineering Editors
- Publisher: The AI Engineering
- Published: 2026-11-17
- Updated: 2026-11-17
- URL: https://theaiengineering.com/articles/agent-skills
- Markdown: https://theaiengineering.com/articles/agent-skills.md

To cite one section, link to its anchor:

- [What are agent skills?](https://theaiengineering.com/articles/agent-skills#what-are-agent-skills)
- [How agent skills work: progressive disclosure](https://theaiengineering.com/articles/agent-skills#how-agent-skills-work-progressive-disclosure)
- [A worked example: SKILL.md and folder layout](https://theaiengineering.com/articles/agent-skills#a-worked-example-skillmd-and-folder-layout)
- [How the description decides when a skill triggers](https://theaiengineering.com/articles/agent-skills#how-the-description-decides-when-a-skill-triggers)
- [Claude skills: where skills run in Claude's apps and API](https://theaiengineering.com/articles/agent-skills#claude-skills-where-skills-run-in-claudes-apps-and-api)
- [Other agents that support agent skills](https://theaiengineering.com/articles/agent-skills#other-agents-that-support-agent-skills)
- [Agent skills vs MCP servers, AGENTS.md, system prompts, subagents, and plugins](https://theaiengineering.com/articles/agent-skills#agent-skills-vs-mcp-servers-agentsmd-system-prompts-subagents-and-plugins)
- [Agent skills security: what to check before you install one](https://theaiengineering.com/articles/agent-skills#agent-skills-security-what-to-check-before-you-install-one)
- [How to evaluate an agent skill](https://theaiengineering.com/articles/agent-skills#how-to-evaluate-an-agent-skill)
- [Where to go next](https://theaiengineering.com/articles/agent-skills#where-to-go-next)
- [Frequently asked questions](https://theaiengineering.com/articles/agent-skills#faq)
