What are AI agent skills? How SKILL.md works

AI agent skills are reusable folders that teach an AI agent how to perform a particular kind of work. A skill contains a SKILL.md file with metadata and instructions, and it may also carry scripts, reference material, templates, or other assets. The agent discovers the skill from its description, loads the instructions when the task matches, and reads the supporting files only when it needs them.

That makes a skill more than a saved prompt and less than a new application. It is a portable piece of operating knowledge: small enough to inspect, specific enough to reuse, and structured so an agent does not need every instruction in every conversation.

The minimum skill is one folder and one file

The open Agent Skills specification defines a skill as a directory containing at least one file named exactly SKILL.md:

source-review/
├── SKILL.md
├── scripts/        # optional executable helpers
├── references/     # optional documentation
└── assets/         # optional templates and other resources

SKILL.md starts with YAML frontmatter and continues with Markdown instructions:

---
name: source-review
description: Reviews a draft against supplied sources and flags unsupported claims. Use when checking research articles, reports, or briefs before publication.
---

## Review process

1. List every factual claim in the draft.
2. Match each claim to a supplied source.
3. Mark unsupported claims instead of inventing support.
4. Return a table with claim, source, confidence, and next action.

The name identifies the skill. The description does the routing work: it tells a compatible agent what the skill does and when it applies. The Markdown body tells the agent what to do after it has chosen the skill.

The distinction matters. A beautifully written body cannot help if a vague description means the agent never loads it.

Skills load in stages

The key design idea is progressive disclosure. According to the Agent Skills overview, compatible agents generally load a skill in three stages:

1. Discovery: The agent sees lightweight metadata such as the name and description.
2. Activation: A matching task causes the full SKILL.md instructions to enter context.
3. Execution: The agent follows those instructions and opens bundled resources as needed.

Without this structure, fifty reusable workflows would mean fifty full instruction documents competing for context before the user asked a question. With it, the agent can keep a short catalogue of available capabilities and pay the full context cost only for the one it uses.

This also explains why smaller skills usually work better than an all-purpose handbook. A focused description routes more reliably, a short body costs less to load, and a narrow workflow is easier to test.

What belongs inside a skill

A skill should contain the knowledge the agent cannot safely or consistently infer for itself. Common ingredients include:

• a sequence of steps that must happen in a particular order;
• acceptance criteria or a review checklist;
• examples of valid inputs and outputs;
• rules for missing, ambiguous, or unsafe inputs;
• a template the finished work must follow;
• a script for deterministic or repetitive processing; and
• reference material the agent should consult only for relevant cases.

Imagine a release-notes skill. Its SKILL.md might explain how to classify changes, exclude internal maintenance, preserve issue links, and format the result. A script might collect commits. A reference file might define the product's public terminology. An asset might provide the release-note template.

The skill does not make the model permanently learn any of this. It makes the material available at the right moment.

A prompt, a skill, and an MCP server solve different problems

These terms often get collapsed into “ways to customize an AI,” but they have different jobs.

Use a prompt while the workflow is still changing every time. Turn it into a skill when the task, constraints, and output shape repeat. Reach for MCP when the agent must query a changing system or take an action through a governed interface.

A skill and MCP server can work together. A support-triage skill can define the review method while an MCP server provides current tickets. One supplies procedure; the other supplies capability and live state.

For the broader vocabulary, see LLM Mart's working taxonomy of prompts, skills, workflows, recipes, and agents.

Skills can be portable without being identical everywhere

The core format is open, and the Agent Skills project describes cross-product reuse as one of its goals. A conservative skill built from the standard fields and relative file references has the best chance of moving between compatible agents.

Clients can still extend the format. Claude Code, for example, supports features for invocation control, arguments, tool permissions, subagent execution, and dynamic context injection in its skills documentation. Those features can be useful, but they are not automatically portable to every agent that understands the base specification.

Treat portability as a design choice:

• keep the core workflow in standard Markdown;
• isolate client-specific behavior and document it;
• state required software or network access in compatibility metadata; and
• test the skill in every client you claim to support.

“It is a folder of Markdown” does not mean every host interprets every field the same way.

What skills do not guarantee

A skill makes behavior reusable. It does not make that behavior correct, safe, or mandatory.

Natural-language instructions remain instructions to a model. The agent can misunderstand them, the description can trigger on the wrong task, and a bundled script can contain ordinary software bugs. Some client fields pre-approve tools, but permission support varies and should never be mistaken for a universal sandbox.

Third-party skills add a supply-chain problem: instructions themselves can be malicious, and scripts can read files, call networks, or install dependencies. Inspect the complete bundle, not only the friendly description. Check the publisher, license, scripts, dependencies, requested tools, external destinations, and update path before granting access to sensitive work.

LLM Mart exposes trust information with listings because “available” and “safe for this environment” are different claims.

When a task deserves a skill

A task is a strong skill candidate when most of these are true:

• you have performed it more than once;
• the same corrections recur;
• order or completeness matters;
• the output follows a stable structure;
• examples improve reliability;
• the agent needs specific reference material; or
• another person should be able to reuse and review the method.

Do not create a skill just to avoid writing a two-sentence prompt. The maintenance cost is small, but it is not zero. Every skill adds metadata the agent must consider, files someone must own, and behavior that should be retested when the client changes.

Start with one narrow job. Write a description that names both the capability and its triggers. Keep the instructions concise, move detailed material into focused references, and test cases where the skill should stay out of the way. LLM Mart's guide to creating an agent skill walks that build end to end.

That is the useful mental model: an AI agent skill is a small, inspectable package of procedural knowledge, loaded on demand. It does not replace good prompts, secure tools, or human judgment. It makes a proven way of working easier to find and reuse.

Sources

• Agent Skills: overview
• Agent Skills: specification
• Claude Code: extend Claude with skills