Skills

A skill is just a folder full of instructions.

Imagine your job is to fix a truck, but you’ve never done that before. It’s a small job, just a small part that needs swapping. Still, there are loads of ways to get this wrong. It’s a big, complicated system and you don’t know very much about getting into it, much less making the repair.

But it’s not that bad: you’ve got a repair manual right in front of you. It’s thick, but if you read it carefully, you’ll be able to figure it out.

The repair manual is structured. It’s got a table of contents, helping you get your bearings in an unfamiliar book. It’s got sections and chapters.

It describes procedures, yes, but it also has diagrams and tables. It’s a lot of information but thanks to all the structure, if you’re patient, you can find whatever you need.

Agent Skills is a format for making manuals this same way, so that agents can figure out how to solve a problem, efficiently navigating through the exact path they need for just the information that solves their current problem.

Starting context matters

If I gave you the broken truck, the part, some wrenches, and no manual, your chances of making it all work go down. Maybe you and I get lucky: you’ve got some existing experience that gives you a head-start on the problem. Or maybe this truck breaks this way often, and there’s a torn off page in the glove box with some notes that steer you toward a solution.

It’s the same with an agent. Tell it very little, maybe you get lucky. If nothing else, agents are stubborn. They’ll just keep trying. But their “solution” may look nothing like what you want.

So luck isn’t good enough, and we don’t have to rely on it.

A skill lets us take the luck out of the equation by giving the agent everything it needs to know, up front.

You can write skills for anything you want done predictably, repeatedly, and correctly. Maybe that’s a process at work, maybe it’s a strategy for organizing your files.

Agents can’t read your mind. So give them a piece of your mind using skills.

Skill structure

First, SKILL.md.

This file is the first thing an agent considers in a skill. It’s formatted using markdown. This file acts as an introduction. Here you’ll explain how the skill is going to help the agent and give it high level instructions.

For simple problems, a single folder with a SKILL.md file is enough.

But for something more complex, skills can include more:

• references: more instructions
• scripts: code the agent can run to solve problems
• assets: templates, examples

You can describe the various files in your skill in that SKILL.md file, like a table of contents.

Why not throw everything into a single file?

Because remember, information is physical. The model driving your agent has limits. You don’t want to throw irrelevant information into the mix. This structure lets your agent touch only the information it needs for a specific task, and no more. That makes it faster and more efficient as it works.

What happens without instruction?