What Are Agent Skills? Teaching AI Agents New Tricks

Agent skills are small packages of know-how that an AI agent can pick up when a task calls for them. Each skill is a folder with a SKILL.md file: a short name and description at the top, then plain instructions, plus optional scripts or reference files. The agent reads the description, decides whether the skill is relevant, and only then loads the full instructions.

Think of them as the onboarding docs you would hand a new teammate, written so an AI can use them on its own.

The problem agent skills solve

AI agents are generalists. A coding agent knows a lot about programming in general, but it does not know how your team writes release notes, which test command your project uses, or the five steps you always follow before deploying.

Without skills, you have two options, and both are awkward:

• Repeat yourself in every prompt. You paste the same checklist again and again, and sometimes you forget.
• Stuff everything into one giant instruction file. The agent reads all of it every time, even when 90% of it has nothing to do with the task at hand.

Skills sit in between. Knowledge lives in focused, named packages, and the agent pulls in only what the current task needs.

How agent skills work

The format is deliberately simple. A skill is a folder, and the only required file is SKILL.md.

The SKILL.md file

SKILL.md starts with a small block of YAML frontmatter containing two fields:

• name: a short identifier, such as release-notes or pdf-forms.
• description: one or two sentences saying what the skill does and when to use it.

Below the frontmatter is ordinary markdown: steps, rules, examples, and warnings. That is the part the agent follows once it decides the skill applies. If you want to see a full example, our guide on how to write a SKILL.md file walks through one line by line.

Optional extras

A skill folder can also hold supporting material:

• Scripts the agent can run, for example a script that validates a config file or converts a document.
• Reference files such as a style guide, an API cheat sheet, or a template.
• Assets like boilerplate files the agent copies into a project.

The instructions in SKILL.md point to these files, so the agent knows they exist and when to open them.

Loading only what is needed

The clever part is how skills are loaded. At the start of a session, the agent sees only each skill’s name and description. That costs very little context, so you can install many skills without slowing the agent down.

When a request matches a description, the agent reads the full SKILL.md. If the instructions mention a reference file or script, it opens that next. This layered approach is often called progressive disclosure: detail arrives only when it becomes useful.

Agent skills vs. other ways to guide an agent

Skills are one of several tools for shaping agent behavior. Here is how they compare.

Approach	What it is	Loaded when	Best for
Prompt	Instructions you type for one task	Once, for that request	One-off requests
Project instruction file	A file of rules the agent reads in a repository	Every session in that project	Rules that always apply to one project
Agent skill	A folder with SKILL.md and optional files	Only when the task matches	Reusable know-how across projects
MCP server	A connection to an external tool or data source	When the agent calls a tool	Live access to systems and data

Skills and MCP often get mixed up. The short version: a skill teaches the agent how to do something, while MCP gives it access to something. A skill might explain your deployment checklist; an MCP server might let the agent query your issue tracker. Our explainer on what MCP is goes deeper.

Where agent skills came from

Anthropic introduced Agent Skills for Claude, and the folder-plus-SKILL.md format has since been adopted more widely by other agent tools. Because a skill is just files, it is easy to share: you can keep skills in a Git repository, copy them between machines, or publish them for others.

That portability is a big part of the appeal. A well-written skill is not tied to one chat window or one project.

What makes a good skill

Not every piece of knowledge deserves to be a skill. The best ones share a few traits.

Focused on one job

A skill called write-changelog is easier for an agent to choose correctly than one called general-helpers. One clear job per skill keeps descriptions sharp and matching accurate.

A description that says when to use it

The description is what the agent reads when deciding. “Helps with documents” is too vague. “Fills in PDF forms and extracts form fields. Use when the user asks to complete or read a PDF form” tells the agent exactly when to reach for it.

Concrete, followable steps

Agents follow instructions literally. Numbered steps, exact commands, and short examples work better than general advice like “be careful with the database.”

Honest about edge cases

Mention the gotchas you have already learned the hard way: the flaky test to rerun, the file that must never be edited by hand, the API that rate-limits. That is exactly the kind of knowledge an agent cannot guess.

Practical examples of agent skills

Here are a few skills teams commonly write:

1. Code review checklist: what to look for before approving a change.
2. Testing conventions: how to run tests, where to put new ones, and what counts as done.
3. Commit and PR style: message format, branch naming, and what a description should include.
4. Document handling: reading or creating spreadsheets, PDFs, or slide decks.
5. Brand and writing style: tone, terminology, and formatting rules for user-facing text.
6. Framework know-how: patterns and pitfalls for a library your team uses heavily.

For a longer list with reasons behind each, see our roundup of essential skills for AI coding teams.

How to start using agent skills

Getting started does not require any special tooling.

1. Notice repetition. Look for instructions you keep retyping or mistakes agents keep making.
2. Write one small skill. Create a folder, add a SKILL.md with a clear name and description, and write the steps.
3. Test it on a real task. Ask the agent to do the thing and watch whether it picks up the skill and follows it.
4. Tighten the description. If the agent ignores the skill or uses it at the wrong time, the description usually needs work.
5. Grow slowly. Add skills as needs appear, not all at once.

Check your agent tool’s documentation for where it looks for skill folders, since locations differ between tools.

Agent skills in a team of agents

Skills become even more useful when several agents work together. A tester can carry a testing skill, a front-end developer a UI conventions skill, and a reviewer a review checklist, so each role brings the right expertise without everyone loading everything.

In BotQuarters, for example, you can give teammates skills from a skill library in one click, so the agents in your AI company share the same playbooks you would give a human team.

FAQ

What is a SKILL.md file?

A SKILL.md file is the core of an agent skill. It starts with YAML frontmatter containing a name and a description, followed by markdown instructions the agent follows when the skill is relevant. It can reference other files in the same folder, such as scripts or templates.

Are agent skills the same as MCP?

No. Agent skills package instructions and know-how, while MCP (Model Context Protocol) connects an agent to external tools and data sources. They work well together: a skill can explain how to use a tool that an MCP server provides.

Do agent skills use up a lot of context?

Not by default. Agents typically see only each skill’s name and description up front, and load the full instructions only when a task matches. That lets you install many skills while keeping the agent’s context lean.

Can I share agent skills with my team?

Yes. A skill is just a folder of files, so you can store it in a Git repository, copy it to other machines, or publish it. Since the format has been adopted beyond a single vendor, the same skill can often be reused across different agent tools.