An AI agent with tools can act, but tools alone don't tell it how your team does a job. An agent skill is a small, reusable guide that teaches the agent the steps, rules and traps for one kind of task, and it loads only when that task comes up.
Tools act, skills teach
A tool is a single capability the agent can call: run a terminal command, open a web page, send an API request, read a file. Tools answer 'what can the agent do?'. They say nothing about when to use them, in what order, or what 'done' looks like.
Ask an agent that only has tools to 'open a PR for the docs change' and it has to guess the rest. Which branch? Does the changelog need a line? Should the tests run first? Is there a PR template? A capable model makes reasonable guesses, but reasonable guesses vary from run to run and rarely match your team's actual process. That is where the mess comes from: wrong steps, steps in the wrong order, and a lot of improvising.
A skill fills that gap. It is written knowledge about how to do one particular job: which tools to reach for, the steps to follow, the rules that apply and the mistakes to avoid. The tools stay the same; the skill tells the agent how to combine them. If you've seen how the Model Context Protocol connects agents to tools (MCP vs API), skills sit one layer above that. MCP gives the agent new things it can do, and a skill teaches it a workflow that uses them.
What a skill looks like
In the Agent Skills format, a skill is a folder containing a file called SKILL.md. The file has two parts:
- Frontmatter: a short block of YAML at the top with a
nameand adescription. Both are required. The name is lowercase with hyphens, such as , and matches the folder's name.
Wondering how this was made? How we make these