You can hand an agent a hundred tools and it’ll still flail if it doesn’t know how to do a particular job well. Tools are capability. Skills are competence.
What a Skill actually is
A skill is, at its simplest, a folder:
pdf-skill/
SKILL.md # what this skill is + when to use it + how
scripts/ # helper code the agent can run
references/ # docs, examples, templates it can readThe SKILL.md is the heart of it — a short description that tells the agent when the skill
applies and how to carry out the task step by step.
The clever part: progressive disclosure
Here’s why skills scale where giant prompts don’t.
The agent doesn’t load every skill all the time. It reads the short descriptions first, and only pulls in a skill’s full instructions when the task actually calls for it.
So you can have dozens of skills installed without drowning the model in context. It’s like a craftsperson with a shelf of manuals — they don’t read all of them, they grab the right one when a specific job lands on the bench.
1. Task arrives: "fill out this PDF form"
2. Agent scans skill descriptions → "pdf-skill matches"
3. Agent loads pdf-skill/SKILL.md → now it knows the procedure
4. Agent runs the scripts, reads the references, does the jobSkills vs. tools vs. MCP
These get confused, so a quick map:
- Tools — actions the agent can take (run code, read a file).
- MCP — a standard for connecting tools and data to the agent.
- Skills — packaged know-how for doing a kind of task well, often using those tools.
A skill might say: “To convert this document, use the pdf tool like so, watch out for these
three gotchas, and format the output this way.” That procedural knowledge is the value.
Why you’ll care
As you build more capable agents, the bottleneck stops being raw model ability and becomes reliability on specific tasks. Skills are how you encode hard-won, repeatable expertise — once — so the agent gets it right every time.
We’ll build a skill from scratch in an upcoming post and video.