Agent skills vs agents: what is the difference?
· 4 min read
People often mix up skills and agents, and many projects end up with a skill that is really a role, or an agent that is really a checklist. They are different tools. Using the right one makes your setup easier to maintain and easier for an AI tool to use correctly.
The short version
- A skill teaches an agent how to do one job well. It is a playbook.
- An agent is a specialist with a role, a process and boundaries. It is a teammate.
A skill is what you know. An agent is who does the work.
Side by side
| Skill | Agent | |
|---|---|---|
| Purpose | Teach one repeatable job | Take on a role and own a kind of task |
| File | skills/<name>/SKILL.md |
agents/<name>.md |
| Frontmatter | name, description, optional license, compatibility, allowed-tools |
name, description, optional tools and model |
| Extra files | references/, scripts/, assets/ |
None of its own |
| How it is chosen | The agent reads the skill’s description to decide when to load it | The main assistant reads the agent’s description to decide when to hand work over |
| Can use other things | Points to its own reference files and scripts | Can use skills |
What goes in a skill
A skill is narrow and procedural: “how to write release notes”, “how to review a diff”, “how to fill in this form”. It holds steps, rules, examples and supporting files. It does not say who the agent is or what it is allowed to touch. See how to write a SKILL.md.
What goes in an agent
An agent definition describes a role and how that role works. A useful structure:
- Role: who the agent is and what it owns.
- Responsibilities: what it should do.
- Boundaries: what it must not do or touch.
- Tool guidance: which tools to prefer, and
toolsin the frontmatter to limit them. Leavingtoolsempty means the agent inherits every tool. - Definition of done: how it knows it has finished.
The optional model field picks a model for the agent. In Claude Code the values are the aliases haiku, sonnet and opus, or inherit.
---
name: code-reviewer
description: Reviews changes for bugs and security issues. Use proactively after code is written or modified.
tools: Read, Grep, Glob
---
You are a senior reviewer. You never edit files; you report findings.
## Responsibilities
- Review the changes the user points to using the code-review skill.
- Report findings in order of severity.
## Boundaries
- Do not change code. Do not run commands that modify the project.
Because tools is limited to reading, this agent can look at code but never change it.
How they work together
An agent uses skills. The reviewer above does its work by following the code-review skill, and a second agent for pull requests could use the same skill. One skill, many agents, with the instructions kept in one place.
Resist copying a skill’s steps into an agent. Two copies drift apart and the agent ends up following the old one. Point to the skill instead. In Skill Builder, Skill reference and Agent reference blocks do exactly that: they link one document to another in the same project with a name and a one-line description, without duplicating the instructions.
Which should you write?
Write a skill when:
- you keep explaining the same procedure to the AI,
- the knowledge is about how to do something, and
- several agents or tasks could use it.
Write an agent when:
- you want a consistent specialist that owns a kind of task,
- it needs limits on tools or on what it may touch, or a particular model, and
- you want to delegate work to it instead of doing it in the main conversation.
If you are unsure, start with a skill. You can always wrap it in an agent later.
Common mistakes
- A role disguised as a skill. “You are a senior engineer who…” belongs in an agent.
- An agent with no boundaries. Say what it must not do, and limit its tools.
- A vague description. Both skills and agents are chosen by their description. Say when to use them.
- Copying instead of linking. Reference the skill; do not paste it.
Try it
In Skill Builder, a project holds your skills and agents together, links them, and exports the lot as ready-to-copy files. The interactive guide builds one of each. Then export for your AI tool.