An agent skill is a reusable package of instructions that teaches an AI agent how to do one specific kind of task well. Skills let you give an agent detailed procedures without adding them to every prompt, because each skill loads only when its task comes up.
For example, suppose your team keeps a skill for reviewing experiment reports. When a user asks the agent to review a write-up, the agent loads the skill and checks four things in order: the primary metric, sample sizes, how conclusions treat noise, and a house checklist. When the same user asks for help with unrelated code, the skill stays unloaded and costs no context.
A skill can also include reference files, scripts, and templates. The agent opens those only when the instructions point to them.
Build better agents with Arize
Trace, evaluate, and learn. Build agents that work with Arize AX and start tracing your runs today.
Prefer open source? Try Arize Phoenix for self-hosted, open source agent observability.
Why agent skills matter
An agent needs some guidance on every task and other guidance only occasionally. Skills give you a place to put the occasional guidance so it is available without crowding every call.
Agent skills are useful for:
- Keeping prompts short: Move task-specific procedures out of the standing instructions so unrelated calls stay small.
- Sharing know-how: Package a procedure once and reuse it across agents and tools that support the format.
- Changing behavior safely: Version a skill like configuration and test each revision before you ship it.
- Debugging behavior: See in traces which skill loaded on a task and whether the agent followed it.
For practical authoring advice, see Arize’s guide on how to write effective AI agent skills.
How agent skills work
Start with the difference between what an agent is told permanently and what it needs now and then.
Permanent instructions cover identity, boundaries, and behavior that applies to every task. A skill covers the procedure for one kind of work, such as reviewing a document type, preparing a specific report, or running a house-style analysis.
If you put every procedure in the permanent prompt, every call gets longer. The model also has to weigh many instructions that have nothing to do with the current task. Packaging each procedure as a skill avoids that cost on unrelated tasks.
The SKILL.md file
In the format described by the Agent Skills specification, a skill is a folder. Its entry point is a SKILL.md file.
The file has two parts:
- Frontmatter: At least a name and a description. The agent uses the description to decide whether the skill is relevant.
- Body: The step-by-step instructions, written in Markdown.
The folder can also hold reference material, templates, and scripts that the body points to.
Progressive disclosure
Progressive disclosure, also called progressive loading, is the pattern that makes skills practical. The agent loads information in stages:
- At rest, the agent sees only each skill’s name and short description.
- When a task matches a description, the agent loads the full
SKILL.mdbody. - If the instructions point to a reference file or script for the current case, the agent opens that too.
Each stage costs context only when the previous stage showed it was needed. This means you can install many skills while keeping the base context small.
How to write an agent skill
Here is the experiment-report review skill from the opening example. The frontmatter tells the agent when to use it, and the numbered body tells it what to do.
---
name: experiment-report-review
description: Review an experiment report for stated metrics, sample sizes, and calibrated conclusions. Use when asked to review or critique an experiment write-up.
---
1. Confirm the primary metric and decision rule were stated before results.
2. Check every reported comparison includes its sample size.
3. Flag conclusions that treat noise-level differences as decisions.
4. Compare structure against references/checklist.md before commenting on style.
The skill folder also holds two supporting files:
- A checklist:
references/checklist.mdholds the house template. The agent opens it only at step 4. - A validation script: It confirms that required sections exist before the agent comments on style.
Loaded for a report review, these instructions focus the agent. Loaded for an unrelated coding task, they would only waste context.
That is why the description deserves as much care as the body. A vague description makes the skill load on the wrong tasks or miss the right ones.
Agent skills vs. tools, prompts, and system prompts
These terms overlap in everyday use, but each one does a different job.
A tool gives an agent the ability to take an action, such as calling an API, running code, or fetching a record. A skill gives the agent a procedure for using its abilities well: which steps to follow, what to check, and what good output looks like.
A skill may tell the agent to call tools or run a bundled script. Its core is still instructions, not execution capability.
A prompt is the input to a single model call. A skill is a stored artifact that gets selected and inserted into relevant calls over time. In that sense it is closer to versioned configuration than to a one-off instruction.
A system prompt holds guidance that applies to every task. Use this rule of thumb:
- Every task: If guidance applies everywhere, put it in the standing instructions.
- One kind of task: If guidance applies to one recognizable kind of task and would distract elsewhere, make it a skill.
The harness around the agent selects skills, loads resources, and enforces permissions. It determines how reliably the right skill loads. For that reason, test skill behavior inside the real harness rather than by pasting instructions into a chat window.
How to test whether a skill improves performance
Treat a skill like any other system change. “The instructions read better” is not evidence that the agent performs better.
A simple test plan looks like this:
- Build a small, fixed set of representative tasks for the skill’s stated purpose. Include edge cases.
- Add a few tasks where the skill should not trigger.
- Run each task with and without the skill. When you revise a skill, also run the old and new versions.
- Score every run with the same criteria.
Useful criteria include:
- Task success: Did the agent complete the task correctly?
- Targeted errors: Did the specific mistakes the skill claims to prevent go down?
- Added cost: How many extra steps or tokens did the skill add?
An evaluation harness is the repeatable setup that runs these cases and scores them. It turns a skill revision into a measurable comparison.
Test triggering, too
A skill that never loads does nothing. A skill that loads on unrelated tasks adds cost to every such call and can steer the agent in the wrong direction.
Review traces to see when the skill was selected, what it loaded, and whether the agent followed the loaded material. AI observability tooling makes this visible in production. The real task mix often reveals triggering mistakes that a tidy test set missed.
Limitations of agent skills
- Skills do not add capabilities: If no tool can fetch the data a procedure needs, better instructions will not complete the task.
- Skills can conflict: Two loaded skills may give incompatible procedures for the same task.
- Skills go stale: APIs, templates, and house rules change while the
SKILL.mdfile stays the same. - Bundled scripts execute: They need the same review, permissions, and sandboxing as any code an agent runs.
- Results may not transfer: A skill that helps on its author’s test cases may not help another team’s tasks or another model.
A portable file format does not mean portable results. Each team that adopts a skill should run its own comparison. For more on running agent code safely, see agent sandbox.
Frequently asked questions
What goes in a SKILL.md file?
A SKILL.md file contains frontmatter and instructions. The frontmatter has at least a name and a description of what the skill does and when to use it. The body holds the procedure in Markdown, and it can point to optional files for references, templates, or scripts.
How is an agent skill different from a tool?
A tool provides an executable capability, such as calling an API. A skill provides instructions for doing a kind of task well. A skill may direct the agent to use tools or bundled scripts in a particular order with particular checks.
Does loading more skills make an agent better?
No, not by itself. Each loaded skill uses context and may compete with other skills. Skills help when they trigger on the right tasks and their instructions measurably improve results on those tasks.
How do I know a skill revision helped?
Run the same fixed task set against the old and new versions and score both with unchanged criteria. Compare task success, targeted error rates, and cost. Then check triggering in traces so a gain on one task is not hiding new false triggers elsewhere.
Putting agent skills to work
Start with one procedure your agent performs often and inconsistently. Write it as a skill with a precise description, and keep the body to the steps that matter.
Before you ship it, record the skill version, the test set, and the with-and-without results. After you ship it, watch traces for triggering mistakes. If your harness records skill loads in its traces, a tracing tool such as Arize AX lets you review which skill loaded on each task and how the run turned out.
